本頁概述 Google Workspace 外掛程式事件物件的結構。
事件物件是自動建立和傳遞的 JSON 結構 做為參數,當使用者與 外掛程式。事件物件會存放主機應用程式及 目前背景資訊。
Google Workspace 外掛程式會在以下位置使用事件物件:
首頁觸發條件: 您定義的每個
homepageTrigger
函式都會自動傳遞事件 物件。您可以在 您的首頁觸發函式,找出有效主機應用程式, 平台、使用者語言代碼以及其他資訊首頁觸發時建立的事件物件不包含所有 欄位。與小工具相關 會省略背景資訊。
內容比對觸發條件: 每個主機應用程式都提供一組不同的內容相關觸發條件, 會在使用者輸入特定情境時觸發。例如:
內容相關觸發條件啟動時,主機應用程式會呼叫 將相對應的
runFunction
傳送至外掛程式資訊清單,並傳遞 事件物件做為參數在內容比對期間建立的事件物件 觸發條件觸發條件包含首頁觸發事件中的所有欄位 物件,以及包含情境資訊的欄位。小工具動作:事件物件 也會用來提供小工具 以相同方式 Gmail 外掛程式的 Action Model 相關單位會如何運用資料,並讓他們覺得自己 獲得充分告知,且能夠針對該使用方式表示同意Google Workspace 外掛程式使用相同的小工具處理常式函式。
Action
物件和動作 回應。不過在 Google Workspace 外掛程式中 動作事件物件 為回呼函式提供更多可處理的資訊。因小工具動作而建立的事件物件含有 內容相關觸發事件物件中包含的欄位,以及包含
預覽連結觸發條件: 在 Google 文件、試算表和簡報中,你可以 設定第三方服務的連結預覽功能 方便您根據特定網址模式 進行修正當使用者與符合下列條件的連結互動時 因此
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 時才會顯示。物件 。 |
eventObject.docs |
Docs event object
只有在通話主辦人使用 Google 文件時才會顯示。物件 包含文件資訊 |
eventObject.sheets |
Sheets event object
只有在通話主辦人使用 Google 試算表時才會顯示。物件 。 |
eventObject.slides |
Slides event object
只有在通話的主辦人是 Google 簡報時才會顯示。物件 包含簡報資訊 |
原始 Gmail 外掛程式欄位 | |
eventObject.messageMetadata.accessToken |
string 已淘汰。存取權杖。別擔心!您可以使用 即可使用臨時 Gmail 外掛程式範圍存取使用者資料。
如需 Google Workspace 外掛程式的相關資訊,請參閱
|
eventObject.messageMetadata.messageId |
string 已淘汰。討論串的訊息 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 使用
Action.setParameters() 。對應鍵和值包括
字串。
如需 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 已淘汰並預設為停用。 與使用者協調的世界標準時間 時區 (以毫秒為單位)。詳情請見 存取使用者語言代碼和時區以瞭解詳情。
如需 Google Workspace 外掛程式的相關資訊,請參閱
|
常見事件物件
共同事件物件是整體事件物件的一部分,該物件包含 使用者用戶端提供給外掛程式的一般資訊。這個 的資訊包括使用者的所在地區、主機應用程式和平台等詳細資料。
除了首頁和內容觸發條件外,外掛程式也會建構並傳遞
針對動作回呼函式執行事件物件
並在使用者與小工具互動時觸發。外掛程式的回呼函式可以查詢
共用事件物件,藉此判斷使用者開啟的小工具內容
用戶端。舉例來說,外掛程式可找出使用者輸入
TextInput
小工具 (位於
eventObject.commentEventObject.formInputs
物件。
常見事件物件欄位 | |
---|---|
commonEventObject.platform |
string 表示事件來源 (「WEB」, `IOS` 或 `ANDROID`)。 |
commonEventObject.formInputs |
object 包含目前 小工具。對應鍵是字串 ID 。 地圖值物件的結構為 視小工具類型而定:
|
commonEventObject.hostApp |
string 表示已啟用外掛程式的代管應用程式 產生事件物件時。可能的值包括 包括:
|
commonEventObject.parameters |
object 任何其他參數 提供給
Action 使用
Action.setParameters() 。
|
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
欄位中接收目前的小工具值。
這包括使用者在日期或時間挑選器中選取的日期或時間值。
不過,資訊結構取決於
小工具已設為日期時間挑選器、僅限日期的挑選器或時間
。結構差異如下表所示:
日曆活動物件
「行事曆」事件物件是在整體事件物件中 會擷取使用者的日曆和日曆活動相關資訊。它只 。
下表列出 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 與會者的其他邀請對像人數 表示他們即將推出預設值為零。 |
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 代表會議活動的物件 整合 Google Meet 等解決方案 |
conferenceData.conferenceSolution.iconUri |
string 使用者可看見的圖示代表的 這個會議解決方案。 |
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 電話號碼的區碼。要求者 使用者。價值的依據 公開的 區碼 CLDR 清單。 |
entryPoint.uri |
string 進入點的 URI。最大值 長度為 1300 個字元格式取決於進入點 類型:
|
雲端硬碟事件物件
雲端硬碟事件物件是指整體事件物件中 會擷取使用者的 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 。
|
文件事件物件
Docs 事件物件是整體事件物件的一部分 使用者文件及其內容的相關資訊。它只會出現在 事件物件。
文件事件物件 | |
---|---|
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
在文件 UI 中開啟文件的範圍授權;否則這個
欄位為 false 。
|
docs.matchedUrl.url |
string
只有在符合下列條件時才會顯示:
在 Google 文件中產生預覽的連結網址。如要使用這個欄位,您必須在外掛程式的資訊清單中設定 LinkPreviewTriggers 。詳情請參閱「使用智慧型方塊預覽連結」。
使用者預覽連結 "docs" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |
試算表事件物件
試算表事件物件是整體事件物件的一部分 使用者文件及其內容的相關資訊。它只會出現在 事件物件。
試算表事件物件 | |
---|---|
sheets.id |
string 只有在
https://www.googleapis.com/auth/drive.file 範圍符合下列條件時才會顯示
使用者授權。在試算表 UI 中開啟的試算表 ID。
|
sheets.title |
string 只有在
https://www.googleapis.com/auth/drive.file 範圍符合下列條件時才會顯示
使用者授權。在試算表中開啟的試算表標題
第一種是使用無代碼解決方案 AutoML
透過使用者介面建立機器學習模型
|
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" } } |
投影片事件物件
Slides 事件物件是整體事件物件包含的部分 使用者文件及其內容的相關資訊。它只會出現在 事件物件。
投影片事件物件 | |
---|---|
slides.id |
string 只有在
https://www.googleapis.com/auth/drive.file 範圍符合下列條件時才會顯示
使用者授權。在 Google 簡報中開啟的簡報 ID
第一種是使用無代碼解決方案 AutoML
透過使用者介面建立機器學習模型
|
slides.title |
string 只有在
https://www.googleapis.com/auth/drive.file 範圍符合下列條件時才會顯示
使用者授權。簡報標題會在「
簡報 UI。
|
slides.addonHasFileScopePermission |
boolean 如果「 true 」有要求外掛程式
並收到 https://www.googleapis.com/auth/drive.file
在簡報 UI 中開啟的簡報範圍授權;否則
這個欄位是 false 。
|
slides.matchedUrl.url |
string
只有在符合下列條件時才會顯示:
在 Google 簡報中產生預覽的連結網址。如要使用這個欄位,您必須在外掛程式的資訊清單中設定 LinkPreviewTriggers 。
詳情請參閱「使用智慧型方塊預覽連結」。
使用者預覽連結 "slides" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } } |