Интерфейс конечной точки дополнений Google Workspace


Обзор сервиса

Когда пользователь запускает взаимодействие в поддерживаемом хост-приложении (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, который должен быть экземпляром одного из пяти типов ответов:

  1. RenderActions – отрисовывает новые карточки, перемещается по наборам карточек или выполняет действия в интерфейсе (например, {"action": {"navigations": [...]}} или {"renderActions": ...}).
  2. SubmitFormResponse – отвечает на отправку формы пользователем, предоставляя инструкции по отрисовке карточки и необязательный индикатор обновления состояния (например, {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse – предоставляет динамические текстовые подсказки для полей автозаполнения виджетов (например, {"autoComplete": {"items": [...]}}).
  4. DataActions. Выполняет изменения в документе или действия в чат-группе Google Chat, активированные обратным вызовом (например, {"hostAppDataAction": {...}}).
  5. 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