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

GET/v1/catalog/services/{service_id}

الحصول على خدمة من الدليل

get_catalog_service

يعيد عنصرًا من الدليل حسب المعرّف مع الأوصاف باللغتين. المعرّف غير المعروف يعيد 404 catalog.service_not_found.

المصادقة

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

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

  • service_idstring (uuid)مطلوب

    معرّف عنصر دليل الخدمات (UUID).

معاملات الترويسة

  • X-View-Asstring

    لمفاتيح API ذات الدور admin فقط. ينفّذ الطلب بصفة ملف تعريف البيانات <profile>[:viewer|verifier|editor]، مثل employee:viewer. لا يمكن لمفتاح التثبيت استخدام هذه الترويسة (403).

معاملات ملفات تعريف الارتباط

  • kb_view_asstring

    ملف تعريف ارتباط وضع «View as» (عرض بصفة) للجلسة. تضبطه العملية POST /auth/view-as وتمسحه العملية DELETE /auth/view-as.

الاستجابات

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

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

  • 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

الكائن: CatalogService

  • categorystringمطلوب

    المعرّف النصي للفئة (GET /v1/catalog/categories).

  • description_enstring | nullمطلوب

    وصف قصير بالإنجليزية. القيمة null إن لم يوجد وصف.

  • domainstring | nullمطلوب

    نطاق الموقع الإلكتروني بلا www.. القيمة null إن لم يوجد موقع.

  • group_namestring | nullمطلوب

    المجموعة (المورّد) إن كانت الخدمة جزءًا من عائلة منتجات، مثل Atlassian؛ وإلا فالقيمة null.

  • iconbooleanمطلوب

    يشير إلى أن الأيقونة تأتي مع Sursa.

  • icon_urlstring | nullمطلوب

    عنوان URL للأيقونة (/v1/catalog/services/{service_id}/icon?v=… أو عنوان خارجي يضبطه التثبيت). القيمة null إن لم توجد أيقونة.

  • idstring (uuid)مطلوب
  • namestringمطلوب
  • slugstringمطلوب
  • websitestring | nullمطلوب

    عنوان URL للموقع الإلكتروني (https://…) أو null.

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

403الإجراء غير مسموح: الدور غير كافٍ، أو لا وصول إلى المجموعة أو البطاقة، أو يعمل الطلب في وضع «View as»، أو المؤسسة معلّقة أو محذوفة (الحقل `detail` كائن فيه `code: org_suspended | org_deleted`).

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

  • 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

404الكائن غير موجود أو غير متاح لك. لا تؤكد واجهة 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

422خطأ في صحة البيانات: نص الطلب أو المعاملات لا تطابق المخطط (الحقل `detail` قائمة بأخطاء صحة البيانات)، أو قيمة معامل خارج النطاق المسموح (الحقل `detail` رسالة نصية).

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

  • 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 بالثواني: انتظر ثم أعد المحاولة.

← catalog · مرجع API