本页面概述了 Google Workspace 插件事件对象的结构。
事件对象是 JSON 结构,系统会在用户与插件互动时自动构建这些结构,并将其作为参数传递给触发函数或回调函数。事件对象会将有关托管应用和当前上下文的客户端信息传递到插件服务器端回调函数。
Google Workspace 插件会在以下位置使用事件对象:
首页触发器。 当首页触发器函数触发时,系统会自动向您定义的每个
homepageTrigger
函数传递一个事件对象。您可以在首页触发器函数中使用此对象来识别活跃的托管应用、客户端的平台、用户语言区域和其他信息。在首页触发器触发时创建的事件对象不包含其他两种情况下包含的所有字段;系统会省略与微件和情境信息相关的字段。
内容相关触发器。 每个托管应用都会提供一组不同的情境触发器,这些触发器会在用户进入特定情境时触发。例如:
- Gmail 提供了一个上下文触发器,用于在用户打开邮件时触发,还提供了另一个上下文触发器,用于在用户撰写邮件时触发。
- Google 日历针对用户打开活动时提供了情境触发器。
- Google 云端硬盘提供了一个上下文触发器,用于在用户选择云端硬盘文件时触发。
当情境触发器触发时,托管应用会调用插件清单中列出的相应
runFunction
,并将事件对象作为参数传递给它。在情境触发器触发时创建的事件对象包含首页触发器事件对象中包含的所有字段,以及包含情境信息的字段。微件操作。事件对象还用于使用 Gmail 插件使用的相同操作模型提供微件互动性。Google Workspace 插件使用完全相同的 widget 处理程序函数、
Action
对象和操作响应。不过,在 Google Workspace 插件中,操作事件对象包含回调函数可以处理的更多信息。作为 widget 操作的结果而创建的事件对象包含情境触发器事件对象中包含的所有字段,以及包含 widget 信息的字段。
预览链接触发器。 在 Google 文档、表格和幻灯片中,您可以根据特定网址格式为第三方服务配置链接预览。当用户与符合模式的链接互动时,系统会触发
linkPreviewTriggers
,并将包含链接的事件对象传递给触发器的回调函数。您的插件可以使用此事件对象构建智能条状标签和卡片,以便在托管应用中显示与链接相关的信息。您还可以构建微件操作,让用户与预览卡片及其内容进行互动。Google Chat 应用触发器(开发者预览版)。在 Google Chat 中,您的插件会显示为 Chat 应用,用户可以通过将其添加到聊天室、发送消息、使用斜杠命令等方式与其互动。如需构建互动功能,您需要设置和使用各种 Chat 应用触发器。每个触发器都会发送不同的事件对象载荷,以帮助您处理或响应每种类型的互动。
事件对象结构
下表介绍了 Google Workspace 插件事件对象的顶级结构。事件对象结构包含一个 commonEventObject
顶级字段,用于存储与主机无关的信息。每个事件对象还可以包含以下特定于主机的顶级字段之一,具体取决于当前的主机应用:gmailEventObject
、calendarEventObject
或 driveEventObject
。
为了实现向后兼容,Google Workspace 插件事件对象还包含 Gmail 插件操作事件对象中使用的所有原始字段。这些字段列在下表中的“原始 Gmail 插件字段”下;这些字段中的信息会在新对象结构中重现。
事件对象 | |
---|---|
eventObject.commonEventObject |
Common fields object
一个对象,其中包含所有事件对象(无论是哪种托管应用)共有的信息。 |
eventObject.calendar |
Calendar event object
仅当调用主机为 Google 日历时才会存在。一个包含日历和活动信息的对象。 |
eventObject.chat |
Chat event object
仅当发起通话的主持人是 Google Chat 时才会出现。一个包含 Chat 信息的对象。 |
eventObject.drive |
Drive event object
仅当调用主机为 Google 云端硬盘时才会存在。一个包含云端硬盘信息的对象。 |
eventObject.gmail |
Gmail event object
仅当调用方主机为 Gmail 时才会存在。一个包含 Gmail 信息的对象。 |
eventObject.docs |
Docs event object
仅当调用主机为 Google 文档时才会存在。一个包含 Google 文档信息的对象。 |
eventObject.sheets |
Sheets event object
仅当调用方主机为 Google 表格时才会存在。一个包含 Google 表格信息的对象。 |
eventObject.slides |
Slides event object
仅当调用方主机为 Google 幻灯片时才会存在。一个包含 Google 幻灯片信息的对象。 |
原始 Gmail 插件字段 | |
eventObject.messageMetadata.accessToken |
string 已废弃。访问令牌。您可以使用此 API 启用使用临时 Gmail 插件作用域访问用户数据的权限。
对于 Google Workspace 插件,请在 |
eventObject.messageMetadata.messageId |
string 已废弃。在 Gmail 界面中打开的会话串的邮件 ID。
对于 Google Workspace 插件,请在 |
eventObject.clientPlatform |
string 已废弃。指明事件的来源平台(网站、iOS 或 Android)。
对于 Google Workspace 插件,请在 |
eventObject.formInput |
object 已废弃。卡片中所有表单 widget 的当前值的映射,每个 widget 的值不得超过 1 个。键是与 widget 关联的字符串 ID,值是字符串。当您需要从多个具有预期单值的 widget(例如文本输入框和���关)读取数据时,事件对象会提供 formInput 以方便您使用。对于多值 widget(例如复选框),您可以改为从 formInputs 读取每个值。
对于 Google Workspace 插件,请改为在 |
eventObject.formInputs |
object 已废弃。卡片中微件的当前值的映射,以字符串列表的形式呈现。键是与微件关联的字符串 ID。对于单值 widget,值以单元素数组的形式显示。对于多值 widget(例如复选框组),所有值都会显示在列表中。
对于 Google Workspace 插件,请在 |
eventObject.parameters |
object 已废弃。您使用 Action.setParameters() 向
Action 提供的任何其他参数的映射。映射键和值均为字符串。
对于 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 插件,请在 |
常见事件对象
常规事件对象是整个事件对象的一部分,用于将与主机无关的一般信息从用户的客户端传递到插件。这些信息包括用户的语言区域、托管应用和平台等详细信息。
除了首页触发器和情境触发器之外,当用户与微件互动时,插件还会构建事件对象并将其传递给操作回调函数。您的插件回调函数可以查询通用事件对象,以确定用户客户端中打开的 widget 的内容。例如,您的插件可以在 eventObject.commentEventObject.formInputs
对象中找到用户输入到 TextInput
widget 中的文本。
常见事件对象字段 | |
---|---|
commonEventObject.platform |
string 表示事件的来源(“WEB”“IOS”或“ANDROID”)。 |
commonEventObject.formInputs |
object 一个映射,其���包含显示的卡片中微件的当前值。映射键是分配给每个 widget 的字符串 ID。 映射值对象的结构取决于 widget 类型:
|
commonEventObject.hostApp |
string 表示在生成事件对象时插件处于活动状态的主机应用。可能的值包括:
|
commonEventObject.parameters |
object 您使用 actionParameters 或
Action.setParameters() 向操作提供的任何其他参数。
开发者预览版 :对于扩展 Google Chat 的插件,如需根据用户在多选菜单中输入的内容建议项,请使用 |
commonEventObject.userLocale |
string 默认处于停用状态。用户的语言和国家/地区标识符,格式为 ISO 639 语言代码-ISO 3166 国家/地区代码。例如 en-US 。
如需启用此字段,您必须在插件清单中将 |
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 是配置为日期时间选择器、仅日期选择器还是仅时间选择器而异。下表介绍了结构差异:
日历活动对象
日历活动对象是整个活动对象的一部分,用于携带用户日历和日历活动的相关信息。只有当托管应用是 Google 日历时,此属性才会出现在事件对象中。
下表列出了事件对象的 calendarEventObject
字段中存在的字段。只有当日历活动中存在数据,并且插件将其 addOns.calendar.currentEventAccess
manifest字段设为 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。 |
参加者
Attendee 对象包含 Google 日历活动的各位参加者的信息。只有当日历活动中存在数据且插件将其 addOns.calendar.currentEventAccess
manifest字段设置为 READ
或 READ_WRITE
时,事件对象中才会包含此信息。
参加者对象 | |
---|---|
attendee.additionalGuests |
number 参加者已表明要携带的额外宾客人数。默认值为 0。 |
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),也可以是第三方会议。只有当日历活动中存在数据且插件将其 addOns.calendar.currentEventAccess
manifest字段设置为 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 会议解决方案类型。可能的值包括:
|
conferenceData.conferenceSolution.name |
string 此会议解决方案的用户可见名称(非本地化)。 |
conferenceData.entryPoints[] |
list of entry point objects
会议入口点列表,例如网址或电话号码。 |
conferenceData.notes |
string 要向用户显示的有关会议的其他备注(例如网域管理员的���明或法律通知)。可以包含 HTML。长度上限为 2048 个字符。 |
conferenceData.parameters |
object 一个对象,包含要供插件使用的已定义参数数据的映射。 |
conferenceData.parameters.addOnParameters |
object 参数字符串键值对的映射。 这些键和值由插件开发者定义,用于将信息附加到特定会议,以便插件使用。 |
入口点
入口点对象包含有关访问给定会议的已建立方式(例如通过电话或视频)的信息。只有当 Google 日历活动中存在数据且插件将其 addOns.calendar.currentEventAccess
manifest字段设置为 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 个字符。格式取决于入口点类型:
|
云端硬盘事件对象
Drive 事件对象是整个事件对象的一部分,用于携带有关用户 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 默认处于停用状态。该插件正在撰写的草稿中当前包含的“抄送”收件人电子邮件地址列表。如需启用此字段,您必须将清单中的 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 文档事件对象
Google 文档事件对象是整个事件对象的一部分,用于携带有关用户文档及其内容的信息。只有当托管应用是 Google 文档时,此属性才会出现在事件对象中。
Google 文档事件对象 | |
---|---|
docs.id |
string 仅当用户已授权
https://www.googleapis.com/auth/drive.file 范围时才会出现。Google 文档界面中打开的文档的 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
仅当满足以下条件时才存在:
在 Google 文档中生成预览的链接的网址。如需使用此字段,您必须在插件清单中配置 LinkPreviewTriggers 。如需了解详情,请参阅包含智能条状标签的预览链接。
当用户预览链接 "docs" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |
Google 表格事件对象
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 ,则表示该插件已请求并获得了对 Google 表格界面中打开的电子表格的 https://www.googleapis.com/auth/drive.file 范围授权;否则,此字段为 false 。
|
sheets.matchedUrl.url |
string
仅当满足以下条件时才存在:
在 Google 表格中生成预览的链接的网址。如需使用此字段,您必须在插件清单中配置 LinkPreviewTriggers 。如需了解详情,请参阅包含智能条状标签的预览链接。
当用户预览链接 "sheets" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |
Google 幻灯片事件对象
Google 幻灯片事件对象是整个事件对象的一部分,用于携带用户文档及其内容的相关信息。只有在托管应用为 Google 幻灯片时,此属性才会出现在事件对象中。
Google 幻灯片事件对象 | |
---|---|
slides.id |
string 仅当用户授权了
https://www.googleapis.com/auth/drive.file 范围时才会出现。在 Google 幻灯片界面中打开的演示文稿的 ID。
|
slides.title |
string 仅当用户授权了
https://www.googleapis.com/auth/drive.file 范围时才会出现。在 Google 幻灯片界面中打开的演示文稿的标题。
|
slides.addonHasFileScopePermission |
boolean 如果为 true ,则表示该插件已请求并已获得对在幻灯片界面中打开的演示文稿的 https://www.googleapis.com/auth/drive.file 范围授权;否则,此字段为 false 。
|
slides.matchedUrl.url |
string
仅当满足以下条件时才存在:
在 Google 幻灯片中生成预览的链接的网址。如需使用此字段,您必须在插件清单中配置 LinkPreviewTriggers 。
如需了解详情,请参阅包含智能条状标签的预览链接。
当用户预览链接 "slides" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |