Susijusių objektų išplėtimas

Objektai nurodo susijusius objektus pagal ID: kortelė turi owner_id ir collection_id. Kai jums reikia paties susijusio objekto, antros užklausos siųsti nereikia. Paprašykite jo su expand[], ir jis ateis tame pačiame atsake, lauke 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"}
  }
}

Pavyzdys sutrumpintas: išplėstas objektas turi visus savo skaitymo operacijos laukus. ID laukai lieka savo vietose, todėl kodas, kuris nenaudoja expand[], mato tokį patį atsaką kaip anksčiau.

Susijusius objektus išplečia šios operacijos. Kelias su tašku išplečia išplėsto objekto nuorodą, pavyzdžiui, collection.default_owner – tai kortelės rinkinio numatytasis atsakingas asmuo.

Operacija	Keliai
`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`

Kiekviena nuoroda ateina tokia forma, kokia susijusį objektą skaito jo operacija:

Nuoroda	Kas ateina lauke `expanded`
`collection`	Rinkinys, kaip `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Naudotojas, kaip `GET /v1/users`: iškvietėjui, kuris gali valdyti naudotojus, – visa eilutė, kitiems iškvietėjams – trumpoji eilutė (`brief=true`, tik aktyvūs naudotojai). `verifiers` – sąrašas ta pačia tvarka kaip `verifier_ids`.
`folders`	Kortelės aplankai jos rinkinyje, kuriuos iškvietėjas mato, kaip `GET /v1/folders/{folder_id}` be `path`.
`card`	Kortelė, kaip `GET /v1/cards` elementas.
`event`	Įvykis, kaip `GET /v1/webhook-events/{event_id}`.

Sąrašuose

Sąrašo atveju kelią pradėkite data.: jis taikomas kiekvienam puslapio elementui. Taip pat ir sąrašui, kuris grąžina masyvą, pavyzdžiui, GET /v1/cards, ir sąrašui, kurio elementai yra lauke, pavyzdžiui, jobs iš GET /v1/jobs arba items iš pristatymų žurnalo.

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 kiekvieną nuorodą visam puslapiui įkelia iš karto, todėl sąrašo išplėtimas kainuoja maždaug tiek, kiek viena papildoma užklausa, o ne po užklausą kiekvienam elementui. Kito puslapio žymeklis nepriklauso nuo expand[], todėl kitame puslapyje galite prašyti kitų nuorodų.

Taisyklės

Iki 10 kelių vienoje užklausoje, kiekvienas ne gilesnis nei 2 segmentų: sąraše data.owner, objekte collection.default_owner.
Nežinomas kelias, daugiau nei 10 kelių arba gilesnis nei 2 segmentų kelias grąžina 400 su kodu api.expand_invalid. details.path nurodo kelią, o details.reason – kas negerai: unknown_path, too_deep arba too_many_paths.
Susijęs objektas išplečiamas tik iškvietėjui, kuris galėtų jį perskaityti atskira užklausa. Raktui reikia tos operacijos apimties: cards:read kortelėms, rinkiniams ir aplankams, users:read naudotojams, webhooks:manage įvykiams. Objektas taip pat turi būti matomas iškvietėjui, pavyzdžiui, būti rinkiniuose, kuriais apribotas raktas. Kitaip nuoroda išplečiama kaip null, o verifiers sąraše naudotojo vietoje yra null. Jo ID vis tiek grąžinamas. folders išvardija tik aplankus, kuriuos iškvietėjas mato.
Pasirinktinio šaltinio raktas kortelių neskaito, todėl su juo dokumento card visada yra null. Kad gautumėte kortelę, push API kvieskite su API raktu, turinčiu apimtis import:write ir cards:read.
Senesnis nei 30 dienų įvykis ir bandomojo pristatymo įvykis išplečiami kaip null.
expand[] tik prideda duomenų į atsaką. Jis niekada nekeičia to, ką užklausa daro.