本页面简要介绍了 Google Workspace 插件事件对象的结构。
事件对象是 JSON 结构,可在用户与插件互动时自动构建并作为参数传递,以触发或回调函数。事件对象会将有关托管应用和当前上下文的客户端信息传送到插件的服务器端回调函数。
Google Workspace 插件会在以下位置使用事件对象:
首页触发器。 在首页触发器函数触发时,您定义的每个
homepageTrigger
函数都会自动传递一个事件对象。您可以在首页触发器函数中使用此对象来识别活跃的托管应用、客户端的平台、用户语言区域和其他信息。首页触发器触发时创建的事件对象不包含其他两种情况下包含的所有字段;与 widget 和上下文信息相关的字段会省略。
内容相关触发器。每个主机应用提供一组不同的上下文触发器,在用户进入特定上下文时触发。例如:
当上下文触发器触发时,托管应用会调用插件清单中列出的相应
runFunction
,并向其传递事件对象作为参数。上下文触发器触发时创建的事件对象包含首页触发器事件对象中包含的所有字段,以及包含上下文信息的字段。微件操作。事件对象也用于提供 widget 互动,使用 Gmail 插件所用的操作模型。Google Workspace 插件使用相同的微件处理程序函数、
Action
对象和操作响应。但是,在 Google Workspace 插件中,操作事件对象包含可供回调函数处理的更多信息。作为微件操作的结果创建的事件对象包含上下文触发器事件对象中包含的所有字段,以及包含微件信息的字段。
预览链接触发器。 在 Google 文档、表格和幻灯片中,您可以根据特定网址格式为第三方服务配置链接预览。当用户与符合该模式的链接互动时,会触发
linkPreviewTriggers
,并且系统会将包含该链接的事件对象传递给触发器的回调函数。您的插件可以使用此事件对象构建智能条状标签和卡片,以在宿主应用中显示链接的相关信息。您还可以构建 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 文档时,此字段才会显示。包含 Google 文档信息的对象。 |
eventObject.sheets |
Sheets event object
仅当调用主机是 Google 表格时,此字段才会显示。包含 Google 表格信息的对象。 |
eventObject.slides |
Slides event object
仅当发起调用的主持人是 Google 幻灯片时,此字段才会显示。包含幻灯片信息的对象。 |
原始 Gmail 插件字段 | |
eventObject.messageMetadata.accessToken |
string 已弃用。访问令牌。您可以使用此方法开启通过临时 Gmail 插件范围访问用户数据的权限。
对于 Google Workspace 插件,请在 |
eventObject.messageMetadata.messageId |
string 已弃用。在 Gmail 界面中打开的会话的邮件 ID。
对于 Google Workspace 插件,请在 |
eventObject.clientPlatform |
string 已弃用。指明事件的来源(Web、iOS 或 Android)。
对于 Google Workspace 插件,请在 |
eventObject.formInput |
object 已弃用。卡片中所有表单微件的当前值的映射,每个微件仅限一个值。键是与微件关联的字符串 ID,值为字符串。当您需要从具有预期奇异值的多个微件(例如文本输入和开关)读取数据时,事件对象提供了 formInput 以方便。对于多值微件(如复选框),您可以改为从 formInputs 读取每个值。
对于 Google Workspace 插件,请改为在 |
eventObject.formInputs |
object 已弃用。卡片中 widget 的当前值的映射,以字符串列表的形式呈现。键是与微件关联的字符串 ID。对于单值微件,该值显示在单元素数组中。对于多值微件(例如复选框组),所有值都以列表形式显示。
对于 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 互动时构建事件对象并将其传递给操作回调函数。插件的回调函数可以查询通用事件对象,以确定用户客户端中打开的 widget 的内容。例如,您的插件可以在 eventObject.commentEventObject.formInputs
对象中找到用户在 TextInput
widget 中输入的文本。
常见的事件对象字段 | |
---|---|
commonEventObject.platform |
string 指示事件的来源(“WEB”“IOS”或“ANDROID”)。 |
commonEventObject.formInputs |
object 包含所显示卡片中 widget 的当前值的映射。映射键是为每个 widget 分配的字符串 ID。 映射值对象的结构取决于 widget 类型:
|
commonEventObject.hostApp |
string 用于指示在生成事件对象时插件处于哪个托管应用中。可能的值包括下列项:
|
commonEventObject.parameters |
object 您使用
Action.setParameters() 提供给
Action 的其他任何参数。
|
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 中选择的日期或时间值。不过,根据微件是配置为日期时间选择器、仅日期选择器还是仅时间选择器,信息的结构会有所不同。下表介绍了结构差异:
日历活动对象
日历事件对象是整个事件对象的一部分,其中包含有关用户日历和日历活动的信息。仅当托管应用是 Google 日历时,此事件才会出现在事件对象中。
下表列出了事件对象的 calendarEventObject
字段中显示的字段。当且仅当 Google 日历事件中存在标记为用户生成的内容的字段,且该插件将其 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 参加者表示会邀请的额外邀请对象的人数。默认值为 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
清单字段设置为 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 参数字符串键和值的映射。 这些键和值由插件开发者定义,以将信息附加到特定会议以供该插件使用。 |
入口点
入口点对象携带有关访问指定会议的既定方式的信息,例如电话或视频。当且仅当日历活动中存在数据,并且插件将其 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 所选项的 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 范围时才存在。在 Google 文档界面中打开的文档的标题。 |
docs.addonHasFileScopePermission |
boolean 如果为 true ,表示插件已针对在 Google 文档界面中打开的文档请求并获得 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 范围时才存在。在表格界面中打开的电子表格的 ID。
|
sheets.title |
string 仅当用户授权
https://www.googleapis.com/auth/drive.file 范围时才存在。在表格界面中打开的电子表格的标题。
|
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 幻灯片时,事件对象中才会显示此事件。
幻灯片事件对象 | |
---|---|
slides.id |
string 仅当用户授权
https://www.googleapis.com/auth/drive.file 范围时才存在。在幻灯片界面中打开的演示文稿的 ID。
|
slides.title |
string 仅当用户授权
https://www.googleapis.com/auth/drive.file 范围时才存在。在幻灯片界面中打开的演示文稿的标题。
|
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" } } |