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

GET/v1/folders

الحصول على أشجار مجلدات كل المجموعات

folder_trees

يعيد في استجابة واحدة أشجار مجلدات كل المجموعات التي يستطيع المستخدم أن يرى فيها كائنًا واحدًا على الأقل، بقواعد الرؤية نفسها كما في GET /v1/collections/{name}/folders وبترتيب GET /v1/collections. المجموعة التي ليس فيها كائنات مرئية تُستبعد. إلى جانب cards، لكل مجلد إجماليات الشجرة الفرعية cards_total وsensitive_total وtop_category. ومع updated_since أو metadata[<key>]= يحمل الحقل folders لكل مجموعة المجلداتِ المطابقة قائمةً مسطحة (الحقل children فارغ، ويبيّن parent_id الموضع في الشجرة). ومع updated_since تُرتَّب حسب updated_at تصاعديًا، ثم حسب id؛ وبدونه بترتيب sort_key. وتُستبعد المجموعات التي لا مجلدات مطابقة فيها.

المصادقة

أرسل مفتاح API في الترويسة Authorization: Authorization: Bearer <key>.

معاملات الاستعلام

  • limitinteger

    حجم الصفحة. دون المعاملين limit وcursor تُعاد القائمة كاملة؛ ومع المعامل تُعاد عناصر بعدد limit على الأكثر، وتُعطى الصفحة التالية في الترويستين Link (rel="next") وX-Next-Cursor.

    ≥ 1, ≤ 200

  • cursorstring

    مؤشر الصفحة التالية من الترويسة X-Next-Cursor أو من الحقل next_cursor في الاستجابة السابقة بعوامل التصفية نفسها؛ ويحمل حجم الصفحة. مع المعامل offset معًا: 422 validation.failed؛ ومؤشر قائمة أخرى أو عوامل تصفية أخرى أو مؤشر تالف: 400 api.cursor_invalid.

    length ≤ 512

  • updated_sincestring (date-time)

    الكائنات التي تساوي فيها قيمة updated_at هذه اللحظة أو تأتي بعدها فقط (RFC 3339 مع إزاحة التوقيت)، للمزامنة. معه تُرتَّب القائمة حسب updated_at تصاعديًا، ثم حسب id، ويتابع المؤشر بهذا الترتيب. الكائنات المحذوفة لا تظهر في القائمة: الحذف يصل على شكل أحداث.

    length ≤ 512

  • metadatamap of string

    التصفية حسب metadata: الشرط metadata[<key>]=<value> يطابق القيمة تمامًا. حتى 3 شروط، ويجب أن تتحقق كلها (?metadata[team]=support&metadata[crm_id]=A-1042). أكثر من 3 شروط أو مفتاح غير صالح يعيد 400 api.metadata_invalid.

الاستجابات

200استجابة ناجحة

ترويسات الاستجابة

  • Link

    عنوان الصفحة التالية، <…>; rel="next". غياب الترويسة يعني أن هذه الصفحة الأخيرة.

  • X-Next-Cursor

    مؤشر الصفحة التالية للمعامل cursor. غياب الترويسة يعني أن هذه الصفحة الأخيرة.

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: FolderTreeList

array of FolderTree
  • collection_idintegerمطلوب
  • collection_namestringمطلوب
  • collection_titlestringمطلوب

    اسم المجموعة للعرض.

  • permissionsarray of stringمطلوب

    الصلاحيات الفعلية للمستخدم على المجموعة.

  • unfiledintegerمطلوب

    بطاقات المجموعة المتاحة للمستخدم والتي ليست في أي مجلد. لا تُحتسب البطاقات المؤرشفة، كما في قائمة البطاقات الافتراضية.

  • foldersarray of FolderNodeمطلوب
401لم تُرسَل بيانات اعتماد (لا ملف تعريف ارتباط للجلسة ولا مفتاح API)، أو لم يُعثر على المفتاح.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

429طلبات كثيرة جدًا (`api.rate_limited`)، أو استُنفدت حصة المؤسسة للدقيقة أو اليوم أو الشهر (`api.quota_exceeded`؛ يحتوي الحقل `error.details` على `quota` و`limit` و`reset_at`)، أو بلغت المؤسسة حدها، أو خدمة الإجابات مشغولة (`answers.engine_busy`). انتظر المدة المذكورة في الترويسة `Retry-After`.

ترويسات الاستجابة

  • Retry-After

    عدد الثواني التي تنتظرها قبل إعادة محاولة الطلب.

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

رموز الأخطاء

الرموز التي قد تعيدها نقطة النهاية هذه في error.code، إضافةً إلى الرموز العامة لكل طلب.

حدود المعدل

تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.

← folders · مرجع API