Ví dụ: danh bạ

Tra người dùng, nhóm và đơn vị của tổ chức như các bộ chọn hiển thị, và đổi một loạt id thành tên hiển thị.

Danh bạ là người dùng, nhóm và đơn vị của tổ chức, đúng như các bộ chọn trong ứng dụng hiển thị. Các lệnh dưới đây gọi API với tư cách một chủ thể dịch vụ:

export ORIGIN=https://agentflow.example.com
export AGENTFLOW_KEY=afk_…

Phản hồi đã được rút gọn; … đánh dấu phần lược bỏ. Một id thuộc tổ chức khác trả lời y như không tồn tại.

1. Người dùng

curl -sS -G "$ORIGIN/api/v1/users" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  --data-urlencode "q=lan" \
  --data-urlencode "is_active=true" \
  --data-urlencode "limit=20"

{
  "items": [
    {
      "id": "2c7a…",
      "email": "lan.nguyen@example.com",
      "display_name": "Nguyễn Thị Lan",
      "is_active": true,
      "group_names": ["Kế toán"],
      "unit_names": ["Chi nhánh Hà Nội"],
      "status": "active",
      …
    }
  ],
  "next_cursor": "…",
  "prev_cursor": null
}

q tìm theo một phần của tên hoặc email, không phân biệt hoa thường.
group_id và not_group_id nhận danh sách id nhóm, cách nhau bằng dấu phẩy. Một id sai định dạng trong danh sách trả 400 INVALID_QUERY_PARAMETER.
role_id và unit_id cần deployment.admin; thiếu quyền đó thì trả 403.
sort là email (mặc định), last_seen_at hoặc created_at; dir là asc hoặc desc. Không gửi dir thì email sắp tăng dần, hai mốc thời gian thì mới nhất trước.

Một người dùng:

curl -sS "$ORIGIN/api/v1/users/$USER_ID" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

{ "id": "2c7a…", "display_name": "Nguyễn Thị Lan", "email": "lan.nguyen@example.com", "is_active": true }

2. Nhóm

curl -sS -G "$ORIGIN/api/v1/groups" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  --data-urlencode "q=kế toán" \
  --data-urlencode "limit=10"

{
  "items": [
    {
      "id": "61e0…",
      "org_id": "9c41…",
      "name": "Kế toán",
      "description": null,
      "member_count": 2,
      "created_at": "…",
      "updated_at": "…"
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

q tìm theo một phần của tên nhóm, không phân biệt hoa thường.
member_count là số người dùng trong nhóm, trên mọi trang.
sort là name, mặc định tăng dần. Danh sách phân trang bằng limit, cursor và before, như mọi danh sách khác. Xem Phân trang.

Một nhóm, cùng các thành viên:

curl -sS "$ORIGIN/api/v1/groups/$GROUP_ID" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

{
  "id": "61e0…",
  "name": "Kế toán",
  "member_count": 2,
  "members": [
    { "id": "2c7a…", "email": "lan.nguyen@example.com", "display_name": "Nguyễn Thị Lan", "added_at": "…" },
    …
  ],
  …
}

members chỉ liệt kê người dùng.

3. Đơn vị

curl -sS -G "$ORIGIN/api/v1/units" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  --data-urlencode "q=hà nội" \
  --data-urlencode "limit=50"

{
  "items": [
    {
      "id": "4d19…",
      "code": "HN",
      "name": "Chi nhánh Hà Nội",
      "parent_id": "a3b7…",
      "archived": false,
      "archived_at": null,
      "depth": 1,
      "ancestor_names": ["Tổng công ty"],
      …
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

q tìm theo một phần của tên hoặc mã, không phân biệt hoa thường. include_archived=true lấy cả đơn vị đã lưu trữ.
sort là name (mặc định), code hoặc created_at; dir là asc hoặc desc. Không gửi dir thì name và code sắp tăng dần, created_at thì mới nhất trước.
Quay lại trang trước: gửi prev_cursor làm before, như mọi danh sách khác.

Một đơn vị:

curl -sS "$ORIGIN/api/v1/units/$UNIT_ID" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

{ "id": "4d19…", "name": "Chi nhánh Hà Nội", "code": "HN", "parent_id": "a3b7…", "is_archived": false }

Lưu ý tên trường: is_archived ở đây, archived trong danh sách.

4. Đổi id thành tên hiển thị

curl -sS -G "$ORIGIN/api/v1/identities" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  --data-urlencode "user_ids=2c7a…,8e42…" \
  --data-urlencode "group_ids=61e0…" \
  --data-urlencode "service_principal_ids=5b0e…"

{
  "users": [{ "id": "2c7a…", "name": "Nguyễn Thị Lan" }],
  "groups": [{ "id": "61e0…", "name": "Kế toán" }],
  "service_principals": [{ "id": "5b0e…", "name": "Invoice Import" }]
}

Mỗi mảng giữ đúng thứ tự id bạn gửi; một id gửi lặp lại chỉ xuất hiện một lần.
Một id không tìm thấy trong tổ chức thì vắng mặt, không phải null — như 8e42… ở trên. Hãy hiển thị chính id đó thay cho tên.
Tối đa 100 id khác nhau mỗi yêu cầu, tính gộp cả ba loại. Vượt quá: 422 VALIDATION_ERROR.
Một id sai định dạng: 400 INVALID_QUERY_PARAMETER, nêu tên tham số chứa nó.

Ví dụ: danh bạ

1. Người dùng

2. Nhóm

3. Đơn vị

4. Đổi id thành tên hiển thị

On this page