展开关联对象

对象通过 ID 引用关联对象：卡片有 owner_id 和 collection_id。需要关联对象本身时，不必再发一个请求。用 expand[] 指定要展开的对象，它会出现在同一个响应的 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"}
  }
}

示例有所删减：展开的对象包含其自身读取操作返回的全部字段。ID 字段保持原位，因此不使用 expand[] 的代码看到的响应与之前相同。

以下操作可以展开关联对象。带点的路径展开已展开对象的关联，例如 collection.default_owner 是卡片所属合集的默认负责人。

操作	路径
`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`

每个关联对象都以读取它的操作所返回的形式出现：

关联	`expanded` 中的内容
`collection`	合集，与 `GET /v1/collections` 中的相同。
`owner`、`verifiers`、`default_owner`	用户，与 `GET /v1/users` 中的相同：有权管理用户的调用方得到完整信息，其他调用方得到简要信息（`brief=true`，仅限活跃用户）。`verifiers` 是一个列表，顺序与 `verifier_ids` 相同。
`folders`	卡片在其所属合集中、调用方能看到的文件夹，与不带 `path` 的 `GET /v1/folders/{folder_id}` 中的相同。
`card`	卡片，与 `GET /v1/cards` 中的一项相同。
`event`	事件，与 `GET /v1/webhook-events/{event_id}` 中的相同。

在列表中展开

对于列表，路径以 data. 开头：展开作用于页面中的每一项。返回数组的列表（例如 GET /v1/cards）和把各项放在某个字段中的列表（例如 GET /v1/jobs 的 jobs 或投递日志的 items）都是如此。

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 对每个关联一次性加载整页的对象，因此展开一个列表的开销大约相当于多发一个请求，而不是每一项多一个请求。下一页的游标与 expand[] 无关，因此在下一页可以请求展开其他关联。

规则

每个请求最多 10 个路径，每个路径最多 2 段：列表中写 data.owner，单个对象上写 collection.default_owner。
路径未知、超过 10 个路径或路径超过 2 段时，返回 400，错误码为 api.expand_invalid。details.path 指出是哪个路径，details.reason 说明问题所在：unknown_path、too_deep 或 too_many_paths。
只有调用方能用单独的请求读取某个关联对象时，该对象才会展开。密钥需要具有对应读取操作的权限范围：卡片、合集和文件夹需要 cards:read，用户需要 users:read，事件需要 webhooks:manage。对象还必须对调用方可见，例如对于仅限部分合集的密钥，对象必须位于这些合集中。否则该关联展开为 null，在 verifiers 中则是对应位置上的用户为 null。其 ID 仍会返回。folders 只列出调用方能看到的文件夹。
自定义数据源密钥不能读取卡片，因此使用这种密钥时，文档的 card 始终为 null。要获取卡片，请用具有 import:write 和 cards:read 权限范围的 API 密钥调用推送 API。
超过 30 天的事件和测试投递的事件展开为 null。
expand[] 只会向响应中添加数据，从不改变请求的行为。