واجهة نقطة نهاية إضافات Google Workspace


نظرة عامة على الخدمة

عندما يبدأ المستخدم تفاعلاً في تطبيق مضيف متوافق (Gmail أو تقويم Google أو Google Drive أو Google Chat أو مستندات Google أو جداول بيانات Google أو العروض التقديمية من Google أو Workspace Studio)، يرسل المضيف حمولة حدث HTTP POST إلى عنوان URL لمعاودة الاتصال للإضافة التي تم ضبطها (/*).

يجب أن تتلقّى نقطة نهاية الإضافة حمولة طلب EventObject وأن تعرض أحد أنواع استجابة JSON الخمسة الصالحة الموضّحة في الاستجابة: HandleEventResponse.


عقد نقطة نهاية الويب هوك

الطريقة مسار نقطة النهاية نص الطلب نص الاستجابة
POST ‫/* (أو مسار معاودة الاتصال الذي تم ضبطه) EventObject أحد أنواع الردود الخمسة

الطلب: EventObject

يحتوي EventObject على بيانات وصفية ذات مستوى أعلى وحقول أحداث شائعة وتفاصيل سياقية للتطبيق المستضيف:

سياق التفويض والسياق الشائع

  • commonEventObject: لغة المستخدم، تعداد التطبيق المضيف (GMAIL، CALENDAR، DRIVE، CHAT، DOCS، SHEETS، SLIDES، WORKFLOW)، نظام تشغيل المستخدم، المنطقة الزمنية، قيم إدخال نموذج التطبيق المصغّر (formInputs)، والمعلمات المخصصة. يمكنك الاطّلاع على CommonEventObject.
  • authorizationEventObject: رموز الدخول عبر OAuth للمستخدمين ورموز تعريف المستخدمين والنطاقات المسموح بها من النظام يمكنك الاطّلاع على AuthorizationEventObject.

كائنات أحداث التطبيق المضيف

استنادًا إلى التطبيق الذي يستدعي دالة ردّ الاتصال، يتوفّر أحد عناصر المضيف التالية:

  • Gmail: معرّف الرسالة ومعرّف سلسلة المحادثات ورمز الدخول المؤقت وقوائم مستلمي الرسائل (toRecipients وccRecipients وbccRecipients). يُرجى الاطّلاع على GmailEventObject.
  • تقويم Google: معرّف الحدث ومعرّف الحدث المتكرّر ومعرّف التقويم ومعلومات المنظّم والمشاركين وبيانات الاجتماع ونقاط الدخول يمكنك الاطّلاع على CalendarEventObject.
  • ‫Drive: الملفات أو المجلدات المحدّدة (selectedItems) والبيانات الوصفية لعنصر المؤشر الحالي (activeCursorItem). يُرجى الاطّلاع على DriveEventObject.
  • ‫Chat: نوع الحدث (ADDED_TO_SPACE وREMOVED_FROM_SPACE وMESSAGE وCARD_CLICKED) والبيانات الوصفية للمساحة وتفاصيل المستخدم وبيانات الحمولة يمكنك الاطّلاع على ChatEventObject.
  • ‫Workspace Studio: عمليات استدعاء الإجراءات، وأحداث دورة حياة المشغّلات، وإعدادات العناصر، وعمليات استرداد الموارد، وخرائط البيانات المتغيّرة. يمكنك الاطّلاع على WorkflowEventObject.
  • مستندات Google: رقم تعريف المستند وعنوانه وعلامة الإذن على مستوى الملف ونمط عنوان URL المطابق يمكنك الاطّلاع على DocsEventObject.
  • جداول بيانات Google: رقم تعريف جدول البيانات والعنوان وعلامة الإذن على مستوى الملف ونمط عنوان URL المطابق يمكنك الاطّلاع على SheetsEventObject.
  • العروض التقديمية من Google: معرّف العرض التقديمي والعنوان وعلامة الإذن على مستوى الملف ونمط عنوان URL المطابق يمكنك الاطّلاع على SlidesEventObject.

الردّ: HandleEventResponse

استجابة HTTP التي تعرضها نقطة نهاية الويب هوك هي عنصر JSON جذري غير مميّز بعلامة يجب أن يكون مثيلاً لأحد أنواع الاستجابة الخمسة التالية:

  1. RenderActions: تعرض بطاقات جديدة أو تنتقل بين حزم البطاقات أو تنفّذ إجراءات واجهة المستخدم (على سبيل المثال، {"action": {"navigations": [...]}} أو {"renderActions": ...}).
  2. SubmitFormResponse: يستجيب لإجراء إرسال نموذج من المستخدم من خلال تعليمات عرض البطاقة ومؤشر اختياري لتعديل الحالة (على سبيل المثال، {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse: يوفّر اقتراحات نصية ديناميكية لحقول الإكمال التلقائي في التطبيقات المصغّرة (على سبيل المثال، {"autoComplete": {"items": [...]}}).
  4. DataActions: تُجري تغييرات على المستندات أو إجراءات في مساحة Chat يتم تفعيلها من خلال عملية الاستدعاء (على سبيل المثال، {"hostAppDataAction": {...}}).
  5. AuthorizationError: تطلب من المستخدم تفويض بيانات اعتماد خارجية تابعة لجهة خارجية أو تطلب نطاقات Google OAuth إضافية (على سبيل المثال، {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).

مواصفات OpenAPI 3.0 المستقلة ومخططات JSON

لإنشاء نماذج خادم أو مكتبات برامج SDK أو مخططات التحقق من الحمولة تلقائيًا لنقطة نهاية رد الاتصال، راجع ملفات المواصفات التالية:

  • مواصفات OpenAPI 3.0.3: addon_callback_openapi.json
  • تعريفات مخطط JSON: endpoint_interface.schema.json
    • جزء مخطّط الطلب: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • جزء من مخطّط الاستجابة: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse