本頁面概略說明 Google Workspace 外掛程式事件物件的結構。
事件物件是 JSON 結構,會在使用者與外掛程式互動時自動建構,並以參數的形式傳遞至觸發或回呼函式。事件物件會將主機應用程式和目前情境的用戶端資訊,傳送至外掛程式的伺服器端回呼函式。
Google Workspace 外掛程式會在以下位置使用事件物件:
首頁觸發條件。當首頁觸發事件函式觸發時,系統會自動將事件物件傳遞至您定義的每個
homepageTrigger
函式。您可以在首頁觸發事件函式中使用這個物件,識別目前的主機應用程式、用戶端的平台、使用者語言代碼和其他資訊。首頁觸發事件時建立的事件物件不包含其他兩種情況中的所有欄位,而是省略了與小工具和內容相關資訊相關的欄位。
內容比對觸發條件。每個主機應用程式都會提供一組不同的情境觸發事件,在使用者進入特定情境時觸發。例如:
- Gmail 提供兩種內容觸發條件,分別是使用者開啟郵件時,以及使用者撰寫郵件時。
- Google 日曆會在使用者開啟活動時提供內容觸發事件。
- Google 雲端硬碟提供內容觸發條件,可在使用者選取雲端硬碟檔案時觸發。
當內容觸發事件觸發時,主機應用程式會呼叫外掛程式資訊清單中列出的對應
runFunction
,並將事件物件做為參數傳遞。觸發情境觸發事件時建立的事件物件,包含了主頁面觸發事件物件中的所有欄位,以及包含情境資訊的欄位。小工具動作:事件物件也可用於提供 小工具互動功能,使用與 Gmail 外掛程式相同的動作模型。Google Workspace 外掛程式會使用相同的小工具處理常式函式、
Action
物件和動作回應。不過,在 Google Workspace 外掛程式中,動作事件物件包含了回呼函式可處理的更多資訊。小工具動作產生的事件物件包含內容觸發事件物件中的所有欄位,以及包含小工具資訊的欄位。
預覽連結觸發事件。在 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 文件時才會顯示。包含文件資訊的物件。 |
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 UI 中開啟的討論串訊息 ID。
如為 Google Workspace 外掛程式,請在 |
eventObject.clientPlatform |
string 已淘汰。表示事件來源 (網站、iOS 或 Android)。
如為 Google Workspace 外掛程式,請在 |
eventObject.formInput |
object 已淘汰。資訊卡中所有表單小工具目前的值對應,每個小工具僅限一個值。鍵是與小工具相關聯的字串 ID,值則是字串。事件物件會提供 formInput ,方便您從多個小工具讀取資料,這些小工具具有預期的單一值,例如文字輸入和切換鈕。針對多值小工具 (例如核取方塊),您可以改為從 formInputs 讀取每個值。
如為 Google Workspace 外掛程式,請改為在 |
eventObject.formInputs |
object 已淘汰。資訊卡中小工具目前值的對應表,以字串清單呈現。鍵是與小工具相關聯的字串 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 已淘汰,並預設為停用。使用者時區的 時區 ID。例如: America/New_York 、Europe/Vienna 和 Asia/Seoul 。詳情請參閱「
存取使用者語言代碼和時區」。
如為 Google Workspace 外掛程式,請在 |
eventObject.userTimezone.offset |
string 已淘汰,並預設為停用。使用者時區的 與世界標準時間 (UTC) 之間的時間偏移,以毫秒為單位。詳情請參閱「 存取使用者語言代碼和時區」。
如為 Google Workspace 外掛程式,請在 |
通用事件物件
通用事件物件是整體事件物件的一部分,可將一般、不依主機的資訊從使用者用戶端傳送至外掛程式。這些資訊包括使用者的語言代碼、主機應用程式和平台等詳細資料。
除了主畫面和內容觸發條件之外,使用者與小工具互動時,外掛程式也會建構並將事件物件傳遞至動作回呼函式。外掛程式的回呼函式可以查詢常見的事件物件,以判斷使用者用戶端中開啟的小工具內容。舉例來說,外掛程式可以找出使用者在 eventObject.commentEventObject.formInputs
物件中 TextInput
小工具中輸入的文字。
常見的事件物件欄位 | |
---|---|
commonEventObject.platform |
string :表示事件來源 (「WEB」、「IOS」或「ANDROID」)。 |
commonEventObject.formInputs |
object 含有顯示資訊卡中小工具目前值的對應表。地圖索引鍵是指派給每個小工具的字串 ID。 地圖值物件的結構取決於小工具類型:
|
commonEventObject.hostApp |
string :指出在事件物件產生時,外掛程式在哪個主機應用程式中處於啟用狀態。可能的值包括:
|
commonEventObject.parameters |
object 您使用 actionParameters 或
Action.setParameters() 為動作提供的任何額外參數。開發人員預覽版: 如果擴充 Google 聊天的外掛程式要根據使用者在多重選取選單中輸入的內容建議項目,請使用 |
commonEventObject.userLocale |
string 預設為停用。使用者的語言和國家/地區 ID,格式為 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 使用者時區的 時區 ID。例如: 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 日曆 ID。 |
calendar.capabilities |
object 使用者產生的資料。描述外掛程式可用來查看或更新事件資訊的功能的物件。 |
calendar.capabilities.canAddAttendees |
boolean 使用者產生的資料。 true
如果外掛程式可以將新參與者新增至活動參與者名單,則為 true ;否則為 false 。 |
calendar.capabilities.canSeeAttendees |
boolean 使用者產生的資料。 true :如果外掛程式可以讀取活動出席者名單,則為 false ,否則為 false 。 |
calendar.capabilities.canSeeConferenceData |
boolean 使用者產生的資料。 true
如果外掛程式可以讀取事件會議資料,則為 false ;否則為空白。 |
calendar.capabilities.canSetConferenceData |
boolean 使用者產生的資料。 true :如果外掛程式可以更新事件會議資料,則為 false ,否則為 false 。 |
calendar.capabilities.canAddAttachments |
boolean 使用者產生的資料。 true
如果外掛程式可在活動中新增附件,則為 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 與會者的回覆狀態。可能的值包括:
|
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 目前有效的 Google 雲端硬碟項目。 |
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 文件事件物件
Docs 事件物件是整體事件物件的一部分,可提供使用者文件及其內容的相關資訊。只有在主機應用程式為 Google 文件時,這項屬性才會出現在事件物件中。
Google 文件事件物件 | |
---|---|
docs.id |
string 只有在使用者授予
https://www.googleapis.com/auth/drive.file 範圍權限時才會顯示。在 Google 文件 UI 中開啟的文件 ID。 |
docs.title |
string 只有在使用者授予
https://www.googleapis.com/auth/drive.file 範圍權限時才會顯示。在 Google 文件 UI 中開啟的文件標題。 |
docs.addonHasFileScopePermission |
boolean 如果為 true ,表示外掛程式已要求並取得 https://www.googleapis.com/auth/drive.file 範圍授權,以便在 Google 文件 UI 中開啟文件;否則,這個欄位為 false 。 |
docs.matchedUrl.url |
string
只有在符合下列條件時才會顯示:
在 Google 文件中產生預覽畫面的連結網址。如要使用這個欄位,您必須在外掛程式的資訊清單中設定 LinkPreviewTriggers 。詳情請參閱「使用智慧型方塊預覽連結」。
使用者預覽連結 "docs" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |
試算表事件物件
Sheets 事件物件是整體事件物件的一部分,可提供使用者文件及其內容的相關資訊。只有在主機應用程式為 Google 試算表時,這個屬性才會出現在事件物件中。
試算表事件物件 | |
---|---|
sheets.id |
string 只有在使用者授予
https://www.googleapis.com/auth/drive.file 範圍權限時才會顯示。在試算表 UI 中開啟的試算表 ID。 |
sheets.title |
string 只有在使用者授予
https://www.googleapis.com/auth/drive.file 範圍權限時才會顯示。在 Google 試算表 UI 中開啟的試算表名稱。 |
sheets.addonHasFileScopePermission |
boolean 如果為 true ,表示外掛程式已要求並取得 https://www.googleapis.com/auth/drive.file 範圍授權,可存取在試算表 UI 中開啟的試算表;否則,這個欄位為 false 。 |
sheets.matchedUrl.url |
string
只有在符合下列條件時才會顯示:
在 Google 試算表中產生預覽畫面的連結網址。如要使用這個欄位,您必須在外掛程式的資訊清單中設定 LinkPreviewTriggers 。詳情請參閱「使用智慧型方塊預覽連結」。
使用者預覽連結 "sheets" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |
幻燈片事件物件
Google 簡報事件物件是整體事件物件的一部分,可提供使用者文件及其內容的相關資訊。只有在主機應用程式為 Google 簡報時,這個屬性才會出現在事件物件中。
幻燈片事件物件 | |
---|---|
slides.id |
string 只有在使用者授予
https://www.googleapis.com/auth/drive.file 範圍權限時才會顯示。在 Google 簡報 UI 中開啟的簡報 ID。 |
slides.title |
string 只有在使用者授予
https://www.googleapis.com/auth/drive.file 範圍權限時才會顯示。在 Google 簡報 UI 中開啟的簡報標題。 |
slides.addonHasFileScopePermission |
boolean 如果為 true ,表示外掛程式已要求並取得 https://www.googleapis.com/auth/drive.file 範圍授權,可在 Google 簡報 UI 中開啟簡報;否則,這個欄位為 false 。 |
slides.matchedUrl.url |
string
只有在符合下列條件時才會顯示:
在 Google 簡報中產生預覽畫面的連結網址。如要使用這個欄位,您必須在外掛程式的資訊清單中設定 LinkPreviewTriggers 。詳情請參閱「使用智慧型方塊預覽連結」。
使用者預覽連結 "slides" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |