Mở rộng đối tượng liên quan

Đối tượng tham chiếu tới các đối tượng liên quan bằng ID: một thẻ có owner_id và collection_id. Khi cần chính đối tượng liên quan, bạn không phải gửi yêu cầu thứ hai. Hãy yêu cầu nó bằng expand[], và nó sẽ có ngay trong cùng phản hồi, bên trong expanded:

curl -G https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "expand[]=owner" \
  --data-urlencode "expand[]=collection"

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "owner_id": 7,
  "collection_id": 3,
  "expanded": {
    "owner": {"id": 7, "username": "anna", "display_name": "Anna Petrova", "role": "editor"},
    "collection": {"id": 3, "name": "support", "title": "Support"}
  }
}

Ví dụ đã được rút gọn: đối tượng được mở rộng có mọi trường của thao tác đọc riêng của nó. Các trường ID vẫn ở nguyên chỗ cũ, nên mã không dùng expand[] nhận được phản hồi giống như trước.

Các thao tác sau mở rộng đối tượng liên quan. Đường dẫn có dấu chấm mở rộng một liên kết của đối tượng đã được mở rộng, ví dụ collection.default_owner là người phụ trách mặc định của bộ sưu tập chứa thẻ.

Thao tác	Đường dẫn
`GET /v1/cards/{card_id}`, `GET /v1/cards-by-external-id/{external_id}`	`collection`, `owner`, `verifiers`, `folders`, `collection.default_owner`
`GET /v1/cards`	`data.collection`, `data.owner`, `data.verifiers`, `data.folders`
`GET /v1/jobs/{job_id}`	`card`, `card.collection`, `card.owner`, `card.verifiers`, `card.folders`
`GET /v1/jobs`	`data.card`
`GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id}`	`event`
`GET /v1/webhooks/{webhook_id}/deliveries`	`data.event`
`GET /v1/push/sources/{source_id}/documents/{external_id}`	`card`, `card.collection`, `card.owner`, `card.verifiers`, `card.folders`
`GET /v1/push/sources/{source_id}/syncs/{sync_number}/documents`	`data.card`

Mỗi liên kết có dạng giống như trong thao tác đọc đối tượng liên quan:

Liên kết	Nội dung trong `expanded`
`collection`	Bộ sưu tập, như trong `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Người dùng, như trong `GET /v1/users`: dòng đầy đủ cho bên gọi được phép quản lý người dùng, dòng rút gọn (`brief=true`, chỉ người dùng đang hoạt động) cho các bên gọi khác. `verifiers` là danh sách theo thứ tự của `verifier_ids`.
`folders`	Các thư mục của thẻ trong bộ sưu tập của nó mà bên gọi có thể xem, như trong `GET /v1/folders/{folder_id}` không có `path`.
`card`	Thẻ, như một phần tử của `GET /v1/cards`.
`event`	Sự kiện, như trong `GET /v1/webhook-events/{event_id}`.

Trong danh sách

Với danh sách, hãy bắt đầu đường dẫn bằng data.: nó áp dụng cho mọi phần tử của trang. Quy tắc này như nhau cho danh sách trả về một mảng, chẳng hạn GET /v1/cards, và cho danh sách giữ các phần tử trong một trường, chẳng hạn jobs của GET /v1/jobs hoặc items của nhật ký các lần gửi.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "expand[]=data.owner" \
  --data-urlencode "expand[]=data.collection"

Sursa tải mỗi liên kết cho cả trang cùng một lúc, nên mở rộng một danh sách tốn khoảng bằng một yêu cầu bổ sung, chứ không phải một yêu cầu cho mỗi phần tử. Con trỏ của trang tiếp theo không phụ thuộc vào expand[], nên bạn có thể yêu cầu các liên kết khác ở trang tiếp theo.

Quy tắc

Tối đa 10 đường dẫn cho mỗi yêu cầu, mỗi đường dẫn gồm tối đa 2 thành phần: data.owner trong danh sách, collection.default_owner trên một đối tượng.
Đường dẫn không xác định, hơn 10 đường dẫn hoặc đường dẫn gồm hơn 2 thành phần trả về 400 với mã api.expand_invalid. details.path cho biết đường dẫn, còn details.reason cho biết lỗi là gì: unknown_path, too_deep hoặc too_many_paths.
Đối tượng liên quan chỉ được mở rộng cho bên gọi có thể đọc nó bằng yêu cầu riêng. Khóa cần phạm vi quyền của thao tác đó: cards:read cho thẻ, bộ sưu tập và thư mục, users:read cho người dùng, webhooks:manage cho sự kiện. Đối tượng cũng phải hiển thị với bên gọi, chẳng hạn nằm trong các bộ sưu tập của một khóa chỉ được giới hạn trong một số bộ sưu tập. Nếu không, liên kết được mở rộng thành null, và trong verifiers người dùng được thay bằng null ở đúng vị trí của mình. ID của nó vẫn được trả về. folders chỉ liệt kê các thư mục mà bên gọi có thể xem.
Khóa của nguồn tùy chỉnh không đọc thẻ, nên với khóa này card của một tài liệu luôn là null. Để lấy thẻ, hãy gọi các endpoint đẩy dữ liệu bằng khóa API có phạm vi import:write và cards:read.
Sự kiện cũ hơn 30 ngày và sự kiện của một lần gửi thử được mở rộng thành null.
expand[] chỉ thêm dữ liệu vào phản hồi. Nó không bao giờ thay đổi việc yêu cầu thực hiện.