狙擊鏡

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

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

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

查看範圍

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

1. 開啟指令碼專案。
2. 按一下左側的「總覽」圖示 info_outline。
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 或編輯器外掛程式，該外掛程式必須遵守所有指定限制，才能發布。

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

選擇 Google Workspace 外掛程式的權限

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

編輯器範圍

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

Gmail

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

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

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

Google 日曆權限

以下是 Google Workspace 外掛程式 (可擴充 Google 日曆) 常用的權限範圍。

Google Chat 範圍

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

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

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

Google 雲端硬碟範圍

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

存取權杖

為保護使用者資料，Google Workspace 外掛程式中使用的 Gmail 範圍只會授予使用者資料的臨時存取權。如要啟用臨時存取權，您必須使用存取權權杖做為引數，呼叫 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 Workspace 或 Apps Script 服務，可能需要額外的範圍。在大多數情況下，您可以讓 Apps Script 自動偵測這些範圍，並更新資訊清單。編輯資訊清單的範圍時，請勿移除任何範圍，除非您要用更合適的替代方案 (例如較狹隘的範圍) 取代。

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