範圍

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

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

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

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

查看範圍

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

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 或 Google 編輯器外掛程式，該外掛程式必須遵守所有指定限制，才能發布。

嘗試發布前，請先參閱受限範圍的完整清單。如果外掛程式使用任何這類範圍，您必須在發布前遵守特定 API 範圍的附加規定。

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

選擇 Google Workspace 外掛程式的範圍

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

編輯者範圍

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

Gmail

Google Workspace 外掛程式專用的範圍可協助保護使用者 Gmail 資料。請在外掛程式資訊清單中明確新增這些範圍，以及任何其他必要範圍。

下表列出 Google Workspace 外掛程式常用的範圍，這些外掛程式會擴充 Gmail 功能。如果外掛程式會擴充 Gmail 功能，您必須將標示為「必要」的任何範圍新增至 Google Workspace 外掛程式資訊清單。

將範圍廣泛的 https://mail.google.com 範圍，替換為一組範圍較窄的範圍，允許外掛程式所需的互動。

Google 日曆範圍

下表列出 Google Workspace 外掛程式常用的範圍，這些外掛程式會擴充 Google 日曆功能。

Google Chat 範圍

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

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

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

Google 雲端硬碟範圍

下表列出 Google Workspace 外掛程式常用的範圍，這些外掛程式會擴充 Google 雲端硬碟。

存取權杖

為保護使用者資料，Google Workspace 外掛程式使用的 Gmail 範圍會授予使用者資料的暫時存取權。如要啟用臨時存取權，請使用動作事件物件的存取權杖呼叫 GmailApp.setCurrentMessageAccessToken。

啟用 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 外掛程式常用的範圍：