میانای نقطه پایانی برافزاهای Google Workspace


نمای کلی سرویس

وقتی کاربر تعاملی را در برنامه میزبان پشتیبانی‌شده (Gmail، تقویم Google، Google Drive، Google Chat، سندنگار Google، کاربرگ‌نگار Google، اسلایدنگار Google، یا Workspace Studio) راه‌اندازی می‌کند، میزبان یک بار داده رویداد HTTP POST را به نشانی وب فراخوان برافزای پیکربندی‌شده شما (/*) ارسال می‌کند.

نقطه پایانی برافزای شما باید بار داده درخواست 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 را ببینید.
  • تقویم: شناسه رویداد، شناسه رویداد تکرارشونده، شناسه تقویم، اطلاعات سازمان‌دهنده، شرکت‌کنندگان، داده‌های کنفرانس، و نقاط ورودی. CalendarEventObject را ببینید.
  • Drive: فایل‌ها یا پوشه‌های انتخاب‌شده (selectedItems) و فراداده مورد مکان‌نمای فعلی (activeCursorItem). DriveEventObject را ببینید.
  • Chat: نوع رویداد (ADDED_TO_SPACE، REMOVED_FROM_SPACE، MESSAGE، CARD_CLICKED)، فراداده فضا، جزئیات کاربر، و داده‌های پایه‌بار. ChatEventObject را ببینید.
  • Workspace Studio: فراخوانی‌های کنش، رویدادهای چرخه حیات راه‌انداز، پیکربندی‌های عنصر، بازیابی‌های منبع، و نقشه‌های داده متغیر. WorkflowEventObject را ببینید.
  • سندنگار: شناسه سند، عنوان، پرچم اجازه محدوده فایل، و الگوی نشانی وب مطابقت‌داده‌شده. DocsEventObject را ببینید.
  • Sheets: شناسه صفحه‌گسترده، عنوان، پرچم اجازه محدوده فایل، و الگوی نشانی وب مطابقت‌داده‌شده. SheetsEventObject را ببینید.
  • اسلایدنگار: شناسه ارائه، عنوان، پرچم اجازه محدوده فایل، و الگوی نشانی وب مطابقت‌داده‌شده. 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

برای تولید خودکار کدهای آماده سرور، کتابخانه‌های کارخواه کیت توسعه نرم‌افزار، یا طرح‌واره‌های اعتبارسنجی بار مفید برای نقطه پایانی بازخوان، به فایل‌های مشخصات زیر مراجعه کنید:

  • مشخصات 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