Giao diện

Câu hỏi thường gặp (FAQ) — REST API Data Source ​

Cài đặt và cấu hình ​

Không thể kết nối đến API bên ngoài, báo lỗi timeout? ​

Nguyên nhân phổ biến:

  1. API bên ngoài không truy cập được từ server Digiforce (firewall, VPN)
  2. URL không chính xác (sai protocol, host, port)
  3. Timeout quá ngắn cho API phản hồi chậm

Cách khắc phục:

  • Kiểm tra kết nối từ server: curl -v https://api.example.com/v1/health
  • Đảm bảo Base URL đúng, bao gồm protocol (https://)
  • Tăng giá trị Timeout trong cấu hình data source
  • Kiểm tra proxy settings nếu server nằm sau proxy

API yêu cầu xác thực, cấu hình như thế nào? ​

Plugin hỗ trợ nhiều phương thức xác thực thông qua Headers:

// Bearer Token
Authorization: Bearer {{$env.API_TOKEN}}

// API Key
X-API-Key: {{$env.API_KEY}}

// Basic Auth
Authorization: Basic {{$env.API_BASIC_CREDENTIALS}}

Bảo mật

Nên lưu token/key trong Environment Variables ($env) thay vì ghi trực tiếp vào cấu hình. Sử dụng plugin environment-variables để quản lý.

Response transformer không hoạt động đúng? ​

Response transformer sử dụng template syntax. Kiểm tra:

  1. Đường dẫn JSON chính xác: dùng {{rawResponse.body.xxx}} (không phải rawResponse.data)
  2. Sử dụng Debug mode để xem raw response trước khi viết transformer
  3. Kết quả phải có dạng { data: [...], meta: { count: N } } cho action list

Ví dụ: API trả về { results: [...], pagination: { total: 100 } }:

json
{
  "data": "{{rawResponse.body.results}}",
  "meta": {
    "count": "{{rawResponse.body.pagination.total}}"
  }
}

Làm sao truyền token của user hiện tại sang API bên ngoài? ​

Sử dụng template variable {{request.token}} trong Headers:

Authorization: Bearer {{request.token}}

Điều này cho phép mỗi user gọi API bên ngoài với token riêng của họ, hữu ích khi API bên ngoài cũng dùng cùng hệ thống xác thực.

Sử dụng hàng ngày ​

Dữ liệu có được cache không? ​

Không. Plugin gọi HTTP request trực tiếp đến API bên ngoài mỗi lần có request từ Digiforce. Dữ liệu luôn phản ánh trạng thái mới nhất từ API.

Có thể cấu hình chỉ một số action (ví dụ chỉ đọc, không ghi)? ​

Có. Bạn chỉ cần cấu hình action nào bạn muốn hỗ trợ. Plugin kiểm tra availableActions() và chỉ cho phép các action đã được cấu hình. Ví dụ: chỉ cấu hình list và get để tạo collection read-only.

Phân trang hoạt động như thế nào? ​

Plugin truyền page và pageSize từ Digiforce UI vào template context. Bạn cần map chúng vào query params hoặc body phù hợp với API bên ngoài:

// Ví dụ: API dùng offset/limit
?offset={{(request.params.page - 1) * request.params.pageSize}}&limit={{request.params.pageSize}}

// Ví dụ: API dùng page/per_page
?page={{request.params.page}}&per_page={{request.params.pageSize}}

Tổng số bản ghi cần được map trong response transformer (meta.count) để phân trang hiển thị đúng.

Có thể sử dụng biến môi trường trong cấu hình không? ​

Có. Sử dụng {{$env.TÊN_BIẾN}} trong bất kỳ trường nào hỗ trợ template. Plugin lấy giá trị từ app.environment.getVariables(), tức biến được quản lý bởi plugin environment-variables.

Làm sao gửi dữ liệu dạng form-encoded thay vì JSON? ​

Đặt Content-Type của action thành application/x-www-form-urlencoded. Plugin sẽ tự động chuyển body thành URL-encoded string thông qua URLSearchParams.

Lỗi thường gặp ​

Lỗi "Failed to request external http datasource"? ​

Đây là lỗi chung khi HTTP request đến API bên ngoài thất bại. Kiểm tra:

  1. API bên ngoài có đang hoạt động không
  2. Thông tin xác thực còn hợp lệ không (token hết hạn?)
  3. URL và method có đúng không
  4. Sử dụng Debug mode để xem chi tiết request và response

Lỗi "request config of action xxx is not set"? ​

Action bạn đang gọi chưa được cấu hình cho collection này. Ví dụ: cố tạo bản ghi (create) nhưng chưa định nghĩa action create trong collection settings.

Response trả về nhưng không thấy dữ liệu? ​

Kiểm tra Response transformer:

  • Đảm bảo data trỏ đến đúng vị trí trong response body
  • Dùng Debug mode để so sánh raw response và transformed response
  • Nếu response là object (không phải array), action get phải trả về data là object, list phải trả về array

WhiteList/BlackList không có tác dụng? ​

WhiteList và BlackList chỉ áp dụng cho values trong create/update:

  • WhiteList: Nếu có, chỉ các trường trong danh sách mới được gửi
  • BlackList: Nếu có, các trường trong danh sách bị loại bỏ
  • Thứ tự: WhiteList áp dụng trước, rồi BlackList

Vấn đề khác ​

So sánh với plugin PostgreSQL Data Source? ​

Tiêu chíPostgreSQL PluginREST API Plugin
Nguồn dữ liệuDatabase trực tiếpHTTP API
Auto-detect fieldsCó (introspect schema)Có (suy luận từ JSON response)
Cấu hìnhĐơn giản (connection string)Phức tạp hơn (endpoint + transformer)
Hiệu năngNhanh (truy vấn SQL trực tiếp)Phụ thuộc vào API bên ngoài
Filter/SortHỗ trợ đầy đủ (SQL)Phụ thuộc vào API hỗ trợ

Có thể kết nối nhiều REST API cùng lúc không? ​

Có. Tạo nhiều data source với type http, mỗi cái trỏ đến một API khác nhau. Không có giới hạn số lượng.

API trả về XML thay vì JSON? ​

Plugin hiện chỉ hỗ trợ JSON response. Nếu API trả về XML, bạn cần:

  • Dùng middleware/proxy để chuyển đổi XML → JSON trước khi Digiforce gọi
  • Hoặc liên hệ đội phát triển API để cung cấp endpoint JSON