使用者必須授權外掛程式,以及存取其資料的其他應用程式 或代表他們行事當使用者首次執行外掛程式時, 外掛程式 UI 顯示開始授權流程的授權提示。
在這個流程中,提示訊息會告訴使用者應用程式需要執行什麼動作 所需的權限舉例來說,外掛程式可能需要讀取 使用者的電子郵件訊息,或在日曆中建立活動。外掛程式指令碼 專案會將這些個別權限定義為 OAuth 範圍。
在資訊清單中宣告範圍
使用網址字串在授權流程中,Apps Script 會顯示
以清楚易懂的方式說明使用者範圍舉例來說,您的 Google Workspace 外掛程式
使用「朗讀目前訊息」也就是在資訊清單中寫入
https://www.googleapis.com/auth/gmail.addons.current.message.readonly
。過程中
在授權流程中,擁有此範圍的外掛程式會要求使用者允許
外掛程式:在外掛程式執行期間查看電子郵件。
查看範圍
如要查看指令碼專案目前所需的範圍,請執行 包括:
- 開啟指令碼專案。
- 按一下左側的「總覽」。 。
- 查看「專案 OAuth 範圍」下方的範圍。
此外,您也可以在專案資訊清單中,查看指令碼專案目前的範圍。
oauthScopes
下
」欄位中,但前提是您已明確設定這些範圍。
設定明確範圍
Apps Script 會自動掃描指令碼,決定指令碼需要的範圍 。對大部分的指令碼來說,這是 可節省您的時間,但對於已發布的外掛程式而言, 以便更直接地控管範圍
舉例來說,Apps Script 可能會為外掛程式指令碼專案
範圍預設為 https://mail.google.com
使用者授權指令碼時
並授予該專案使用者 Gmail 的完整存取權
讓他們使用服務帳戶如果是已發布的外掛程式,您「必須」將這個範圍替換為
其中包含外掛程式需求的有限組合。
如要明確設定指令碼專案使用的範圍,請編輯
該檔案的資訊清單檔案。資訊清單欄位
oauthScopes
是陣列
所需的全部範圍值。如要設定專案的範圍,請執行下列步驟:
包括:
- 查看外掛程式目前使用的範圍。決定內容 就需要進行調整 例如縮小範圍
- 開啟外掛程式的資訊清單檔案。
- 找出標示為
oauthScopes
的頂層欄位。如果沒有 即可新增。 oauthScopes
欄位會指定字串陣列。如何設定範圍 請將這個陣列的內容替換成 以及要使用哪些項目 舉例來說,如要擴充 Gmail 的 Google Workspace 外掛程式,您可能會採取下列做法:{ ... "oauthScopes": [ "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email" ], ... }
儲存資訊清單檔案變更。
OAuth 驗證
使用特定機密 OAuth 範圍時,可能需要執行外掛程式 OAuth 用戶端驗證 才能發布詳情請參閱下列指南:
受限制的範圍
特定範圍受到限制,並且必須遵守額外的規則 如何保護使用者資料如果日後想要發布 Gmail 或編輯器外掛程式,該外掛程式會使用 一或多個受限制的範圍,外掛程式必須符合所有指定 才能發布圖片
查看受限制範圍的完整清單 再嘗試發布如果外掛程式使用了任何項目,您就必須遵守 使用 特定 API 範圍的其他規定 先進行修正
日曆範圍
以下是擴充 Google 日曆的 Google Workspace 外掛程式常用的範圍。
範圍 | |
---|---|
存取事件中繼資料 |
https://www.googleapis.com/auth/calendar.addons.execute
如果外掛程式會存取日曆活動中繼資料,則為必要屬性。允許 這個外掛程式即可存取事件中繼資料。 |
讀取使用者產生的事件資料 |
https://www.googleapis.com/auth/calendar.addons.current.event.read
如果外掛程式需要讀取使用者產生的事件資料,則為必要屬性。
允許外掛程式存取使用者產生的事件資料。這項資料是
僅適用於
|
寫入使用者產生的事件資料 |
https://www.googleapis.com/auth/calendar.addons.current.event.write
如果外掛程式需要寫入使用者產生的事件資料,則為必要屬性。
允許外掛程式編輯使用者產生的事件資料。這項資料是
僅適用於
|
雲端硬碟範圍
以下是擴充 Google 雲端硬碟的 Google Workspace 外掛程式常用的範圍。
範圍 | |
---|---|
讀取所選項目的中繼資料 |
https://www.googleapis.com/auth/drive.addons.metadata.readonly
如果外掛程式實作的內容相關介面觸發,則為必要屬性 使用者在雲端硬碟中選取項目時。 允許外掛程式讀取使用者所具備項目的有限中繼資料 已在 Google 雲端硬碟中選取中繼資料僅限於項目 ID 標題、MIME 類型、圖示網址,以及外掛程式是否擁有 存取該項目。 |
個別檔案存取權 |
https://www.googleapis.com/auth/drive.file
如果外掛程式需要存取個別雲端硬碟,建議採用這個做法
檔案。
使用
Apps Script 進階雲端硬碟
服務。但如果是要使用
基本雲端硬碟服務,
不過,檔案授權是以個別檔案為基礎,
會在使用者取消授權應用程式時撤銷。 |
Gmail 外掛程式範圍
有幾個範圍是專門針對 可協助保護 Gmail 使用者的 Google Workspace 外掛程式 資料。您必須 明確新增這些範圍 以及其他應用程式 需要外掛程式的程式碼
以下是擴充 Gmail 的 Google Workspace 外掛程式常用範圍。 您必須將標示為必要的項目加進 Google Workspace 外掛程式資訊清單 (如果外掛程式擴充為適用) Gmail。
另外,請務必替換您的https://mail.google.com
這個外掛程式,且範圍較小,可讓外掛程式進行互動
變得十分重要
範圍 | |
---|---|
建立新草稿 |
https://www.googleapis.com/auth/gmail.addons.current.action.compose
如果外掛程式有使用,則為必要屬性 Compose 動作觸發條件。 允許外掛程式暫時建立新的草稿訊息及 以及回覆內容詳情請參閱 撰寫郵件草稿 瞭解詳情;這個範圍通常會用於 撰寫動作。 需要存取權杖。 |
讀取開放式訊息中繼資料 |
https://www.googleapis.com/auth/gmail.addons.current.message.metadata
可暫時存取開放郵件中繼資料 (例如
主旨或收件者)。禁止朗讀郵件內容
因此需要存取權杖 如果外掛程式在 Compose 動作中使用中繼資料,則為必要屬性 觸發條件。 適用於 組合動作,如果撰寫觸發條件,則需要使用這個範圍 需要中繼資料的存取權在實務上,這個範圍 觸發回覆的存取權收件者清單 (收件者、副本:和密件副本) 電子郵件草稿。 |
閱讀開啟的郵件內容 |
https://www.googleapis.com/auth/gmail.addons.current.message.action
可在使用者互動時授予開啟郵件內容的存取權, 例如選取外掛程式選單項目時需要存取權 產生下一個符記 |
閱讀開啟的討論串內容 |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly
可暫時存取開放訊息的中繼資料和內容, 同時授予其他郵件內容的存取權。 。需要存取權杖。 |
讀取所有訊息內容和中繼資料 |
https://www.googleapis.com/auth/gmail.readonly
讀取任何電子郵件中繼資料和內容,包括開啟的郵件。 如果您需要讀取其他郵件的相關資訊,例如 系統在執行搜尋查詢或閱讀整個郵件串時觸發。 |
存取權杖
為保護使用者資料,以下 Gmail 範圍中使用的 Gmail 範圍
僅限 Google Workspace 外掛程式授權
暫時存取使用者資料。如要啟用暫時存取權,您必須呼叫
函式 GmailApp.setCurrentMessageAccessToken(accessToken)
將存取權杖做為引數您必須先向
動作事件物件。
以下範例說明如何設定存取權杖並允許存取
訊息的中繼資料本例中,唯一需要的範圍是
https://www.googleapis.com/auth/gmail.addons.current.message.metadata
。
function readSender(e) {
var accessToken = e.gmail.accessToken;
var messageId = e.gmail.messageId;
// The following function enables short-lived access to the current
// message in Gmail. Access to other Gmail messages or data isn't
// permitted.
GmailApp.setCurrentMessageAccessToken(accessToken);
var mailMessage = GmailApp.getMessageById(messageId);
return mailMessage.getFrom();
}
編輯者範圍
以下是 Google Workspace 外掛程式的常用範圍,適用於 Google 文件、試算表、 和簡報
範圍 | |
---|---|
目前的文件檔案存取權 |
https://www.googleapis.com/auth/documents.currentonly
如果外掛程式存取 Apps Script Docs API,則為必要元素。 授予暫時存取開啟文件內容的權限。 |
目前的試算表檔案存取權 |
https://www.googleapis.com/auth/spreadsheets.currentonly
如果外掛程式存取 Apps Script Sheets API,則為必要屬性。 授予暫時存取試算表內容的權限。 |
目前的簡報檔案存取權 |
https://www.googleapis.com/auth/presentations.currentonly
如果外掛程式存取 Apps Script Slides API,則為必要屬性。 授予目前簡報內容的暫時存取權。 |
個別檔案存取權 |
https://www.googleapis.com/auth/drive.file
必須安裝此外掛程式才能使用 |
其他範圍
如果您的外掛程式使用其他 Apps Script 服務,可能會需要額外的範圍。 在大部分的情況下,您可以允許 Apps Script 偵測這些範圍並更新 資訊清單。編輯資訊清單的範圍清單時,請勿移除 任何範圍,除非您使用更合適的替代選項來取代。 例如縮小範圍
以下是一些 Apps Script 範圍常用的清單,供你參考 搭配 Google Workspace 外掛程式:
範圍 | |
---|---|
讀取使用者的電子郵件地址 |
https://www.googleapis.com/auth/userinfo.email
允許專案讀取目前使用者的電子郵件地址。 |
允許呼叫外部服務 |
https://www.googleapis.com/auth/script.external_request
允許專案
|
讀取使用者的語言代碼和時區 |
https://www.googleapis.com/auth/script.locale
允許專案學習目前使用者的語言代碼和時區。 詳情請參閱 存取使用者語言代碼和時區以瞭解詳情。 |
建立觸發條件 |
https://www.googleapis.com/auth/script.scriptapp
允許專案建立 觸發條件。 |
預覽第三方連結 |
https://www.googleapis.com/auth/workspace.linkpreview
如果外掛程式預覽來自第三方服務的連結,則為必要屬性。 允許使用者在與專案互動時,在 Google Workspace 應用程式中查看連結。 詳情請參閱 使用智慧型方塊預覽連結。 |
建立第三方資源 |
https://www.googleapis.com/auth/workspace.linkcreate
如果外掛程式在第三方服務中建立資源,則為必要屬性。 允許專案讀取使用者提交的資訊 資源建立表單 在 Google Workspace 應用程式中插入資源連結。 詳情請參閱 使用 @ 選單建立第三方資源。 |