نمای کلی سرویس
وقتی کاربر تعاملی را در برنامه میزبان پشتیبانیشده (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 ریشه بدون برچسب است که باید نمونهای از یکی از پنج نوع پاسخ زیر باشد:
RenderActions: کارتهای جدید را ارائه میکند، در دستههای کارت پیمایش میکند، یا کنشهای میانای کاربر را اجرا میکند (برای مثال،{"action": {"navigations": [...]}}یا{"renderActions": ...}).SubmitFormResponse: به کنش ارسال فرم کاربر با دستورالعملهای ارائه کارت و نشانگر اختیاری بهروزرسانی وضعیت (برای مثال،{"renderActions": {...}, "stateChanged": true}) پاسخ میدهد.GetAutocompletionResponse: پیشنهادهای نوشتاری پویا برای فیلدهای تکمیل خودکار ابزاره (برای مثال،{"autoComplete": {"items": [...]}}) ارائه میدهد.DataActions: تغییرات سند یا کنشهای فضای Chat را که توسط فراخوان (برای مثال،{"hostAppDataAction": {...}}) راهاندازی شده است انجام میدهد.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
- قطعه طرحواره درخواست: