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

使用者必須授權外掛程式和其他應用程式存取其資料或代表使用者執行操作。使用者首次執行外掛程式時，外掛程式 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 帳戶的完整存取權。以已發布的外掛程式來說，您必須將這個範圍替換為更多限制，涵蓋外掛程式的需求且不再適用。

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

  1. 查看外掛程式目前使用的範圍。確定需要做出哪些變更，例如使用範圍較小的範圍。
  2. 開啟外掛程式的資訊清單檔案。
  3. 找出標有 oauthScopes 的頂層欄位。如果沒有，可以新增。

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

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

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

OAuth 驗證

使用某些機密 OAuth 範圍時，您的外掛程式可能需要完成 OAuth 用戶端驗證才能發布。詳情請參閱下列指南：

受限制的範圍

某些範圍會受限制，並適用其他有助於保護使用者資料的規則。如果您計劃發布使用一或多個受限制範圍的 Gmail 或編輯器外掛程式，外掛程式必須符合所有指定限制才能發布。

嘗試發布前，請先詳閱受限制範圍的完整清單。如果您的外掛程式使用其中任何一種方式，在發布之前，您就必須遵守特定 API 範圍的額外規定。

編輯器外掛程式範圍

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

在您將程式碼新增至指令碼專案時，Apps Script 會自動判斷使用的服務所需的範圍。針對編輯器外掛程式，通常可以直接依賴這個自動範圍集合，不必自行判斷並明確設定範圍。

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

  /**
   * @OnlyCurrentDoc
   */

這個註解會告知 Apps Script 將編輯器檔案的範圍縮小至 currentonly。舉例來說，如果您將這則註解新增至 Google 試算表外掛程式指令碼專案檔案，您確定外掛程式只需要執行目前開啟的試算表的權限，而非使用者可能在 Google 雲端硬碟內的任何其他試算表。相反地，如果 Google 試算表外掛程式需要在使用者尚未開啟的試算表中讀取或寫入資料，您就不需要使用這則註解。