Báo cáo Nghiên cứu: 4 Cơ chế Liên kết Dữ liệu Lark Base (Bitable)

Tác giả: Gemini CLI - Research Engineer Ngày lập: 11/04/2026 Mục tiêu: Hiểu sâu cơ chế liên kết dữ liệu Lark để thiết kế công cụ dump/migration.

Cơ chế 1: Link field (Liên kết 1 chiều / 2 chiều)

1. Bản chất

Lark định nghĩa Link field là việc thiết lập quan hệ tham chiếu giữa các record của 2 bảng trong cùng một Base.

SingleLink (1 chiều): Bảng A trỏ sang bảng B. Bảng B không tự động hiện field ngược lại.
DuplexLink (2 chiều): Bảng A trỏ sang bảng B, đồng thời tự động tạo/liên kết với 1 field tại bảng B trỏ ngược lại A.

2. API endpoints liên quan

Endpoint	Method	Scope cần	Trả về gì
`/open-apis/bitable/v1/apps/:app_token/tables/:table_id/fields`	GET	`bitable:app:readonly`	Danh sách field kèm metadata link

3. Data fields trong response

Field path	Type	Ý nghĩa	Bắt buộc
`data.items[].type`	int	18 (SingleLink) hoặc 21 (DuplexLink)	Y
`data.items[].property.table_id`	string	ID của bảng đích được liên kết	Y
`data.items[].property.multiple`	bool	Cho phép chọn nhiều record (N:N) hay không	Y
`data.items[].property.back_field_id`	string	ID của field phản chiếu ở bảng đích (chỉ có ở type 21)	N

4. Sample response JSON thực tế

{
  "type": 21,
  "field_name": "Liên kết Dự án",
  "property": {
    "table_id": "tblXyZ123",
    "multiple": true,
    "back_field_id": "fldAbC456"
  }
}

5. Cách trace / đọc metadata

Gọi API list fields của bảng A.
Tìm field có type: 18 hoặc 21.
Lấy table_id trong property để xác định bảng đích.
Nếu là type: 21, dùng back_field_id để tìm field tương ứng ở bảng đích, giúp xác định "bản phản chiếu".

6. Giới hạn

Đọc được qua API:

Cấu trúc liên kết, bảng đích, field ngược lại.
Dữ liệu trong record (trả về mảng record_id của các record được link).

KHÔNG đọc được qua API:

Không hỗ trợ Cross-base link (phải dùng Sync Table để thay thế).

7. Link docs chính thức

Bitable Field Overview

Cơ chế 2: Sync table (Bảng đồng bộ Cross-base)

1. Bản chất

Cơ chế cho phép "vác" một View hoặc một Table từ Base A sang Base B. Dữ liệu tại Base B là Read-only và cập nhật theo chu kỳ (mặc định ~30 phút hoặc trigger manual).

2. API endpoints liên quan

Endpoint	Method	Scope cần	Trả về gì
`/open-apis/bitable/v1/apps/:app_token/tables`	GET	`bitable:app:readonly`	Danh sách bảng kèm flag sync

3. Data fields trong response

Field path	Type	Ý nghĩa	Bắt buộc
`data.items[].is_sync`	bool	`true` nếu là bảng đồng bộ	Y
`data.items[].source_app_token`	string	App Token của Base gốc	N (chỉ khi is_sync=true)
`data.items[].source_table_id`	string	Table ID của bảng gốc	N (chỉ khi is_sync=true)

4. Sample response JSON thực tế

{
  "table_id": "tblSync456",
  "name": "Báo cáo Tổng hợp (Sync)",
  "is_sync": true,
  "source_app_token": "appBaseOrigin789",
  "source_table_id": "tblOrigin123"
}

5. Cách trace / đọc metadata

Duyệt danh sách bảng qua API List Tables.
Nếu is_sync: true, lưu lại source_app_token và source_table_id.
Đây là "Downstream". Bạn cần truy cập "Upstream" (Base gốc) để hiểu logic gốc của dữ liệu.

6. Giới hạn

Đọc được qua API:

Biết bảng nào là bảng sync, nguồn từ đâu.

KHÔNG đọc được qua API:

Lịch sync: Không biết bao lâu sync một lần, lần sync cuối là khi nào.
Mapping field: Không biết bảng sync này chỉ lấy 5/10 field hay lấy hết (phải so sánh cấu trúc field 2 bên thủ công).
Cách bù: Dùng Computer Use mở "Cài đặt bảng" -> "Đồng bộ dữ liệu" để xem cấu trúc mapping và lịch trình.

7. Link docs chính thức

Bitable Table Metadata

Cơ chế 3: Lookup field (Truy xuất dữ liệu qua Link)

1. Bản chất

Sử dụng một Link field có sẵn để "mượn" dữ liệu từ bảng đích hiện lên bảng hiện tại.

Lookup: Lấy giá trị thô.
Rollup: Lấy giá trị sau khi qua hàm tính toán (SUM, COUNT, AVG...). Trong API, cả hai thường dùng chung type 19.

2. API endpoints liên quan

Endpoint	Method	Scope cần	Trả về gì
`/open-apis/bitable/v1/apps/:app_token/tables/:table_id/fields`	GET	`bitable:app:readonly`	Chi tiết property của field

3. Data fields trong response

Field path	Type	Ý nghĩa	Bắt buộc
`data.items[].type`	int	19	Y
`data.items[].property.link_field_id`	string	ID của Link field làm cầu nối	Y
`data.items[].property.source_field_id`	string	ID của field tại bảng đích muốn lấy dữ liệu	Y
`data.items[].property.rollup_function`	string	Hàm tính toán (nếu có - SUM, MAX, MIN...)	N

4. Sample response JSON thực tế

{
  "field_name": "Tổng lương dự án",
  "type": 19,
  "property": {
    "link_field_id": "fldLinkProject",
    "source_field_id": "fldSalary",
    "rollup_function": "SUM"
  }
}

5. Cách trace / đọc metadata

Lookup field X -> tìm link_field_id -> tìm bảng đích -> tìm source_field_id ở bảng đích.
Lark cho phép Lookup của Lookup, tạo thành một chuỗi (Chain). Cần đệ quy để trace về field "gốc" (gốc thường là Text, Number hoặc Date).

6. Giới hạn

Đọc được qua API:

Toàn bộ logic liên kết và hàm tính toán.

KHÔNG đọc được qua API:

Dữ liệu Lookup trong Record API thường là mảng giá trị hoặc mảng object, đôi khi không parse được ngay nếu là dữ liệu phức tạp.

7. Link docs chính thức

Bitable Field Property

Cơ chế 4: Automation (Business Logic)

1. Bản chất

Hệ thống Workflow tự động hóa trong Base. Chạy dựa trên Trigger (Thay đổi field, định kỳ, Form submit) và thực hiện Action (Update record, Gửi tin nhắn, Chạy Script).

2. API endpoints liên quan

Endpoint	Method	Scope cần	Trả về gì
`/open-apis/bitable/v1/apps/:app_token/workflows`	GET	`bitable:app`	Chỉ trả về ID và Title

3. Data fields trong response

Field path	Type	Ý nghĩa	Bắt buộc
`data.workflows[].workflow_id`	string	ID định danh automation	Y
`data.workflows[].title`	string	Tên automation	Y
`data.workflows[].status`	string	`Enable` hoặc `Disable`	Y

4. Sample response JSON thực tế

{
  "data": {
    "workflows": [
      {
        "workflow_id": "7293459700012345678",
        "status": "Enable",
        "title": "Tự động tính lương khi duyệt TTS"
      }
    ]
  }
}

5. Cách trace / đọc metadata

API hiện tại CỰC KỲ HẠN CHẾ. Nó chỉ cho biết "Base này có automation tên là X".
Không thể biết Trigger là gì, Action làm gì qua API public v1.

6. Giới hạn

Đọc được qua API:

ID, Tên, Trạng thái bật/tắt.

KHÔNG đọc được qua API (Critical):

Triggers: Điều kiện để chạy.
Actions: Logic nghiệp vụ (ví dụ: nếu field A = 'Done' thì cộng 1 vào field B).
Scripts: Mã nguồn Javascript trong "Run Script" action là hoàn toàn không thể đọc.
Cách bù:
1. Sử dụng Computer Use/UI Scrape: Vào Base Settings -> Automation.
2. Screenshot/OCR logic từng bước.
3. Lark không có nút Export Automation ra JSON cho người dùng cuối.

7. Link docs chính thức

List Bitable Automations

Kết luận cho việc thiết kế Dump Tool

Schema (Cơ chế 1, 3): Có thể tự động hóa 100% qua API.
Cross-base (Cơ chế 2): Tự động hóa được việc phát hiện quan hệ, nhưng cần thêm quyền truy cập vào các Base "Upstream".
Logic (Cơ chế 4): BẮT BUỘC dùng Computer Use / Manual capture. Đây là "hộp đen" đối với API. Nếu nhân viên cũ thiết kế "1 trigger chạy nhiều việc", logic bên trong sẽ rất phức tạp và chỉ có thể đọc được qua UI.