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

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

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

您可以使用網址字串,在manifest中宣告範圍。在授權流程中,Apps Script 會向使用者顯示範圍的易讀說明。舉例來說,外掛程式可能會使用「Read current document」範圍,在資訊清單中以 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 欄位會指定字串陣列。如要設定專案使用的範圍,請將這個陣列的內容替換為您要使用的範圍。舉例來說,如果是擴充 Google 試算表的編輯器外掛程式,您可能會遇到以下情況:

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

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

OAuth 驗證

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

受限制範圍

部分範圍為受限制,並須遵守額外規則,以利保護使用者資料。如果您要發布使用一或多個受限制範圍的 Gmail 或編輯器外掛程式,該外掛程式必須遵守所有指定限制,才能發布。

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

編輯器外掛程式範圍

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

當您在指令碼專案中新增程式碼時,Apps Script 會自動判斷所用服務所需的範圍。對於編輯器外掛程式,您通常可以只依賴這個自動範圍集合,而不需要自行判斷範圍並明確設定。

如果您未明確設定範圍,且編輯器外掛程式只會讀取或寫入已開啟的編輯器檔案,請在其中一個指令碼專案檔案中加入以下註解:

  /**
   * @OnlyCurrentDoc
   */

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