狙擊鏡

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

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

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

注意： Apps Script 為各種服務使用的範圍與相關 API 使用的範圍重疊。舉例來說，Apps Script 的日曆服務使用許多與 Calendar API 相同的範圍。您可以在 Apps Script 參考文件中查詢特定 Apps Script 服務方法所需的範圍。

查看範圍

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

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

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

設定明確的範圍

Apps Script 會掃描指令碼，找出需要函式呼叫的範圍，自動判斷指令碼需要哪些範圍。對於大多數指令碼而言，這就足夠了，而且還能節省您的時間，但對於已發布的外掛程式，您應更直接地控管範圍。

舉例來說，Apps Script 可能會預設為外掛程式指令碼專案提供非常寬鬆的範圍 https://mail.google.com。當使用者授權給具備此範圍的腳本專案時，該專案就會獲得使用者 Gmail 帳戶的完整存取權。對於已發布的外掛程式，您必須將這個範圍替換為更受限的集合，且僅涵蓋外掛程式的需求。

警告： 請務必使用最不寬鬆的範圍集。為保護使用者資訊，外掛程式和其他已發布的應用程式「絕對不」要求超出必要範圍的權限。在發布外掛程式審查程序期間，系統會檢查外掛程式所需的範圍；如果外掛程式使用的範圍過於廣泛，就無法通過審查。

您可以編輯指令碼專案的manifest檔案，明確設定指令碼專案使用的範圍。資訊清單欄位 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 或編輯器外掛程式，則該外掛程式必須遵守所有指定的限制，才能發布。

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

注意： 盡量避免在外掛程式中使用受限制的範圍，因為這樣更容易通過外掛程式審查，以便公開發布。您可以自由使用受限制的範圍，用於非公開的擴充功能。

選擇 Google Workspace 外掛程式的權限

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

編輯器範圍

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

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

範圍
目前的文件檔案存取權	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 如果外掛程式要使用 onFileScopeGrantedTrigger，以及如果外掛程式要存取 Google 文件、試算表、簡報或雲端硬碟 API，就必須使用此權限。 使用 Apps Script 的「進階雲端硬碟服務」，授予應用程式建立或開啟的檔案的個別檔案存取權。不過，這項功能不允許使用基本 雲端硬碟服務執行類似的動作。系統會針對個別檔案授予檔案授權，並在使用者取消授權應用程式時撤銷。

Gmail

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

以下是 Google Workspace 外掛程式 (可擴充 Gmail) 常用的範圍；如果您的外掛程式可擴充 Gmail，則必須將標示為「Required」的範圍加入 Google Workspace 外掛程式資訊清單。

請務必將外掛程式中的廣泛 https://mail.google.com 範圍，替換為較狹窄的範圍組合，以便允許外掛程式需要的互動，但不超過這個範圍。

範圍
建立新草稿	https://www.googleapis.com/auth/gmail.addons.current.action.compose 如果外掛程式使用 Compose 動作觸發事件，則為必要屬性。允許外掛程式暫時建立新的草稿訊息和回覆。詳情請參閱「 撰寫草稿訊息」一文；這個範圍也經常用於 Compose 動作。需要存取權杖。
讀取已開啟訊息的中繼資料	https://www.googleapis.com/auth/gmail.addons.current.message.metadata 授予開啟郵件中繼資料 (例如主旨或收件者) 的暫時存取權。不允許讀取訊息內容，且需要存取權杖。 如果外掛程式會在組合動作觸發事件中使用中繼資料，就必須使用這個屬性。對於 Compose 動作，如果 Compose 觸發條件需要存取中繼資料，就必須使用這個範圍。實際上，這個範圍可讓撰寫觸發事件存取回覆電子郵件草稿的收件者清單 (to:、cc: 和 bcc:)。
讀取已開啟的訊息內容	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 Workspace 外掛程式 (可擴充 Google 日曆) 常用的權限範圍。

範圍
存取事件中繼資料	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 範圍

開發人員預覽版：Google Workspace 開發人員預覽版體驗計畫提供的功能，可搶先體驗特定功能。

如要呼叫 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 使用應用程式驗證和管理員核准 (可在開發人員預覽版中使用)： chat.app.spaces.create chat.app.spaces
建立聊天室並新增成員		—	使用使用者驗證： chat.spaces.create chat.spaces
在聊天室中加入使用者			使用使用者驗證： chat.memberships chat.memberships.app chat.import 使用應用程式驗證和管理員核准 (可在開發人員預覽版中使用)： 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 Workspace 外掛程式常用的範圍，可用於擴充 Google 雲端硬碟。

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

存取權杖

為保護使用者資料，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 要求。如果專案使用 Apps Script 的 OAuth2 程式庫，也必須使用這個選項。
讀取使用者的語言代碼和時區	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 應用程式中插入資源的連結。詳情請參閱「 透過 @ 選單建立第三方資源」。