Обзор сервиса
Когда пользователь запускает взаимодействие в поддерживаемом хост-приложении (Gmail, Google Календаре, Google Диске, 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… - Календарь: идентификатор мероприятия, идентификатор повторяющегося мероприятия, идентификатор календаря, информация об организаторе, участники, данные о видеовстрече и точки входа. Подробнее:
CalendarEventObject. - Диск. Выбранные файлы или папки (
selectedItems) и метаданные текущего объекта, на который наведен курсор (activeCursorItem). ПодробнееDriveEventObject… - Chat. Тип события (
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), метаданные чат-группы, сведения о пользователе и данные полезной нагрузки. Подробнее:ChatEventObject. - Workspace Studio: Вызовы действий, события жизненного цикла триггеров, конфигурации элементов, извлечения ресурсов и сопоставление данных переменных.
Подробнее:
WorkflowEventObject. - Документы: идентификатор документа, название, флаг разрешения на уровне файла и соответствующий шаблон URL. Подробнее:
DocsEventObject. - Таблицы: идентификатор таблицы, название, флаг разрешения на уровне файла и соответствующий шаблон URL. Подробнее:
SheetsEventObject. - Презентации: идентификатор презентации, название, флаг разрешения на уровне файла и соответствующий шаблон URL. Подробнее:
SlidesEventObject.
Ответ: HandleEventResponse
HTTP-ответ, возвращаемый конечной точкой вебхука, – это неразмеченный корневой объект JSON, который должен быть экземпляром одного из пяти типов ответов:
RenderActions– отрисовывает новые карточки, перемещается по наборам карточек или выполняет действия в интерфейсе (например,{"action": {"navigations": [...]}}или{"renderActions": ...}).SubmitFormResponse– отвечает на отправку формы пользователем, предоставляя инструкции по отрисовке карточки и необязательный индикатор обновления состояния (например,{"renderActions": {...}, "stateChanged": true}).GetAutocompletionResponse– предоставляет динамические текстовые подсказки для полей автозаполнения виджетов (например,{"autoComplete": {"items": [...]}}).DataActions. Выполняет изменения в документе или действия в чат-группе Google Chat, активированные обратным вызовом (например,{"hostAppDataAction": {...}}).AuthorizationErrorпредлагает пользователю авторизовать внешние сторонние учетные данные или запрашивает дополнительные области действия OAuth Google (например,{"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
- Фрагмент схемы запроса: