事件对象

本页面概述了 Google Workspace 插件事件对象的结构。

事件对象是 JSON 结构，会在用户与插件互动时触发，并自动以参数的形式传递或触发函数。事件对象会将插件主应用的相关当前信息和当前上下文传送到插件的服务器端回调函数。

Google Workspace 插件会在以下位置使用事件对象：

  • 首页触发器：当首页触发器函数触发时，系统会自动为您定义的每个 homepageTrigger 函数传递一个事件对象。您可以在首页触发器函数中使用此对象来识别处于活跃状态的托管应用、客户端的平台、用户语言区域及其他信息。

    在首页触发器触发时创建的事件对象不包含另外两种情况中包含的所有字段；与微件和上下文信息相关的字段会被省略。

  • 内容相关触发器。 每个主应用都提供一组不同的上下文触发器，这些触发器会在用户输入特定上下文时触发。例如：

    当上下文触发器触发时，主机应用会调用插件清单中列出的相应 runFunction，并向其传递事件对象作为参数。内容相关触发器触发时创建的事件对象包含首页触发器事件对象中包含的所有字段，以及包含上下文信息的字段。

  • 微件操作。事件对象还可用于提供 widget 互动，使用与 Gmail 插件相同的操作模型。Google Workspace 插件使用相同的所有 widget 处理程序函数、Action 对象和操作响应。但在 Google Workspace 插件中，操作事件对象则包含回调函数可以执行的操作的详细信息。

    因 widget 操作而创建的事件对象包含上下文触发器事件对象中包含的所有字段，以及包含 widget 信息的字段。

  • 预览链接触发器（开发者预览版）。 在 Google 文档中，您可以根据特定网址格式为第三方服务配置链接预览。当用户与满足该模式的链接进行互动时，系统会触发 previewLinkTrigger 并将包含该链接的事件对象传递给触发器的回调函数。您的插件可以使用此事件对象构建智能条状标签和卡片，以在主机应用内呈现有关链接的信息。您还可以构建 widget 操作，让用户能够与预览卡片及其内容互动。

事件对象结构

下表介绍了 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 文档时才存在。一个包含文档信息的对象。
eventObject.sheets Sheets event object
只有在通话主持人是 Google 表格时才会显示。一个包含 Google 表格信息的对象。
eventObject.slides Slides event object
只有在通话主持人是 Google 幻灯片时才存在。包含幻灯片信息的对象。
原始 Gmail 插件字段
eventObject.messageMetadata.accessToken string
已弃用。访问令牌。您可以执行此操作，启用通过 Gmail 临时插件范围访问用户数据的权限。

对于 Google Workspace 插件，请在 eventObject.gmail.accessToken 字段中找到此信息。
eventObject.messageMetadata.messageId string
已弃用。在 Gmail 界面中打开的线程的消息 ID。

对于 Google Workspace 插件，请在 eventObject.gmail.messageId 字段中找到此信息。
eventObject.clientPlatform string
已弃用。指明事件源自何处（网站、iOS 或 Android）。

对于 Google Workspace 插件，请在 eventObject.commonEventObject.platform 字段中找到此信息。
eventObject.formInput object
已弃用。卡片中所有表单微件的当前值的映射，每个微件仅限一个值。键是与 widget 相关联的字符串 ID，值是字符串。如果您需要从有多个具有预期单数值（如文本输入和开关）的 widget 中读取数据，事件对象提供了 formInput。对于多值微件（例如复选框），您可以改为从 formInputs 读取每个值。

对于 Google Workspace 插件，请改为在 eventObject.commonEventObject.formInputs 字段中找到此信息；具有单个值的 widget 表示为包含单个元素的数组。
eventObject.formInputs object
已弃用。卡片中 widget 的最新值映射，以字符串列表形式显示。键是与 widget 关联的字符串 ID。对于单值微件，该值以单元素数组显示。对于多值微件（例如复选框组），所有值都会显示在列表中。

对于 Google Workspace 插件，请在 eventObject.commonEventObject.formInputs 字段中找到此信息。
eventObject.parameters object
已弃用。您使用 Action.setParameters() 向 Action 提供的任何其他参数的映射。映射键和值都是字符串。

对于 Google Workspace 插件，请在 eventObject.commonEventObject.parameters 字段中找到此信息。
eventObject.userCountry string
默认情况下，已弃用和停用。由两个字母组成的代码，指示用户所在的国家或地区。也可能是数字形式的 UN M49 国家/地区代码。

对于 Google Workspace 插件，请在 eventObject.commonEventObject.userLocale 字段中找到此信息。
eventObject.userLocale string
默认情况下，已弃用和停用。由两个字母组成的 ISO 639 代码，指示用户的语言。如需了解详情，请参阅访问用户语言区域和时区。

对于 Google Workspace 插件，请在 eventObject.commonEventObject.userLocale 字段中找到此信息。
eventObject.userTimezone.id string
默认情况下，已弃用和停用。用户所在时区的 时区标识符。示例包括：America/New_York、Europe/Vienna 和 Asia/Seoul。如需了解详情，请参阅 访问用户语言区域和时区。

对于 Google Workspace 插件，请在 eventObject.commonEventObject.timeZone.id 字段中找到此信息。
eventObject.userTimezone.offset string
默认情况下，已弃用和停用。用户时区的 世界协调时间 (UTC) 时间偏移（以毫秒为单位）。如需了解详情，请参阅 访问用户语言区域和时区。

对于 Google Workspace 插件，请在 eventObject.commonEventObject.timeZone.offset 字段中找到此信息。

常见事件对象

通用事件对象是整个事件对象的一部分，会将来自客户端的客户端的常规主机信息传送到插件。这些信息包括用户语言区域、托管应用和平台等详细信息。

除了首页和上下文触发器之外，当用户与 widget 互动时，插件还会构建事件对象并将其传递给操作回调函数。您的插件的回调函数可以查询通用事件对象，以确定用户客户端中打开的 widget 的内容。例如，您的插件可以定位用户在 eventObject.commentEventObject.formInputs 对象的 TextInput 微件中输入的文本。

常见的事件对象字段
commonEventObject.platform string
表示事件的发起位置（“WEB”、“IOS”或“ANDROID”）。
commonEventObject.formInputs object
此地图包含显示的卡片中 widget 的当前值。映射键是为每个 widget 分配的字符串 ID。

地图值对象的结构取决于 widget 类型：

  • 单值 widget（例如文本框）：字符串列表（只有一个元素）。

    示例：对于以 employeeName 作为 ID 的文本输入微件，请使用 e.commonEventObject.formInputs.employeeName.stringInputs.value[0] 访问文本输入值。

  • 多值 widget（例如复选框组）：字符串列表。

    示例：对于以 participants 作为 ID 的多值 widget，请使用 e.commonEventObject.formInputs.participants.stringInputs.value 访问值数组。

  • A date-time picker：一个 DateTimeInput object。

    示例：对于 ID 为 myDTPicker 的选择器，请使用 e.commonEventObject.formInputs.myDTPicker.dateTimeInput 访问 DateTimeInput 对象。

  • A date-only picker：一个 DateInput object。

    示例：对于 ID 为 myDatePicker 的选择器，请使用 e.commonEventObject.formInputs.myDatePicker.dateInput 访问 DateInput 对象。

  • A time-only picker：一个 TimeInput object。

    示例：对于 ID 为 myTimePicker 的选择器，请使用 e.commonEventObject.formInputs.myTimePicker.timeInput 访问 TimeInput 对象。
commonEventObject.hostApp string
表示在生成事件对象时，插件在哪些主机应用中处于活动状态。可取值包括：
  • GMAIL
  • CALENDAR
  • DRIVE
  • DOCS
  • SHEETS
  • SLIDES
commonEventObject.parameters object
您使用 Action.setParameters() 提供给 Action 的所有其他参数。
commonEventObject.userLocale string
默认处于停用状态。用户的语言和国家/地区标识符，采用 ISO 639 语言代码 - ISO 3166 国家/地区代码。例如 en-US。

如需启用此字段，您必须在插件的清单中将 addOns.common.useLocaleFromApp 设置为 true。插件的范围列表还必须包含 https://www.googleapis.com/auth/script.locale。如需了解详情，请参阅 访问用户语言区域和时区。
commonEventObject.timeZone string
默认处于停用状态。时区 ID 和偏移量。如需启用此字段，您必须在插件的清单中将 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 字段中的当前 widget 值。这包括用户在日期或时间选择器 widget 中选择的日期或时间值。但是，信息的结构会因该 widget 是配置为日期时间选择器、仅限日期的选择器还是仅限时间的选择器而异。结构差异如下表所述：

DateTimeInput 对象
dateTimeInput.hasDate boolean
true如果输入日期时间包含日期，则false仅包含时间。
dateTimeInput.hasTime boolean
true（如果输入日期时间包含时间）；如果 false，则仅包含日期。
dateTimeInput.msSinceEpoch string
用户选择的时间，以从公元纪年（1970 年 1 月 1 日 00:00:00）开始计算的毫秒数表示。
DateInput 对象
dateInput.msSinceEpoch string
用户选择的时间，以从公元纪年（1970 年 1 月 1 日 00:00:00）开始计算的毫秒数表示。
TimeInput 对象
timeInput.hours number
用户选择的小时数。
timeInput.minutes number
用户选择的分钟数。

日历活动对象

日历活动对象是整个活动对象中携带用户日历和日历活动相关信息的部分。仅当主应用是 Google 日历时，它才会显示在事件对象中。

下表列出了事件对象的 calendarEventObject 字段。当且仅当数据存在于日历活动中且插件将其 addOns.calendar.currentEventAccess 清单字段设置为 READ 或 READ_WRITE 时，事件对象中才会出现标记为用户生成的数据的字段。

日历活动对象
calendar.attendees[] list of attendee objects
用户生成的数据。日历活动的参加者列表。
calendar.calendarId string
日历 ID。
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
事件 ID。
calendar.organizer object
表示事件组织者的对象。
calendar.organizer.email string
活动组织者的电子邮件地址。
calendar.recurringEventId string
周期性活动的 ID。

参加者

参加者对象包含有关 Google 日历活动各个参加者的信息。当且仅当日历活动中存在数据，并且插件将其 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
参加者的回复状态。可取值包括：
  • accepted：参加者已接受活动邀请。
  • declined：参加者拒绝了活动邀请。
  • needsAction：参加者尚未回复活动邀请。
  • tentative：参加者已暂时接受活动邀请。
attendee.self boolean
true（如果此参加者表示显示此活动的日历）；否则，值为 false。

会议数据

会议数据对象包含附加到 Google 日历活动的会议的相关信息。这些解决方案可以是 Google 会议解决方案，例如 Google Meet 或第三方会议。当且仅当日历活动中存在数据，并且插件将其 addOns.calendar.currentEventAccess 清单字段设置为 READ 或 READ_WRITE 时，该信息才会显示在事件对象中。

会议数据对象
conferenceData.conferenceId string
会议的 ID。此 ID 供应用跟踪会议，您不应向用户显示此 ID。
conferenceData.conferenceSolution object
一个表示会议解决方案的对象，例如 Hangouts 或 Google Meet。
conferenceData.conferenceSolution.iconUri string
表示此会议解决方案的用户可见图标的 URI。
conferenceData.conferenceSolution.key object
用于唯一标识此事件的会议解决方案的键。
conferenceData.conferenceSolution.key.type string
会议解决方案类型。可取值包括：
  • eventHangout（适用于个人用户版 Hangouts）(http://hangouts.google.com)。
  • eventNamedHangout，适用于 Google Workspace 用户的传统版 Hangouts (http://hangouts.google.com)。
  • hangoutsMeet（适用于 Google Meet）(http://meet.google.com)。
conferenceData.conferenceSolution.name string
此会议解决方案的用户可见名称（未本地化）。
conferenceData.entryPoints[] list of entry point objects
视频会议入口点的列表，例如网址或电话号码。
conferenceData.notes string
向用户显示的会议的其他说明（例如，来自网域管理员的说明或法律声明）。可以包含 HTML。最大长度为 2048 个字符。
conferenceData.parameters object
一个对象，其中包含插件定义的已定义参数数据映射。
conferenceData.parameters.addOnParameters object
由参数字符串键和值组成的映射。 这些键和值由插件开发者定义，以将信息附加到特定会议，以供插件使用。

入口点

入口点对象包含关于用户通过特定方式（例如电话或视频）参加指定会议的信息。当且仅当数据存在于日历活动中且插件将其 addOns.calendar.currentEventAccess 清单字段设置为 READ 或 READ_WRITE 时，事件对象中才会显示该信息。

入口点对象
entryPoint.accessCode string
用于访问会议的访问代码。 最大长度为 128 个字符。会议服务提供商通常仅使用 {accessCode, meetingCode, passcode, password, pin} 的子集以提供会议访问权限。匹配，并且始终仅显示会议服务提供商使用的字段。
entryPoint.entryPointFeatures list
入口点的功能。目前，这些功能仅适用于 phone 入口点：
  • toll：入口点是收费电话。
  • toll_free：入口点是免费电话。
entryPoint.entryPointType string
入口点的类型。可能的值包括：
  • more：其他会议加入说明，例如备用电话号码。会议只能有一个 more 入口点；如果存在，则至少还要提供一种其他类型的入口点。
  • phone：通过电话号码加入会议。一个会议可以有零个或多个phone入口点。按格式排序并按字母顺序排序后，Google 日历仅显示前两个手机入口点。
  • sip：通过 SIP 加入会议。一个会议最多只能有一个 sip 入口点。
  • video：通过 HTTP 加入会议。一个会议最多只能有一个 video 入口点。
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 个字符。格式取决于入口点类型：
  • more：需要 http: 或 https: 架构。
  • phone：必须提供 tel: 架构。URI 应包含整个拨号序列（例如，“tel:+12345678900,,12345678;1234”）。
  • sip：需要 sip: 或 sips: 架构。例如“sip:12345678@myprovider.com”。
  • video：需要 http: 或 https: 架构。

云端硬盘事件对象

云端硬盘事件对象是携带用户 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
所选内容的 ID。
item.iconUrl string
表示所选项的图标的网址。
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 邮件的 ID。
gmail.threadId string
当前打开的 Gmail 会话 ID。
gmail.toRecipients[] list of strings
默认处于停用状态。插件正在撰写的草稿中目前包含的“收件人：”收件人电子邮件地址列表。如需开启此字段，您必须将清单中的 addOns.gmail.composeTrigger.draftAccess 字段设置为 METADATA。

Google 文档事件对象

Docs 事件对象是包含用户文档及其内容相关信息的整个事件对象的一部分。仅当主应用是 Google 文档时，它才会出现在事件对象中。

Google 文档事件对象
docs.id string
只有在 https://www.googleapis.com/auth/drive.file 范围已获得用户授权时，才会显示。
在文档界面中打开的文档 ID。
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
仅在满足以下条件时存在：
  • https://www.googleapis.com/auth/workspace.linkpreview 已由该用户授权。
  • 网址与 LinkPreviewTriggers 触发器中指定的主机格式匹配。

用于在 Google 文档中生成预览的链接的网址。如要使用此字段，您必须在插件的清单中配置 LinkPreviewTriggers。如需了解详情，请参阅 Google 文档中的预览链接。

用户预览链接 https://www.example.com/12345 时的载荷示例： 

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}

Google 表格事件对象

表格事件对象是整个事件对象中携带用户文档及其内容相关信息的部分。仅当主应用是 Google 表格时，它才会出现在事件对象中。

Google 表格事件对象
sheets.id string
仅当 https://www.googleapis.com/auth/drive.file 范围已获得用户授权时，此字段才会显示。在 Google 表格界面中打开的电子表格的 ID。
sheets.title string
仅当 https://www.googleapis.com/auth/drive.file 范围已获得用户授权时，此字段才会显示。在 Google 表格界面中打开的电子表格的标题。
sheets.addonHasFileScopePermission boolean
如果为 true，则插件会请求并接收在表格界面中打开的电子表格的 https://www.googleapis.com/auth/drive.file 范围授权；否则，此字段为 false。

Google 幻灯片事件对象

幻灯片事件对象是整个事件对象中承载用户文档及其内容相关信息的部分。仅当主应用是 Google 幻灯片时，它才会出现在事件对象中。

Google 幻灯片事件对象
slides.id string
仅当 https://www.googleapis.com/auth/drive.file 范围已获得用户授权时，此字段才会显示。在幻灯片界面中打开的演示文稿 ID。
slides.title string
仅当 https://www.googleapis.com/auth/drive.file 范围已获得用户授权时，此字段才会显示。在 Google 幻灯片界面中打开演示文稿的标题。
slides.addonHasFileScopePermission boolean
如果为 true，则插件已请求并获得在幻灯片界面中打开的演示文稿的 https://www.googleapis.com/auth/drive.file 范围授权；否则，此字段为 false。