狙擊鏡

使用者必須授權存取資料或代為執行的外掛程式和其他應用程式。使用者首次執行外掛程式時，外掛程式 UI 會顯示授權提示，以啟動授權流程。

在這個流程中，提示會告知使用者應用程式想取得哪些權限。舉例來說，外掛程式可能想取得讀取使用者電子郵件或在日曆中建立活動的權限。外掛程式的指令碼專案會將這些個別權限定義為 OAuth 範圍。

您可以使用網址字串，在資訊清單中宣告範圍。在授權流程中，Apps Script 會向使用者顯示範圍的易讀說明。舉例來說，Google Workspace 外掛程式可能會使用「讀取目前郵件」範圍，這會在資訊清單中寫成 https://www.googleapis.com/auth/gmail.addons.current.message.readonly。在授權流程中，具有這項範圍的外掛程式會要求使用者允許外掛程式「在外掛程式執行期間查看你的電子郵件」。

注意： Apps Script 各項服務使用的範圍與相關 API 使用的範圍重疊。舉例來說，Apps Script 的 Calendar 服務與 Calendar API 使用許多相同的範圍。如要查詢特定 Apps Script 服務方法所需的範圍，請參閱 Apps Script 參考文件。

查看範圍

如要查看指令碼專案目前需要的範圍，請按照下列步驟操作：

1. 開啟指令碼專案。
2. 按一下左側的「總覽」 。
3. 查看「專案 OAuth 範圍」下方的範圍。

您也可以在專案資訊清單的 oauthScopes 欄位中查看指令碼專案的目前範圍，但前提是您已明確設定這些範圍。

設定明確範圍

Apps Script 會掃描指令碼的程式碼，找出需要範圍的函式呼叫，自動判斷指令碼需要哪些範圍。對大多數指令碼來說，這樣就已足夠，還能節省時間，但如果是已發布的增益集，您應該更直接地控管範圍。

舉例來說，Apps Script 預設可能會為外掛程式指令碼專案提供非常寬鬆的 https://mail.google.com 範圍。如果使用者授權指令碼專案使用這個範圍，專案就會取得使用者 Gmail 帳戶的完整存取權。如果是已發布的外掛程式，您必須將這個範圍替換為更有限的集合，涵蓋外掛程式的需求即可。

警告： 請務必使用權限最少的範圍集。為保護使用者資訊，外掛程式和其他已發布的應用程式絕不應要求超出絕對必要的範圍權限。發布外掛程式時，系統會進行外掛程式審查，檢查外掛程式要求的範圍。如果外掛程式使用的範圍過於廣泛，就無法通過審查。

您可以編輯指令碼專案的資訊清單檔案，明確設定專案使用的範圍。資訊清單欄位 oauthScopes 是外掛程式使用的所有範圍陣列。如要設定專案的範圍，請按照下列步驟操作：

1. 查看外掛程式目前使用的範圍。判斷需要進行哪些變更，例如縮小範圍。
2. 開啟外掛程式的資訊清單檔案。
3. 找到標示為 oauthScopes 的頂層欄位。如果沒有，可以自行新增。

4. oauthScopes 欄位會指定字串陣列。如要設定專案使用的範圍，請將這個陣列的內容替換為您要使用的範圍。舉例來說，如果是擴充 Gmail 的 Google Workspace 外掛程式，您可能會看到以下內容：

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

5. 儲存資訊清單檔案變更。

OAuth 驗證

使用特定敏感 OAuth 範圍時，外掛程式可能需要先通過 OAuth 用戶端驗證，才能發布。詳情請參閱下列指南：

• Apps Script 的 OAuth 用戶端驗證
• 未經驗證的應用程式
• OAuth 驗證常見問題
• Google API 服務：使用者資料政策

受限制的範圍

部分範圍受限制，且須遵守額外規則，以利保護使用者資料。如果您打算發布使用一或多個受限範圍的 Gmail 或 Google 文件外掛程式，外掛程式必須先遵守所有指定限制，才能發布。

嘗試發布前，請先查看受限制範圍的完整清單。如果外掛程式使用任何一項，您必須在發布前遵守特定 API 範圍的額外規定。

注意： 如果可以，請避免在外掛程式中使用受限範圍，這樣外掛程式較容易通過審查，並公開發布。您可以在非公開外掛程式中自由使用受限範圍。

Visual Studio Code 適用的 Google Workspace 開發人員工具擴充功能會提供所有範圍的診斷資訊，包括範圍說明，以及範圍是否屬於機密或受限。

選擇 Google Workspace 外掛程式的範圍

以下各節提供 Google Workspace 外掛程式常用的範圍。

編輯者範圍

以下是 Google Workspace 外掛程式的常用範圍，可擴充 Google 文件、試算表和簡報的功能。

注意：currentonly 範圍僅適用於 Apps Script 服務。這不包括 Apps Script 進階服務或對 Google Workspace API 的直接呼叫。

範圍
目前的文件存取權	https://www.googleapis.com/auth/documents.currentonly 如果外掛程式會存取 Apps Script 文件 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 外掛程式必須使用 onFileScopeGrantedTrigger，才能存取 Google 文件、試算表、簡報或雲端硬碟 API。使用 Apps Script 進階雲端硬碟服務，授予應用程式建立或開啟的檔案存取權。不過，這不允許使用基本 Drive 服務執行類似動作。檔案授權是依檔案授予，且會在使用者取消授權應用程式時撤銷。

Gmail

我們專為 Google Workspace 外掛程式建立了一些範圍，以協助保護使用者 Gmail 資料。您必須明確將這些範圍加入外掛程式資訊清單，以及外掛程式程式碼所需的任何其他範圍。

以下是擴充 Gmail 的 Google Workspace 外掛程式常用範圍；標示為「必要」的範圍必須加入 Google Workspace 外掛程式資訊清單，外掛程式才能擴充 Gmail。

請務必在外掛程式中，將非常廣泛的 https://mail.google.com 範圍，替換為一組較窄的範圍，允許外掛程式進行所需的互動，但不得超出範圍。

範圍
建立新草稿	https://www.googleapis.com/auth/gmail.addons.current.action.compose 如果外掛程式使用 撰寫動作觸發條件，則必須提供這項資訊。 允許外掛程式暫時建立新的草稿郵件和回覆。詳情請參閱「 撰寫草稿訊息」一文；這個範圍也常與 撰寫動作搭配使用。需要存取權杖。
讀取開啟的訊息中繼資料	https://www.googleapis.com/auth/gmail.addons.current.message.metadata 授予開啟郵件中繼資料的暫時存取權 (例如主旨或收件者)。不允許讀取郵件內容，且需要存取權杖。 如果外掛程式在撰寫動作觸發程序中使用中繼資料，則必須提供這項資訊。 如果是 撰寫動作，如果撰寫觸發程序需要存取中繼資料，則必須使用這個範圍。實際上，這個範圍可讓撰寫觸發程序存取回覆電子郵件草稿的收件者清單 (收件者、副本和密件副本)。
讀取開啟的郵件內容	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 讀取任何電子郵件中繼資料和內容，包括開啟的郵件。 如要讀取其他郵件的相關資訊，例如執行搜尋查詢或讀取整個郵件串，則必須使用這項權限。 警告：這是非常廣泛的受限範圍。請只在絕對必要時才使用這項功能。

Google 日曆範圍

以下是擴充 Google 日曆的 Google Workspace 外掛程式常用範圍。

範圍
存取事件中繼資料	https://www.googleapis.com/auth/calendar.addons.execute 如果外掛程式會存取日曆活動中繼資料，則必須提供這項權限。允許外掛程式存取活動中繼資料。
讀取使用者產生的事件資料	https://www.googleapis.com/auth/calendar.addons.current.event.read 如果外掛程式需要讀取使用者產生的事件資料，則為必要項目。 允許外掛程式存取使用者產生的事件資料。只有在將 addOns.calendar.eventAccess 資訊清單欄位 設為 READ 或 READ_WRITE 時，才能取得這項資料。
寫入使用者產生的事件資料	https://www.googleapis.com/auth/calendar.addons.current.event.write 如果外掛程式需要寫入使用者產生的事件資料，則為必填。 允許外掛程式編輯使用者產生的事件資料。只有在將 addOns.calendar.eventAccess 資訊清單欄位 設為 WRITE 或 READ_WRITE 時，才能取得這項資料。

Google Chat 範圍

如要呼叫 Chat API，您必須以 Google Chat 使用者或 Chat 擴充應用程式的身分進行驗證。每種驗證類型都需要不同的範圍，而且並非所有 Chat API 方法都支援應用程式驗證。

如要進一步瞭解 Chat 範圍和驗證類型，請參閱 Chat API 的「驗證和授權總覽」

下表列出根據支援的驗證類型，經常使用的 Chat API 方法和範圍：

方法	支援使用者驗證	支援應用程式驗證	支援的授權範圍
傳送訊息			使用使用者驗證： chat.messages.create chat.messages chat.import 使用應用程式驗證： chat.bot
建立聊天室			使用使用者驗證： chat.spaces.create chat.spaces chat.import 透過應用程式驗證和管理員核准 (適用於 Developer Preview)： chat.app.spaces.create chat.app.spaces
建立聊天室並新增成員		—	使用使用者驗證： chat.spaces.create chat.spaces
在聊天室中新增使用者			使用使用者驗證： chat.memberships chat.memberships.app chat.import 透過應用程式驗證和管理員核准 (適用於 Developer Preview)： chat.app.memberships
列出 Chat 聊天室的活動或事件		—	使用「使用者驗證」時，您必須為要求中包含的每個 事件類型使用範圍： 訊息相關事件： chat.messages chat.messages.readonly 表情符號回應相關事件： chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly 會員相關活動： chat.memberships chat.memberships.readonly 與空間相關的活動： chat.spaces chat.spaces.readonly

Google 雲端硬碟範圍

以下是擴充 Google 雲端硬碟的 Google Workspace 外掛程式常用範圍。

範圍
讀取所選項目中繼資料	https://www.googleapis.com/auth/drive.addons.metadata.readonly 如果外掛程式實作了關聯介面，且會在使用者選取雲端硬碟中的項目時觸發，則必須提供這項資訊。 允許外掛程式讀取使用者在 Google 雲端硬碟中選取項目的有限中繼資料。中繼資料僅限於項目的 ID、標題、MIME 類型、圖示網址，以及外掛程式是否有權存取項目。
個別檔案存取權	https://www.googleapis.com/auth/drive.file 如果外掛程式需要存取個別雲端硬碟檔案，建議使用這個方法。 使用 Apps Script 進階雲端硬碟服務，授予應用程式建立或開啟的檔案存取權。不過，這不允許使用基本 Drive 服務執行類似動作。檔案授權是依檔案授予，且會在使用者取消授權應用程式時撤銷。 請參閱「 為所選檔案要求檔案存取權」範例。

存取權杖

為保護使用者資料，Google Workspace 外掛程式使用的 Gmail 範圍只會授予使用者資料的暫時存取權。如要啟用臨時存取權，您必須使用存取權權杖做為引數，呼叫 GmailApp.setCurrentMessageAccessToken(accessToken) 函式。您必須從動作事件物件取得存取權杖。

注意： 啟用 Gmail 範圍的存取權權杖「不」等同於 ScriptApp.getOAuthToken() 傳回的存取權權杖。您必須使用動作事件物件中提供的權杖。

以下範例說明如何設定存取權杖，允許存取訊息的中繼資料。這個範例只需要 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 Workspace 或 Apps Script 服務，可能需要其他範圍。在大多數情況下，您可以讓 Apps Script 偵測這些範圍，並自動更新資訊清單。編輯資訊清單的範圍清單時，請勿移除任何範圍，除非您要以更合適的替代方案 (例如較窄的範圍) 取代。

下表列出 Google Workspace 外掛程式常用的範圍：

範圍
讀取使用者的電子郵件地址	https://www.googleapis.com/auth/userinfo.email 允許專案讀取目前使用者的電子郵件地址。
允許呼叫外部服務	https://www.googleapis.com/auth/script.external_request 允許專案發出 UrlFetch 要求。如果專案使用 OAuth2 for Apps Script 程式庫，也必須完成這項操作。
讀取使用者的語言代碼和時區	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 應用程式中插入資源連結。詳情請參閱「 透過 @ 選單建立第三方資源」。