Giao diện
Nguồn dữ liệu (Dynamic Action)
Trang này để làm gì
Khai báo các nguồn dữ liệu động dùng trong Dynamic Form, Zalo Mini App và Vibe Code Studio - ví dụ danh sách chi nhánh cho khách chọn, kết quả tra cứu đơn hàng, hay dữ liệu lấy thời gian thực từ hệ thống khác.
Đường dẫn: → (/dynamic-action/data-source)
Màn hình danh sách
- Cột Loại - nguồn lấy dữ liệu từ đâu: DataHub (bảng nội bộ) hoặc API (hệ thống bên ngoài).
- Cột Cấu trúc dữ liệu - nguồn trả về Dạng danh sách (nhiều dòng) hay Dạng chi tiết (một bản ghi). Đây là lựa chọn quan trọng nhất, xem giải thích bên dưới.
- Nút Tạo mới - khai báo nguồn dữ liệu mới.
Hai trục phân loại
Mỗi nguồn dữ liệu được xác định bởi hai lựa chọn độc lập nhau. Hiểu đúng hai trục này là hiểu xong phần khó nhất của Dynamic Action.
Hai trục kết hợp thành bốn cách dùng:
| Loại × Cấu trúc | Ví dụ thực tế |
|---|---|
| DataHub + Danh sách | Dropdown chọn chi nhánh, lấy từ bảng chi_nhanh |
| DataHub + Chi tiết | Tra điểm tích luỹ của khách theo số điện thoại |
| API + Danh sách | Danh sách bác sĩ còn lịch trống hôm nay, gọi sang hệ thống phòng khám |
| API + Chi tiết | Tra trạng thái vận đơn theo mã, gọi sang hãng vận chuyển |
Chọn sai cấu trúc là lỗi khó nhận ra
Nguồn Dạng danh sách gắn vào chỗ cần một bản ghi sẽ hiển thị dòng đầu tiên và im lặng bỏ qua phần còn lại. Ngược lại, nguồn Dạng chi tiết gắn vào dropdown chỉ cho ra đúng một lựa chọn.
Không có thông báo lỗi nào - form vẫn chạy, chỉ là kết quả sai. Hãy xác định trước bạn cần một hay nhiều trước khi tạo nguồn.
Nguồn DataHub - các bước
- Chuẩn bị bảng trong Data Hub Bảng cần có đủ cột bạn muốn dùng. Xem Tạo bảng.
- Tạo nguồn mới, chọn Loại = DataHub Trỏ tới bảng vừa chuẩn bị.
- Chọn cấu trúc trả vềDạng danh sách nếu để khách chọn; Dạng chi tiết nếu để tra cứu một bản ghi.
- Với dạng chi tiết: khai báo điều kiện tra cứu Ví dụ tra theo cột
phonekhớp với số điện thoại của khách đang mở form. - Chọn trường hiển thị và trường giá trị Trường hiển thị là cái khách nhìn thấy (Chi nhánh Quận 1); trường giá trị là cái được lưu (
CN-Q1).
Vì sao nên lưu mã thay vì lưu tên
Tên chi nhánh có thể đổi, có thể viết hoa khác nhau, có thể thừa khoảng trắng. Mã thì ổn định. Lưu mã giúp dữ liệu cũ vẫn khớp sau khi đổi tên hiển thị, và tránh việc cùng một chi nhánh bị đếm thành hai vì khác cách viết.
Nguồn API - các bước
- Chuẩn bị endpoint từ hệ thống của bạn Cần URL, phương thức (GET/POST) và cách xác thực. Phần này thường do bộ phận kỹ thuật cung cấp.
- Tạo nguồn mới, chọn Loại = API Điền URL và cấu hình header xác thực nếu có.
- Khai báo tham số đầu vào Ví dụ mã đơn hàng khách nhập vào form sẽ được truyền sang API.
- Ánh xạ trường từ kết quả trả về API trả JSON; bạn chỉ định trường nào trong JSON tương ứng với trường hiển thị và trường giá trị.
- Kiểm tra bằng một lượt gọi thử Xác nhận dữ liệu về đúng và đủ trước khi gắn vào form thật.
Nguồn API phụ thuộc vào hệ thống bên ngoài
API chậm hoặc lỗi sẽ làm form của khách bị treo ở bước đó. Với dữ liệu ít thay đổi (danh sách chi nhánh, danh mục sản phẩm), hãy đồng bộ về Data Hub theo lịch rồi dùng nguồn DataHub - vừa nhanh vừa không phụ thuộc.
Chỉ dùng API trực tiếp khi dữ liệu buộc phải mới theo thời gian thực, ví dụ số lượng tồn kho hoặc khung giờ còn trống.
So sánh nhanh khi phân vân
| Câu hỏi | Chọn DataHub | Chọn API |
|---|---|---|
| Dữ liệu đổi mấy lần một ngày? | Ít, theo ngày hoặc theo tuần | Liên tục, theo phút |
| Sai lệch vài phút có chấp nhận được? | Có | Không |
| Hệ thống nguồn có sẵn API chưa? | Không cần | Bắt buộc phải có |
| Cần bộ phận kỹ thuật hỗ trợ? | Không | Có |
Lỗi thường gặp
| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
| Dropdown trống | Bảng nguồn không có dòng nào, hoặc điều kiện lọc loại hết | Mở bảng Data Hub kiểm tra dữ liệu thật |
| Dropdown chỉ có một lựa chọn | Nguồn đang để Dạng chi tiết | Đổi sang Dạng danh sách |
| Tra cứu luôn không ra kết quả | Điều kiện tra cứu so sánh sai định dạng (số điện thoại có +84 và không có) | Chuẩn hoá định dạng ở cả hai phía |
| Form treo khi tới bước tra cứu | API bên ngoài không phản hồi | Kiểm tra endpoint; cân nhắc chuyển sang nguồn DataHub |