На этой странице описана структура объектов событий надстроек Google Workspace.
Объекты событий — это структуры JSON, которые автоматически создаются и передаются в качестве параметров для запуска функций или функций обратного вызова, когда пользователь взаимодействует с надстройкой. Объекты событий передают информацию на стороне клиента о главном приложении и текущем контексте в функцию обратного вызова на стороне сервера надстройки.
Дополнения Google Workspace используют объекты событий в следующих местах:
Триггеры на главной странице . Каждой определяемой вами функции
homepageTrigger
автоматически передается объект события при срабатывании триггерной функции домашней страницы. Вы можете использовать этот объект в триггерной функции своей домашней страницы, чтобы идентифицировать активное хост-приложение, платформу клиента, языковой стандарт пользователя и другую информацию.Объекты событий, созданные при срабатывании триггеров домашней страницы, не содержат всех полей, включенных в два других случая; поля, относящиеся к виджетам и контекстной информации, опущены.
Контекстуальные триггеры . Каждое хост-приложение предоставляет свой набор контекстных триггеров, которые срабатывают, когда пользователь входит в определенный контекст. Например:
- Gmail предоставляет контекстный триггер, когда пользователь открывает сообщение , и другой, когда пользователь составляет сообщение .
- Календарь Google предоставляет контекстный триггер, когда пользователь открывает событие .
- Google Диск предоставляет контекстный триггер, когда пользователь выбирает файлы на Диске .
Когда срабатывает контекстный триггер, ведущее приложение вызывает соответствующую
runFunction
, указанную в манифесте надстройки, передавая ей объект события в качестве параметра. Объекты событий, созданные при срабатывании контекстных триггеров, содержат все поля, включенные в объекты событий триггера домашней страницы, а также поля, содержащие контекстную информацию.Действия виджета . Объекты событий также используются для обеспечения интерактивности виджетов , используя ту же модель действий , которую используют надстройки Gmail. Дополнения Google Workspace используют все те же функции обработчиков виджетов, объекты
Action
и ответы на действия. Однако в надстройках Google Workspace объекты событий действий содержат еще больше информации, на которую может действовать функция обратного вызова.Объекты событий, созданные в результате действий виджета, содержат все поля, включенные в объекты событий контекстного триггера, а также поля, содержащие информацию о виджете.
Ссылка на предварительный просмотр срабатывает . В Документах, Таблицах и Презентациях Google вы можете настроить предварительный просмотр ссылок для сторонних сервисов на основе определенных шаблонов URL-адресов. Когда пользователи взаимодействуют со ссылкой, соответствующей шаблону, срабатывает
linkPreviewTriggers
, и объект события, содержащий ссылку, передается в функцию обратного вызова триггера. Ваша надстройка может использовать этот объект события для создания смарт-чипа и карты, которые отображают информацию о ссылке в главном приложении. Вы также можете создавать действия виджета, чтобы пользователи могли взаимодействовать с карточкой предварительного просмотра и ее содержимым.
Структура объекта события
В следующей таблице описана структура верхнего уровня объектов событий надстроек Google Workspace. Структура объекта события включает поле верхнего уровня commonEventObject
для информации, независимой от хоста. Каждый объект события также может иметь одно из следующих полей верхнего уровня, зависящих от хоста, определяемых активным хост-приложением: gmailEventObject
, calendarEventObject
или driveEventObject
.
В целях обратной совместимости объекты событий надстроек Google Workspace также включают все исходные поля, используемые в объектах событий действий надстроек Gmail . Эти поля перечислены в таблице ниже в разделе «Исходные поля надстройки Gmail»; информация в этих полях воспроизводится в новой структуре объекта.
Объект события | |
---|---|
eventObject.commonEventObject | Common fields object Объект, содержащий информацию, общую для всех объектов событий, независимо от хост-приложения. |
eventObject.calendar | Calendar event object Присутствует только в том случае, если вызывающим хостом является Календарь Google . Объект, содержащий информацию о календаре и событиях. |
eventObject.drive | Drive event object Присутствует только в том случае, если вызывающим хостом является Google Диск . Объект, содержащий информацию о Диске. |
eventObject.gmail | Gmail event object Присутствует только в том случае, если вызывающим хостом является Gmail . Объект, содержащий информацию Gmail. |
eventObject.docs | Docs event object Присутствует только в том случае, если вызывающим хостом является Google Docs . Объект, содержащий информацию о Документах. |
eventObject.sheets | Sheets event object Присутствует только в том случае, если вызывающим хостом является Google Таблицы . Объект, содержащий информацию о таблицах. |
eventObject.slides | Slides event object Присутствует только в том случае, если вызывающим хостом является Google Slides . Объект, содержащий информацию о слайдах. |
Исходные дополнительные поля Gmail | |
eventObject.messageMetadata.accessToken | string Устарело. Токен доступа. Вы можете использовать это, чтобы включить доступ к пользовательским данным с помощью временных областей надстройки Gmail. Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.messageMetadata.messageId | string Устарело. Идентификатор сообщения ветки, открытой в пользовательском интерфейсе Gmail. Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.clientPlatform | string Устарело. Указывает, где происходит событие (веб, iOS или Android). Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.formInput | object Устарело. Карта текущих значений всех виджетов формы на карточке, ограниченная одним значением для каждого виджета. Ключами являются строковые идентификаторы, связанные с виджетами, а значениями — строки. Объект события предоставляет formInput для удобства, когда вам нужно прочитать данные из нескольких виджетов с ожидаемыми сингулярными значениями, например текстовые вводы и переключатели. Для виджетов с несколькими значениями, таких как флажки, вместо этого вы можете прочитать каждое значение из formInputs . Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.formInputs | object Устарело. Карта текущих значений виджетов в карточке, представленная в виде списков строк. Ключи — это строковые идентификаторы, связанные с виджетом. Для виджетов с одним значением значение представлено в виде одноэлементного массива. Для виджетов с несколькими значениями, таких как группы флажков, все значения представлены в списке. Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.parameters | object Устарело. Карта любых дополнительных параметров, которые вы предоставляете Action с помощью Action.setParameters() . Ключи и значения карты представляют собой строки. Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.userCountry | string Устарело и отключено по умолчанию . Двухбуквенный код, обозначающий страну или регион пользователя. Это также может быть цифровой код страны UN M49 . Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.userLocale | string Устарело и отключено по умолчанию . Двухбуквенный код ISO 639, обозначающий язык пользователя. Дополнительные сведения см. в разделе Доступ к локали и часовому поясу пользователя . Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.userTimezone.id | string Устарело и отключено по умолчанию . Идентификатор часового пояса пользователя. Примеры: America/New_York , Europe/Vienna и Asia/Seoul . Дополнительные сведения см. в разделе Доступ к локали и часовому поясу пользователя . Для надстроек Google Workspace эту информацию можно найти в поле |
eventObject.userTimezone.offset | string Устарело и отключено по умолчанию . Смещение времени относительно всемирного координированного времени (UTC) часового пояса пользователя, измеряемое в миллисекундах. Дополнительные сведения см. в разделе Доступ к локали и часовому поясу пользователя . Для надстроек Google Workspace эту информацию можно найти в поле |
Общий объект события
Общий объект события — это часть общего объекта события, которая передает в надстройку общую, независимую от хоста информацию от клиента пользователя. Эта информация включает в себя такие сведения, как языковой стандарт пользователя, ведущее приложение и платформу.
Помимо домашней страницы и контекстных триггеров, надстройки создают и передают объекты событий функциям обратного вызова действий , когда пользователь взаимодействует с виджетами. Функция обратного вызова вашего дополнения может запрашивать общий объект события, чтобы определить содержимое открытых виджетов в клиенте пользователя. Например, ваша надстройка может найти текст, который пользователь ввел в виджет TextInput
, в объекте eventObject.commentEventObject.formInputs
.
Общие поля объекта события | |
---|---|
commonEventObject.platform | string Указывает источник события («WEB», «IOS» или «ANDROID»). |
commonEventObject.formInputs | object Карта, содержащая текущие значения виджетов в отображаемой карточке. Ключи карты — это строковые идентификаторы, назначенные каждому виджету. Структура объекта значения карты зависит от типа виджета: Например, вместо Дополнительные сведения о средах выполнения в Apps Script см. в обзоре среды выполнения V8 .
|
commonEventObject.hostApp | string Указывает ведущее приложение, в котором активна надстройка при создании объекта события. Возможные значения включают следующее:
|
commonEventObject.parameters | object Любые дополнительные параметры, которые вы передаете Action с помощью Action.setParameters() . |
commonEventObject.userLocale | string По умолчанию отключено . Язык пользователя и идентификатор страны/региона в формате кода языка ISO 639 – кода страны/региона ISO 3166 . Например, en-US . Чтобы включить это поле, вы должны установить для |
commonEventObject.timeZone | string По умолчанию отключено . Идентификатор часового пояса и смещение. Чтобы включить это поле, вы должны установить для addOns.common.useLocaleFromApp значение true в манифесте вашей надстройки. Список областей действия вашего дополнения также должен включать https://www.googleapis.com/auth/script.locale . Дополнительные сведения см. в разделе Доступ к локали и часовому поясу пользователя . |
commonEventObject.timeZone.id | string Идентификатор часового пояса пользователя. Примеры: America/New_York , Europe/Vienna и Asia/Seoul . Чтобы включить это поле, вы должны установить для addOns.common.useLocaleFromApp значение true в манифесте вашей надстройки. Список областей действия вашего дополнения также должен включать https://www.googleapis.com/auth/script.locale . Дополнительные сведения см. в разделе Доступ к локали и часовому поясу пользователя . |
commonEventObject.timeZone.offset | string Смещение времени от всемирного координированного времени (UTC) часового пояса пользователя, измеряемое в миллисекундах. Дополнительные сведения см. в разделе Доступ к локали и часовому поясу пользователя . |
Входные данные формы выбора даты и времени
Функции обратного вызова действий могут получать текущие значения виджета в поле commonEventObject.formInputs
. Сюда входят выбранные пользователем значения даты и времени в виджетах выбора даты или времени. Однако структура информации различается в зависимости от того, был ли виджет настроен как средство выбора даты и времени, средство выбора только даты или средство выбора только времени. Структурные различия описаны в следующей таблице:
Объект события календаря
Объект события «Календарь» — это часть общего объекта события, содержащая информацию о календаре пользователя и событиях календаря. Он присутствует в объекте события только в том случае, если хост-приложением является Календарь Google.
В следующей таблице перечислены поля, присутствующие в поле calendarEventObject
объекта события. Поля, помеченные как «Созданные пользователем данные», присутствуют в объекте события тогда и только тогда, когда данные присутствуют в событии «Календарь» и надстройка устанавливает для поля манифеста addOns.calendar.currentEventAccess
значение READ
или READ_WRITE
.
Объект события календаря | |
---|---|
calendar.attendees[] | list of attendee objects Пользовательские данные. Список участников календарного мероприятия. |
calendar.calendarId | string Идентификатор календаря. |
calendar.capabilities | object Пользовательские данные. Объект, описывающий возможности надстройки по просмотру или обновлению информации о событии. |
calendar.capabilities.canAddAttendees | boolean Пользовательские данные. true , если надстройка может добавлять новых участников в список участников мероприятия; false в противном случае. |
calendar.capabilities.canSeeAttendees | boolean Пользовательские данные. true , если надстройка может читать список участников мероприятия; false в противном случае. |
calendar.capabilities.canSeeConferenceData | boolean Пользовательские данные. true , если надстройка может читать данные конференции событий; false в противном случае. |
calendar.capabilities.canSetConferenceData | boolean Пользовательские данные. true , если надстройка может обновлять данные конференции событий; false в противном случае. |
calendar.capabilities.canAddAttachments | boolean Пользовательские данные. true , если надстройка может добавлять к событию новые вложения; false в противном случае. |
calendar.conferenceData | Conference data object Пользовательские данные. Объект, представляющий любые данные конференции, связанные с этим событием, например сведения о конференции Google Meet. |
calendar.id | string Идентификатор события. |
calendar.organizer | object Объект, представляющий организатора мероприятия. |
calendar.organizer.email | string Адрес электронной почты организатора мероприятия. |
calendar.recurringEventId | string Идентификатор повторяющегося события. |
Посетитель
Объекты Attendee содержат информацию об отдельных участниках событий Календаря Google. Эта информация присутствует в объекте события тогда и только тогда, когда данные присутствуют в событии Calendar и надстройка устанавливает для поля манифеста addOns.calendar.currentEventAccess
значение READ
или READ_WRITE
.
Объект участника | |
---|---|
attendee.additionalGuests | number Количество дополнительных гостей, которые участник указал, что они приведут. По умолчанию равно нулю. |
attendee.comment | string Ответный комментарий участника, если таковой имеется. |
attendee.displayName | string Отображаемое имя участника. |
attendee.email | string Адрес электронной почты участника. |
attendee.optional | boolean true , если присутствие этого участника помечено как необязательное; false в противном случае. |
attendee.organizer | boolean true , если участник является организатором этого мероприятия. |
attendee.resource | boolean true , если участник представляет ресурс, например помещение или часть оборудования; false в противном случае. |
attendee.responseStatus | string Статус ответа участника. Возможные значения включают следующее:
|
attendee.self | boolean true , если этот участник представляет календарь, в котором появляется это событие; false в противном случае. |
Данные конференции
Объекты данных конференции содержат информацию о конференциях, прикрепленных к событиям Календаря Google. Это могут быть решения для конференций Google, такие как Google Meet, или сторонние конференции. Эта информация присутствует в объекте события тогда и только тогда, когда данные присутствуют в событии Calendar и надстройка устанавливает для поля манифеста addOns.calendar.currentEventAccess
значение READ
или READ_WRITE
.
Объект данных конференции | |
---|---|
conferenceData.conferenceId | string Идентификатор конференции. Этот идентификатор предназначен для того, чтобы приложения могли отслеживать конференции; вы не должны показывать этот идентификатор пользователям. |
conferenceData.conferenceSolution | object Объект, представляющий решение для конференции, например Hangouts или Google Meet. |
conferenceData.conferenceSolution.iconUri | string URI видимого пользователю значка, представляющего это решение для конференции. |
conferenceData.conferenceSolution.key | object Ключ, который однозначно идентифицирует решение конференции для этого мероприятия. |
conferenceData.conferenceSolution.key.type | string Тип решения конференции. Возможные значения включают следующее:
|
conferenceData.conferenceSolution.name | string Видимое пользователю имя этого конференц-решения (не локализованное). |
conferenceData.entryPoints[] | list of entry point objects Список точек входа в конференцию, например URL-адреса или номера телефонов. |
conferenceData.notes | string Дополнительные примечания (например, инструкции администратора домена или юридические уведомления) о конференции, которые будут отображаться пользователю. Может содержать HTML. Максимальная длина — 2048 символов. |
conferenceData.parameters | object Объект, содержащий карту данных определенных параметров для использования надстройкой. |
conferenceData.parameters.addOnParameters | object Карта ключей и значений строк параметров. Эти ключи и значения определяются разработчиком надстройки для прикрепления информации к конкретной конференции для использования надстройки. |
Точка входа
Объекты точек входа несут информацию об установленных средствах доступа к данной конференции, например по телефону или видео. Эта информация присутствует в объекте события тогда и только тогда, когда данные присутствуют в событии Calendar и надстройка устанавливает для поля манифеста addOns.calendar.currentEventAccess
значение READ
или READ_WRITE
.
Объект точки входа | |
---|---|
entryPoint.accessCode | string Код доступа, используемый для доступа к конференции. Максимальная длина — 128 символов. Поставщики конференций обычно используют только подмножество { accessCode , meetingCode , passcode , password , pin } для предоставления доступа к конференциям. Сопоставляйте и отображайте только те поля, которые использует провайдер конференций. |
entryPoint.entryPointFeatures | list Особенности точки входа. В настоящее время эти функции применимы только к точкам входа phone :
|
entryPoint.entryPointType | string Тип точки входа. Возможные значения следующие:
|
entryPoint.label | string Видимая пользователем метка для URI точки входа (не локализованная). |
entryPoint.meetingCode | string Код встречи, используемый для доступа к конференции. Максимальная длина — 128 символов. Поставщики конференций обычно используют только подмножество { accessCode , meetingCode , passcode , password , pin } для предоставления доступа к конференциям. Сопоставляйте и отображайте только те поля, которые использует провайдер конференций. |
entryPoint.passcode | string Код доступа, используемый для доступа к конференции. Максимальная длина — 128 символов. Поставщики конференций обычно используют только подмножество { accessCode , meetingCode , passcode , password , pin } для предоставления доступа к конференциям. Сопоставляйте и отображайте только те поля, которые использует провайдер конференций. |
entryPoint.password | string Пароль, используемый для доступа к конференции. Максимальная длина — 128 символов. Поставщики конференций обычно используют только подмножество { accessCode , meetingCode , passcode , password , pin } для предоставления доступа к конференциям. Сопоставляйте и отображайте только те поля, которые использует провайдер конференций. |
entryPoint.pin | string PIN-код, используемый для доступа к конференции. Максимальная длина — 128 символов. Поставщики конференций обычно используют только подмножество { accessCode , meetingCode , passcode , password , pin } для предоставления доступа к конференциям. Сопоставляйте и отображайте только те поля, которые использует провайдер конференций. |
entryPoint.regionCode | string Код региона номера телефона. Требуется пользователям, если URI не включает код страны. Значения основаны на общедоступном списке кодов регионов CLDR . |
entryPoint.uri | string URI точки входа. Максимальная длина — 1300 символов. Форматирование зависит от типа точки входа:
|
Объект события Диска
Объект события Диска — это часть общего объекта события, которая содержит информацию о Google Диске пользователя и его содержимом. Он присутствует в объекте события только в том случае, если хост-приложением является Google Диск.
Объект события Диска | |
---|---|
drive.activeCursorItem | Drive item object Элемент Диска в данный момент активен. |
drive.selectedItems[] | list of Drive item objects Список элементов (файлов или папок), выбранных на Диске. |
Объект на Диске
Объекты элементов Диска содержат информацию об определенных элементах Диска, таких как файлы или папки.
Объект элемента диска | |
---|---|
item.addonHasFileScopePermission | boolean Если true , надстройка запросила и получила https://www.googleapis.com/auth/drive.file авторизацию области для этого элемента; в противном случае это поле является false . |
item.id | string Идентификатор выбранного элемента. |
item.iconUrl | string URL-адрес значка, представляющего выбранный элемент. |
item.mimeType | string MIME-тип выбранного элемента. |
item.title | string Название выбранного элемента. |
Объект события Gmail
Объект события Gmail — это часть общего объекта события, содержащая информацию о сообщениях Gmail пользователя. Он присутствует в объекте события только в том случае, если хост-приложением является Gmail.
Объект события Gmail | |
---|---|
gmail.accessToken | string Токен доступа, специфичный для Gmail. Вы можете использовать этот токен с методом GmailApp.setCurrentMessageAccessToken(accessToken) чтобы предоставить надстройке временный доступ к открытому в данный момент сообщению Gmail пользователя или позволить вашей надстройке создавать новые черновики. |
gmail.bccRecipients[] | list of strings По умолчанию отключено . Список адресов электронной почты получателей «СК:» в настоящее время включен в черновик, который составляет дополнение. Чтобы включить это поле, необходимо установить для поля addOns.gmail.composeTrigger.draftAccess в манифесте значение METADATA . |
gmail.ccRecipients[] | list of strings По умолчанию отключено . Список адресов электронной почты получателей «CC:», в настоящее время включенный в черновик, который составляет дополнение. Чтобы включить это поле, необходимо установить для поля addOns.gmail.composeTrigger.draftAccess в манифесте значение METADATA . |
gmail.messageId | string Идентификатор открытого в данный момент сообщения Gmail. |
gmail.threadId | string Идентификатор открытой в данный момент темы Gmail. |
gmail.toRecipients[] | list of strings По умолчанию отключено . Список адресов электронной почты получателей «Кому:», в настоящее время включенный в черновик, который составляет дополнение. Чтобы включить это поле, необходимо установить для поля addOns.gmail.composeTrigger.draftAccess в манифесте значение METADATA . |
Объект события Документов
Объект события «Документы» — это часть общего объекта события, которая содержит информацию о документе пользователя и его содержимом. Он присутствует в объекте события только в том случае, если хост-приложением является Google Docs.
Объект события Документов | |
---|---|
docs.id | string Присутствует только в том случае, если область https://www.googleapis.com/auth/drive.file была авторизована пользователем .Идентификатор документа, открытого в пользовательском интерфейсе Документов. |
docs.title | string Присутствует только в том случае, если область https://www.googleapis.com/auth/drive.file была авторизована пользователем .Название документа, открытого в пользовательском интерфейсе Документов. |
docs.addonHasFileScopePermission | boolean Если true , надстройка запросила и получила https://www.googleapis.com/auth/drive.file авторизацию области для документа, открытого в пользовательском интерфейсе Документов; в противном случае это поле является false . |
docs.matchedUrl.url | string Присутствует только в том случае, если выполняются следующие условия:
URL-адрес ссылки, которая создает предварительный просмотр в Документах Google. Чтобы использовать это поле, вам необходимо настроить LinkPreviewTriggers в манифесте вашей надстройки. Дополнительные сведения см. в разделе «Предварительный просмотр ссылок со смарт-чипами» . Пример полезной нагрузки, когда пользователь просматривает ссылку "docs" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |
Объект события Таблиц
Объект события Sheets — это часть общего объекта события, которая содержит информацию о документе пользователя и его содержимом. Он присутствует в объекте события только в том случае, если ведущим приложением является Google Таблицы.
Объект события Таблиц | |
---|---|
sheets.id | string Присутствует только в том случае, если область https://www.googleapis.com/auth/drive.file была авторизована пользователем . Идентификатор электронной таблицы, открытой в пользовательском интерфейсе Таблиц. |
sheets.title | string Присутствует только в том случае, если область https://www.googleapis.com/auth/drive.file была авторизована пользователем . Название таблицы, открытой в пользовательском интерфейсе Таблиц. |
sheets.addonHasFileScopePermission | boolean Если true , надстройка запросила и получила https://www.googleapis.com/auth/drive.file авторизацию области для электронной таблицы, открытой в пользовательском интерфейсе Таблиц; в противном случае это поле является false . |
sheets.matchedUrl.url | string Присутствует только в том случае, если выполняются следующие условия:
URL-адрес ссылки, которая создает предварительный просмотр в Google Таблицах. Чтобы использовать это поле, вам необходимо настроить LinkPreviewTriggers в манифесте вашей надстройки. Дополнительные сведения см. в разделе «Предварительный просмотр ссылок со смарт-чипами» . Пример полезной нагрузки, когда пользователь просматривает ссылку "sheets" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |
Объект события слайдов
Объект события «Слайды» — это часть общего объекта события, которая содержит информацию о документе пользователя и его содержимом. Он присутствует в объекте события только в том случае, если ведущим приложением является Google Slides.
Объект события слайдов | |
---|---|
slides.id | string Присутствует только в том случае, если область https://www.googleapis.com/auth/drive.file была авторизована пользователем . Идентификатор презентации, открытой в пользовательском интерфейсе Slides. |
slides.title | string Присутствует только в том случае, если область https://www.googleapis.com/auth/drive.file была авторизована пользователем . Название презентации открывается в пользовательском интерфейсе слайдов. |
slides.addonHasFileScopePermission | boolean Если true , надстройка запросила и получила https://www.googleapis.com/auth/drive.file авторизацию области для презентации, открытой в пользовательском интерфейсе Slides; в противном случае это поле является false . |
slides.matchedUrl.url | string Присутствует только в том случае, если выполняются следующие условия:
URL-адрес ссылки, которая создает предварительный просмотр в Google Slides. Чтобы использовать это поле, вам необходимо настроить LinkPreviewTriggers в манифесте вашей надстройки. Дополнительные сведения см. в разделе «Предварительный просмотр ссылок со смарт-чипами» . Пример полезной нагрузки, когда пользователь просматривает ссылку "slides" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |