Hướng dẫn cài đặt và cấu hình — REST API Data Source

Yêu cầu hệ thống

Thành phần	Yêu cầu tối thiểu
Server Digiforce	Phiên bản >= 1.0, đã kích hoạt plugin `data-source-manager`
API bên ngoài	REST API trả về JSON, truy cập được từ server Digiforce
Mạng	Server Digiforce phải kết nối được đến API endpoint (mở firewall, VPN nếu cần)

Lưu ý

Plugin data-source-manager và error-handler cần được bật trước. Plugin REST API đăng ký error handler riêng để xử lý lỗi từ API bên ngoài.

Khi plugin được tải, nó đăng ký type http vào DataSourceManager, cho phép tạo data source dựa trên HTTP request.

Trường	Bắt buộc	Mô tả	Ví dụ
Data source name	Có	Tên định danh (chữ, số, gạch dưới)	`crm_api`
Display name	Có	Tên hiển thị trên giao diện	`CRM REST API`
Base URL	Có	URL gốc của REST API	`https://api.example.com/v1`
Headers	Không	Headers mặc định gửi kèm mọi request	`Authorization: Bearer xxx`
Variables	Không	Biến tùy chỉnh dùng trong template	`apiVersion: v2`
Timeout	Không	Thời gian chờ tối đa cho mỗi request (ms)	`30000`
Response type	Không	Kiểu response mong đợi	`json`

Mỗi collection trong REST API data source tương ứng với một nhóm endpoint. Bạn cần định nghĩa action mapping cho mỗi collection:

Action	HTTP Method	Mô tả	Ví dụ path
list	`GET`	Lấy danh sách bản ghi	`/users`
get	`GET`	Lấy một bản ghi theo ID	`/users/{{request.params.filterByTargetKey}}`
create	`POST`	Tạo bản ghi mới	`/users`
update	`PUT` / `PATCH`	Cập nhật bản ghi	`/users/{{request.params.filterByTargetKey}}`
destroy	`DELETE`	Xóa bản ghi	`/users/{{request.params.filterByTargetKey}}`

Thuộc tính	Mô tả
Method	HTTP method (GET, POST, PUT, PATCH, DELETE)
Path	Đường dẫn endpoint (hỗ trợ template variable)
Headers	Headers riêng cho action này (ghi đè headers mặc định)
Params	Query parameters gửi kèm
Content-Type	`application/json` hoặc `application/x-www-form-urlencoded`
Body	Nội dung body cho POST/PUT/PATCH
Response transformer	Template chuyển đổi response sang định dạng chuẩn
Error message transformer	Template trích xuất thông báo lỗi từ response

Plugin cung cấp action runAction cho phép gửi request thử nghiệm:

Cấu hình action (ví dụ: list)
Nhấn Run / Debug để gửi request thực tế đến API
Xem kết quả response, bao gồm:
- Raw response: Status, headers, body gốc
- Transformed response: Dữ liệu sau khi qua response transformer
- Inferred fields: Các trường được tự động nhận diện từ response

TIP

Chế độ Debug cho phép xem response ngay cả khi HTTP status là lỗi (4xx, 5xx), giúp bạn dễ dàng debug cấu hình.

Plugin có thể tự động nhận diện fields từ JSON response:

Plugin cũng tự động đoán filterTargetKey (primary key) bằng cách tìm các trường có tên id, nodeId, hoặc node_id.

Trong cấu hình path, headers, params và body, bạn có thể sử dụng template variables:

Variable	Mô tả	Ví dụ
`{{request.params.filter}}`	Bộ lọc từ Digiforce UI	—
`{{request.params.filterByTargetKey}}`	Giá trị primary key	`/users/{{request.params.filterByTargetKey}}`
`{{request.params.page}}`	Trang hiện tại	`?page={{request.params.page}}`
`{{request.params.pageSize}}`	Số bản ghi mỗi trang	`?limit={{request.params.pageSize}}`
`{{request.headers}}`	Headers của request gốc	—
`{{request.token}}`	Bearer token của user hiện tại	`Authorization: Bearer {{request.token}}`
`{{request.body}}`	Body của request (cho create/update)	—
`{{dataSourceVariables.xxx}}`	Biến tùy chỉnh của data source	`{{dataSourceVariables.apiVersion}}`
`{{$env.xxx}}`	Biến môi trường từ Environment Variables plugin	`{{$env.API_SECRET}}`

Response transformer cho phép bạn chuyển đổi response của API bên ngoài sang định dạng mà Digiforce hiểu:

json

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

Trường	Mô tả
`data`	Mảng bản ghi (cho list) hoặc object bản ghi (cho get)
`meta.count`	Tổng số bản ghi (dùng cho phân trang)