編輯器外掛程式的授權範圍

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

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

您可以使用網址字串，在資訊清單中宣告範圍。在授權流程中，Apps Script 會向使用者顯示範圍的易讀說明。舉例來說，外掛程式可能會使用「讀取目前的文件」範圍，這會在資訊清單中寫為 https://www.googleapis.com/auth/documents.currentonly。在授權流程中，具有這個範圍的外掛程式會要求使用者允許外掛程式執行下列操作：查看及管理已安裝這個應用程式的文件。

查看範圍

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

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

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

設定明確範圍

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

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

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

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

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

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/spreadsheets"
  ],
  ...
}

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

OAuth 驗證

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

受限制的範圍

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

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

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

編輯器外掛程式範圍

建立編輯器外掛程式時，所需範圍取決於外掛程式程式碼使用的 Apps Script 服務和方法。舉例來說，試算表外掛程式可能需要 https://www.googleapis.com/auth/spreadsheets.readonly 範圍，才能讀取不同 Google 試算表的資訊。

當您將程式碼新增至指令碼專案時，Apps Script 會自動判斷您使用的服務所需範圍。對於編輯器外掛程式，您通常可以只依賴這項自動範圍收集功能，而不必自行判斷範圍並明確設定。

如果您未明確設定範圍，且 Editor 外掛程式只會讀取或寫入開啟的編輯器檔案，請在其中一個指令碼專案檔案中新增下列註解：

  /**
   * @OnlyCurrentDoc
   */

這則註解會告知 Apps Script 將編輯器檔案範圍縮小為 currentonly。舉例來說，如果您在 Google 試算表外掛程式指令碼專案檔案中新增這則註解，即表示外掛程式只需要在目前開啟的試算表中運作的權限，不需要存取使用者在 Google 雲端硬碟中的任何其他試算表。反之，如果 Google 試算表外掛程式需要讀取或寫入使用者目前未開啟的試算表資料，則不應使用這項註解。