الأسئلة الشائعة — واجهة برمجة تطبيقات التكامل
الأسئلة الشائعة للمطورين والفرق التي تستخدم واجهة برمجة تطبيقات التكامل في Survanta.
س: ما الذي يمكنني الوصول إليه بمفتاح API للتكامل؟
يمنح مفتاح API للتكامل وصولا للقراءة فقط إلى نقاط نهاية التكامل المعتمدة لمؤسستك. تعتمد البيانات المتاحة على النطاقات المعيّنة لعميل API الخاص بك عند إنشائه. تغطي النطاقات الحالية بيانات التقارير وملخص الاستخدام وصفوف الاستجابات الخام عند منحها صراحة.
س: كيف أضمّن مفتاح API في طلب؟
ضمّن مفتاح API في ترويسة X-Survanta-Api-Key لكل طلب من طلبات واجهة التكامل:
X-Survanta-Api-Key: <your-api-key>
استبدل <your-api-key> بالمفتاح الذي تم إنشاؤه أو تدويره لعميل API الخاص بك. يجب تضمين المفتاح في جميع الطلبات — لا توجد مصادقة قائمة على الجلسة لواجهة برمجة تطبيقات التكامل.
س: ما هي النطاقات المتاحة؟
تفوض النطاقات مسارات القراءة فقط؛ ولا تمنح وصول تعديل. والقيم المدعومة هي بالضبط:
- ReportsRead — قراءة بيانات تعريف الاستبيانات وملخصات الاستجابات التجميعية.
- UsageRead — قراءة ملخص استخدام التكامل للمؤسسة.
- RawResponsesRead — قراءة صفوف الاستجابات الفردية. امنحه فقط عند الحاجة.
تعتمد النطاقات الدقيقة المتاحة على خطة مؤسستك. تواصل مع مسؤول المؤسسة لمراجعة النطاقات المعيّنة لعميل API الخاص بك أو تحديثها.
س: ماذا يعني الرد 401؟
يعني الرد 401 Unauthorized أن مصادقة مفتاح API لم تنتج عميلًا مقبولًا. وتشمل الأسباب الشائعة:
- مفتاح API مفقود من رأس الطلب.
- مفتاح API غير صحيح أو تم تدويره.
- مفتاح API ينتمي إلى مؤسسة أو بيئة مختلفة.
- العميل ملغى أو غير نشط أو منتهي.
تحقق من وجود ترويسة X-Survanta-Api-Key وأن مفتاحك صالح. إذا استمرت المشكلة، تواصل مع مسؤول المؤسسة.
س: كيف أدوّر مفتاح API الخاص بي؟
يتطلب تدوير مفتاح API صلاحية إدارة تكاملات المؤسسة. لتدوير مفتاح:
- اطلب من مسؤول المؤسسة الانتقال إلى الإعدادات > واجهة برمجة تطبيقات التكامل في لوحة التحكم.
- حدد عميل API الذي تريد تدوير مفتاحه.
- انقر على تدوير المفتاح. يُنشأ مفتاح جديد فورًا.
- يُلغى صلاحية المفتاح القديم على الفور.
يلغي التدوير المفتاح القديم ويعرض البديل مرة واحدة، لذلك لا توجد فترة يعمل فيها المفتاحان معًا. نسق نشر المفتاح الجديد فورًا واستخدم نافذة صيانة عندما لا يُقبل الانقطاع.
س: ماذا يحدث إذا تجاوزت حد عملاء API الخاص بي؟
يحد بند التكاملات الخارجية العملاء النشطين وغير المنتهين. ويُمنع الإنشاء عند السعة. وعند خفض الخطة، تحتفظ المصالحة بأقدم العملاء المسموحين وتلغي الأحدث الزائدين. اطلب المزيد بطلب زيادة حد في إنشاء طلب (يتطلب تسجيل الدخول وصلاحية الفوترة).
س: هل توجد حدود معدّل على واجهة برمجة التطبيقات؟
تستخدم وحدات تحكم التكامل سياسات IntegrationClient المضبوطة، وتستخدم قراءة الاستجابات الخام أيضًا IntegrationRawResponses. وهذه سياسات إعداد تطبيق لا مفاتيح Limit للخطة. قد يعيد الطلب المرفوض 429؛ احترم أي بيانات لإعادة المحاولة واستخدم تراجعًا أسيًا محدودًا مع عشوائية.
س: أين يمكنني العثور على توثيق واجهة برمجة التطبيقات ونقاط النهاية المتاحة؟
استخدم فئة وثائق مفتاح Integration API للمصادقة والنطاقات والبيانات الوصفية والتقارير والاستجابات الخام والترقيم والأخطاء والتدوير والأمان. ويتطلب إنشاء العميل من لوحة التحكم صلاحية إدارة تكامل المؤسسة؛ أما رؤية الوثائق فتحكمها بوابة الوثائق بصورة منفصلة.