نطاقات التكامل

تحدد نطاقات التكامل البيانات التي يُصرح لمفتاح API بقراءتها. يجب أن يحمل العميل النطاق الدقيق الحساس لحالة الأحرف الذي تتطلبه نقطة النهاية، وأن تفعّل خطة المؤسسة الفعالة فئة ذلك النطاق. تعين وحدة تحكم المؤسسة الحالية النطاقات أثناء الإنشاء ولا تعرض إجراء تعديل موجهًا.

النطاقات المتاحة

ReportsRead

يمنح صلاحية القراءة على بيانات تعريف الاستبيانات وملخصات الاستجابات التجميعية للمؤسسة.

ما يغطيه نطاق ReportsRead:

GET /api/integrations/metadata/surveys.
GET /api/integrations/reports/surveys.
GET /api/integrations/reports/responses.

ما لا يغطيه نطاق ReportsRead:

ملخصات الاستخدام (تتطلب UsageRead).
صفوف الاستجابات الفردية (تتطلب RawResponsesRead).

UsageRead

يمنح صلاحية القراءة على ملخص استخدام التكامل للمؤسسة.

ما يغطيه نطاق UsageRead:

GET /api/integrations/reports/usage.

ما لا يغطيه نطاق UsageRead:

بيانات الاستبيانات أو الاستجابات.

RawResponsesRead

يمنح صلاحية القراءة على صفوف الاستجابات الفردية.

ما يغطيه نطاق RawResponsesRead:

GET /api/integrations/reports/raw-responses.
بيانات كل إرسال الوصفية وأوصاف الملفات الحالية من نقطة القائمة.
GET /api/integrations/reports/raw-responses/{responseId}/answers لقيم الإجابات الفعلية لاستجابة حالية واحدة داخل المؤسسة، مع مراجع الملفات دون بايتات الملفات.
GET /api/integrations/files/{answerFileId} لارتباطات الملفات الحالية المصرح بها.

اعتبارات الخصوصية:

قد تحتوي بيانات الاستجابة الخام على معلومات شخصية. امنح هذا النطاق فقط عندما يتطلب عقد التكامل صراحة بيانات على مستوى الفرد.
تأكد من أن معالجة بياناتك وتخزينها يمتثلان لأنظمة حماية البيانات المعمول بها.
جميع استعلامات الاستجابة الخام مقيدة بالمؤسسة التي يُستخدم مفتاحها.

تركيبات النطاقات

يمكن لعميل تكامل واحد أن يحمل أي تركيبة من النطاقات. التركيبات النموذجية:

حالة الاستخدام	النطاقات الموصى بها
لوحة ذكاء الأعمال تعرض مؤشرات أداء مجمعة فقط	`ReportsRead`
مراقبة استخدام التكامل	`UsageRead`
استيعاب مستودع البيانات يتطلب بيانات صفية حالية	`ReportsRead` و`RawResponsesRead`
تدقيق امتثال يتطلب سجلات فردية	`RawResponsesRead`

طبّق مبدأ الحد الأدنى من الامتيازات: امنح فقط النطاقات التي يتطلبها التكامل.

فرض النطاقات

تتحقق كل نقطة نهاية من نطاقها المطلوب بعد مصادقة مفتاح API. يعيد المفتاح الصالح الذي يفتقد النطاق 403 Forbidden مع غلاف BaseResponse الآتي، ولا تحدد الاستجابة النطاق المفقود:

{
  "errorCode": 403,
  "errorMessage": "You do not have permission to access this resource.",
  "data": null
}

تُخزن النطاقات في سجل عميل التكامل وهي منفصلة عن مجموعات صلاحيات System وTenant. يتطلب ReportsRead وUsageRead إمكانية الخطة الوصول إلى API التقارير، ويتطلب RawResponsesRead إمكانية الوصول إلى API الاستجابات الخام ويستخدم الحد الأقصى الأقصر المضبوط لعمر المفتاح.

نطاقات التكامل