نظرة عامة على الخدمة
عندما يبدأ المستخدم تفاعلاً في تطبيق مضيف متوافق
(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 جذري غير مميّز بعلامة يجب أن يكون مثيلاً لأحد أنواع الاستجابة الخمسة التالية:
RenderActions: تعرض بطاقات جديدة أو تنتقل بين حزم البطاقات أو تنفّذ إجراءات واجهة المستخدم (على سبيل المثال،{"action": {"navigations": [...]}}أو{"renderActions": ...}).SubmitFormResponse: يستجيب لإجراء إرسال نموذج من المستخدم من خلال تعليمات عرض البطاقة ومؤشر اختياري لتعديل الحالة (على سبيل المثال،{"renderActions": {...}, "stateChanged": true}).GetAutocompletionResponse: يوفّر اقتراحات نصية ديناميكية لحقول الإكمال التلقائي في التطبيقات المصغّرة (على سبيل المثال،{"autoComplete": {"items": [...]}}).DataActions: تُجري تغييرات على المستندات أو إجراءات في مساحة Chat يتم تفعيلها من خلال عملية الاستدعاء (على سبيل المثال،{"hostAppDataAction": {...}}).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
- جزء مخطّط الطلب: