REST API

Kết nối một API JSON qua HTTPS với Fresco BI. Mỗi endpoint bạn khai báo thành một bảng: Fresco BI gọi endpoint, đi theo phân trang, lấy mảng record ở records path và import vào một bảng dữ liệu. Fresco BI chỉ gửi request GET, hoặc POST với JSON body do bạn cung cấp.

Tính năng	Hỗ trợ
Import	Có
DirectQuery	Không
SSL/TLS	Chỉ HTTPS, luôn kiểm tra chứng chỉ
SSH tunnel	Không
Cloud	Có
On-premises (qua Gateway)	Không

Điều kiện cần

Một API truy cập được từ internet qua HTTPS, bằng tên miền DNS (URL dùng địa chỉ IP bị từ chối).
Endpoint trả về JSON (application/json hoặc kiểu +json) chứa một mảng record.
Thông tin xác thực của API, nếu API yêu cầu.

Bước 1: Tạo thông tin xác thực chỉ đọc

Tạo một thông tin xác thực chỉ đọc được các endpoint cần dùng, ví dụ:

API key hoặc token có scope chỉ đọc;
một service user có role chỉ đọc (cho basic authentication);
một OAuth2 client được dùng grant client credentials, chỉ với các scope chỉ đọc.

Thông tin xác thực được lưu mã hóa và chỉ gửi trong header của request (hoặc trong request lấy token với OAuth2). Nó không bao giờ xuất hiện trong thông báo lỗi hay log.

Bước 2: Mở quyền truy cập mạng

Cloud. Nếu API có danh sách IP được phép, hãy cho phép các địa chỉ IP đi ra của Fresco BI (hướng dẫn bên cạnh form nguồn dữ liệu có liệt kê) ở cổng 443 (hoặc cổng trong base URL).

Fresco BI từ chối địa chỉ nội bộ, loopback và metadata, chỉ đi theo redirect tới cùng host và cổng (tối đa 3 lần), và phân trang bằng header Link phải ở lại host của base URL. Trình kết nối này không có SSH tunnel và không có kiểu On-premises (Gateway).

Bước 3: Điền thông tin

Form web cho REST API chưa có. Nguồn này nhận các thiết lập sau:

Base URL: chỉ https://, ví dụ https://api.example.com.
Endpoints: từ 1 đến 50, mỗi endpoint một bảng. Mỗi endpoint có các ô dưới đây.
Tên bảng: không trùng trong một nguồn.
Endpoint path và query: bắt đầu bằng /, ví dụ /v1/customers?page={page}&per_page={limit}. Chỉ được dùng {page}, {offset}, {cursor} và {limit}.
Records path: vị trí mảng record: $ (mặc định, toàn bộ câu trả lời) hoặc đường dẫn như $.data.items, tối đa 10 cấp.
Method: GET (mặc định) hoặc POST. JSON body (POST): một object hoặc mảng JSON, tối đa 10 KB, chỉ gửi với POST.
Headers: tối đa 20 header bổ sung. Không đặt được Authorization, Proxy-Authorization, Host, Cookie, Content-Length, Transfer-Encoding, Connection, Upgrade và TE ở đây.
Xác thực (mặc định none), xem bảng dưới.
Phân trang (mặc định none), xem bên dưới.
Page size ({limit}): từ 1 đến 1.000 (mặc định 100). Số trang đầu tiên: 0 hoặc 1 (mặc định 1). Số trang tối đa: từ 1 đến 100 (mặc định 100).
Số request mỗi giây: từ 1 đến 10 (mặc định 2).
Chứng chỉ CA (PEM): không bắt buộc, dùng khi chứng chỉ của API do CA riêng ký.

Xác thực	Bạn nhập
`none`	không cần gì
`api_key`	API key; gửi trong API key header (mặc định `X-API-Key`)
`bearer`	Bearer token; gửi dạng `Authorization: Bearer`
`basic`	Tên đăng nhập và Mật khẩu
`oauth2_client_credentials`	Token URL (https), Client ID, Client secret, Scope (không bắt buộc)

Với OAuth2, Fresco BI gửi grant_type=client_credentials tới token URL, kèm client ID và secret dạng HTTP Basic, rồi dùng access token nhận được làm bearer token và tự lấy token mới trước khi hết hạn.

Phân trang

Phân trang	Cách tìm trang tiếp
`none`	Mỗi endpoint một request
`page`	`{page}` tăng 1; dừng khi trang ngắn hơn page size
`offset`	`{offset}` tăng theo số record đã đọc; dừng khi trang ngắn
`cursor`	Giá trị ở Next cursor path đưa vào `{cursor}`; dừng khi rỗng hoặc lặp lại
`link`	Đi theo header `Link: <...>; rel="next"`

Với page, offset và cursor, mọi endpoint path phải chứa biến tương ứng. Mọi kiểu đều dừng khi gặp trang rỗng.

Giới hạn

Tối đa 100 trang mỗi endpoint. Nếu còn dữ liệu sau Số trang tối đa, lần tải báo lỗi thay vì import một phần dữ liệu.
Tối đa 100.000 record mỗi bảng, 50 MB mỗi câu trả lời và 500 MB mỗi lần tải.
Cột được suy ra từ 1.000 record đầu; tối đa 500 cột. Object lồng nhau được làm phẳng một cấp (customer_name); object sâu hơn và mảng giữ dạng văn bản JSON.
Câu trả lời 429 được thử lại tối đa 3 lần, theo Retry-After tối đa 60 giây.

Khắc phục sự cố

Máy chủ từ chối tài khoản hoặc mật khẩu. API trả 401 hoặc 403, hoặc request lấy token thất bại. Kiểm tra kiểu xác thực, thông tin xác thực và tên API key header.
Không tìm thấy database hoặc đối tượng này trên máy chủ. Endpoint trả 404. Kiểm tra base URL và endpoint path.
Thông tin kết nối chưa hợp lệ: kiểm tra lại các ô được đánh dấu. API trả một mã 4xx khác (thường do tham số query sai), hoặc URL không phải https:// với tên miền DNS.
Nguồn trả về kiểu dữ liệu trình kết nối chưa hỗ trợ. Câu trả lời không phải JSON, hoặc records path không trỏ tới một mảng. Kiểm tra records path.
Vượt giới hạn kích thước hoặc số kết nối đồng thời. Quá nhiều trang, record hoặc cột, câu trả lời quá 50 MB, hoặc vẫn bị 429 sau khi thử lại. Thu hẹp endpoint, tăng page size hoặc giảm số request mỗi giây.
Địa chỉ máy chủ thuộc dải bị chặn (nội bộ, loopback hoặc metadata). Database trong mạng nội bộ cần kết nối On-premises qua Gateway. Host phân giải ra địa chỉ nội bộ, URL dùng địa chỉ IP, hoặc redirect hay trang Link trỏ sang host khác.
Không phân giải được tên máy chủ (DNS). Kiểm tra lại ô Máy chủ. Kiểm tra host trong base URL.
Không mở được kết nối tới máy chủ và cổng này. Kiểm tra máy chủ, cổng, và firewall đã cho phép IP của Fresco BI chưa. API đang lỗi, trả mã 5xx, hoặc chặn các địa chỉ IP đi ra của Fresco BI (hướng dẫn bên cạnh form nguồn dữ liệu có liệt kê).
Không thiết lập được kết nối SSL với chế độ đã chọn. Kiểm tra chế độ SSL và chứng chỉ CA. Chứng chỉ của API không được tin cậy; dán CA của nó vào ô chứng chỉ CA.