انتقل إلى المحتوى
Sursa Developers

توسيع الكائنات المرتبطة

تشير الكائنات إلى الكائنات المرتبطة بها عبر المعرّف: للبطاقة الحقلان 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"}
  }
}

المثال مختصر: للكائن الموسَّع كل حقول عملية القراءة الخاصة به. وتبقى حقول المعرّفات في مكانها، فالشيفرة التي لا تستخدم 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/cardsdata.collection، data.owner، data.verifiers، data.folders
GET /v1/jobs/{job_id}card، card.collection، card.owner، card.verifiers، card.folders
GET /v1/jobsdata.card
GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id}event
GET /v1/webhooks/{webhook_id}/deliveriesdata.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}/documentsdata.card

تصل كل علاقة بالشكل الذي تعيده العملية التي تقرأ الكائن المرتبط:

العلاقةما يصل في expanded
collectionالمجموعة، كما في GET /v1/collections.
owner، verifiers، default_ownerالمستخدم، كما في GET /v1/users: الصف الكامل للمستدعي الذي يحق له إدارة المستخدمين، والصف المختصر (brief=true، المستخدمون النشطون فقط) لغيره. والحقل verifiers قائمة بترتيب verifier_ids.
foldersمجلدات البطاقة في مجموعتها التي يستطيع المستدعي رؤيتها، كما في GET /v1/folders/{folder_id} بلا path.
cardالبطاقة، كعنصر من GET /v1/cards.
eventالحدث، كما في GET /v1/webhook-events/{event_id}.

في القوائم

في القائمة، ابدأ المسار بالبادئة data.، فيُطبَّق على كل عنصر في الصفحة. ويسري هذا على القائمة التي تعيد مصفوفة، مثل GET /v1/cards، وعلى القائمة التي تحفظ عناصرها في حقل، مثل الحقل jobs في GET /v1/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 مسارات في الطلب الواحد، ولا يتجاوز كل منها جزأين: data.owner في القائمة، وcollection.default_owner في الكائن.
  • يعيد المسار غير المعروف، أو أكثر من 10 مسارات، أو المسار الأعمق من جزأين، الحالة 400 مع الرمز api.expand_invalid. ويسمّي الحقل details.path المسار، ويبيّن الحقل details.reason الخطأ: unknown_path أو too_deep أو too_many_paths.
  • لا يُوسَّع الكائن المرتبط إلا للمستدعي الذي يستطيع قراءته بطلب خاص به. يحتاج المفتاح إلى نطاق تلك العملية: cards:read للبطاقات والمجموعات والمجلدات، وusers:read للمستخدمين، وwebhooks:manage للأحداث. ويجب أيضًا أن يكون الكائن مرئيًا للمستدعي، مثلًا داخل مجموعات مفتاح مقصور على بعض المجموعات. وإلا تُوسَّع العلاقة إلى null، وفي verifiers تحل null محل المستخدم. ويبقى معرّفه في الاستجابة. ولا يسرد الحقل folders إلا المجلدات التي يستطيع المستدعي رؤيتها.
  • لا يقرأ مفتاح المصدر المخصص البطاقات، لذلك يكون الحقل card للمستند معه دائمًا null. وللحصول على البطاقة، استدعِ نقاط نهاية الإرسال بمفتاح API له النطاقان import:write وcards:read.
  • الحدث الأقدم من 30 يومًا وحدث التسليم التجريبي يُوسَّعان إلى null.
  • يضيف المعامل expand[] بيانات إلى الاستجابة فقط، ولا يغيّر أبدًا ما يفعله الطلب.