本頁面由 Cloud Translation API 翻譯而成。

編輯器外掛程式授權

許多以 Apps Script 為基礎的應用程式授權程序都很簡單，因為當使用者嘗試使用時，指令碼專案會要求缺少的權限。

編輯器外掛程式的授權模式較為複雜，原因如下：

使用者建立檔案時，即使尚未授權，所有安裝的擴充功能都會列在「Extensions」選單中。
這些外掛程式適用於可與協作者共用的 Google 雲端硬碟檔案。未安裝編輯器外掛程式的協作者，會在檔案建立者使用該外掛程式的文件中看到該外掛程式。
編輯器外掛程式會在文件開啟時自動執行 onOpen() 函式。

為保護使用者資料，系統會套用授權模式，讓 onOpen() 無法使用某些服務。本指南可協助您瞭解程式碼的功能和執行時機。

授權模式

編輯器外掛程式的授權模式取決於其狀態，而狀態則取決於使用者 (安裝外掛程式的使用者或協作者)。

編輯器外掛程式狀態

安裝或啟用「Extensions」選單中的編輯器外掛程式。

當使用者或管理員從 Google Workspace Marketplace 取得外掛程式並授權存取 Google 資料後，系統就會為該使用者安裝外掛程式。
當任何人使用文件、表單、簡報或試算表中的外掛程式時，該外掛程式就會啟用。
當使用者在檔案上進行協作，其中一位使用者使用外掛程式時，系統會為該使用者安裝外掛程式，並為檔案啟用外掛程式。

下表摘要說明「已安裝」和「已啟用」的差異。請注意，以外掛程式測試指令碼時，您可以在這兩種狀態或其中一種狀態下執行測試。

	已安裝	已啟用
套用對象	使用者	文件、表單、簡報或試算表
原因：	從商店取得外掛程式	使用該文件、表單、簡報或試算表時，從商店取得外掛程式，或在該文件、表單、簡報或試算表中使用先前安裝的外掛程式
可見的選單	在使用者開啟或建立的所有文件、表單、簡報或試算表中，僅限該使用者	該文件、表單、簡報或試算表的所有協作者
`onOpen()` 的授權模式	`AuthMode.NONE` (除非也已啟用，否則 `AuthMode.LIMITED)`	`AuthMode.LIMITED`

授權模式

使用者開啟文件、表單、簡報或試算表時，編輯器外掛程式的 onOpen() 函式會自動執行。為保護使用者資料，Apps Script 會限制 onOpen() 函式的功能。編輯器外掛程式狀態會決定 onOpen() 函式執行的授權模式。

如果檔案、表單、簡報或試算表中已啟用編輯器外掛程式，onOpen() 就會在 AuthMode.LIMITED 中執行。如果外掛程式未啟用，且僅已安裝，onOpen() 會在 AuthMode.NONE 中執行。

在 AuthMode.NONE 中，使用者必須透過點選或執行自訂函式與外掛程式互動，外掛程式才能執行特定服務。如果外掛程式嘗試在 onOpen()、onInstall() 或全域範圍內使用這些服務，權限會失敗，其他呼叫 (例如填入選單) 也會停止。系統僅支援「說明」選項。

如要執行受限制的服務呼叫，您必須使用 AuthMode.FULL 授權模式。使用者互動功能 (例如點選選單選項) 只會在這個模式下執行。程式碼在 AuthMode.FULL 模式下執行後，外掛程式就能使用使用者授權的所有範圍。

Apps Script 會將授權模式傳遞為 Apps Script 事件參數 e 的 authMode 屬性；e.authMode 的值會對應至 Apps Script ScriptApp.AuthMode 列舉中的常數。

授權模式適用於所有 Apps Script 執行方法，包括透過指令碼編輯器、選單項目或 Apps Script google.script.run 呼叫執行。不過，只有在指令碼是因觸發事件 (例如 onOpen()、onEdit() 或 onInstall()) 而執行時，才能檢查 e.authMode 屬性。Google 試算表中的自訂函式會使用自己的授權模式 AuthMode.CUSTOM_FUNCTION，這與 LIMITED 類似，但限制略有不同。在所有其他情況下，指令碼會在 AuthMode.FULL 中執行，如下表所述。

	`NONE`	`LIMITED`	`CUSTOM_FUNCTION`	`FULL`
發生時間	`onOpen()` (如果使用者已安裝外掛程式，但未在文件、表單、簡報或試算表中啟用)	`onOpen()` (其他時間) `onEdit()` (僅限 Google 試算表)	自訂函式	其他所有時間，包括：可安裝的觸發事件 `onInstall()` `google.script.run`
存取使用者資料	僅限語言代碼	僅限語言代碼	僅限語言代碼	是
存取文件、表單、簡報或試算表	否	是	是 — 唯讀	是
存取使用者介面	新增選單項目	新增選單項目	否	是
使用 `Properties`	否	是	是	是
有權存取 `Jdbc`、`UrlFetch`	否	否	是	是
其他服務	`Logger` `Utilities`	任何不會存取使用者資料的服務	任何不會存取使用者資料的服務	所有服務

編輯器外掛程式的授權生命週期

當外掛程式安裝給目前使用者，或在目前檔案中啟用時，開啟該檔案時，系統會載入文件、表單、簡報或試算表的外掛程式。外掛程式會列於「Extensions」選單中，並開始監聽簡單觸發條件 onInstall()、onOpen() 和 onEdit()。如果使用者點選「Extensions」選單項目，系統就會執行。

已安裝編輯器外掛程式

從商店安裝編輯器外掛程式後，其 onInstall() 函式會在 AuthMode.FULL 中執行。在這個授權模式中，外掛程式可以執行複雜的設定例行程序。由於文件、表單、簡報或試算表已開啟，且 onOpen() 函式尚未執行，因此您也應使用 onInstall() 建立選單項目。以下範例說明如何從 onInstall() 函式呼叫 onOpen() 函式：

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

編輯器外掛程式已開啟

開啟文件、表單、簡報或試算表時，系統會載入目前使用者已安裝的每個編輯器外掛程式，或任何協作者在檔案中已啟用的外掛程式，並呼叫每個 onOpen() 函式。onOpen() 執行的授權模式取決於加購項目是否已安裝或啟用。

如果外掛程式只建立基本選單，模式就無關緊要。以下範例顯示基本的 onOpen() 函式：

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

如要根據儲存的 Apps Script 屬性新增動態選單項目、讀取目前檔案的內容，或執行其他進階工作，您必須識別授權模式並妥善處理。

以下範例顯示進階 onOpen() 函式，可根據授權模式變更其動作：

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

請注意，在 AuthMode.LIMITED 中執行時，外掛程式無法開啟側欄或對話方塊。您可以使用選單項目開啟側欄和對話方塊，因為這些項目會在 AuthMode.FULL 中執行。

使用者執行編輯器外掛程式

使用者點選「Extensions」選單項目時，Apps Script 會先檢查使用者是否已安裝外掛程式，如果尚未安裝，系統會提示使用者安裝。如果使用者已授權外掛程式，指令碼就會執行 AuthMode.FULL 中對應於選單項目的函式。在文件、表單、簡報或試算表中啟用外掛程式 (如果尚未啟用)。

排解外掛程式選單無法顯示的問題

如果程式碼無法正確管理授權模式，可能就無法顯示外掛程式選單。例如：

外掛程式嘗試執行目前授權模式不支援的 Apps Script 服務。
外掛程式會在使用者與其互動之前，嘗試執行服務呼叫。

如要移除或重新排列導致 AuthMode.NONE 發生權限錯誤的服務呼叫，請嘗試下列操作：

開啟外掛程式的 Apps 指令碼專案，然後找出 onOpen() 函式。
搜尋 onOpen() 函式，找出提及 Apps Script 服務或與之相關聯的物件，例如 PropertiesService、SpreadsheetApp 或 GmailApp。
如果服務用於建立 UI 元素以外的任何內容，請將其移除或包裝在註解區塊中。只保留下列方法：.getUi()、.createMenu()、.addItem() 和 .addToUi()。並找出並移除任何函式以外的服務。
找出可能包含在先前步驟中註解或移除的程式碼行函式，特別是使用這些程式碼行所產生資訊的函式，然後將服務呼叫移至需要這些程式碼行的函式。重新排列或重寫程式碼庫，以便配合先前步驟所做的變更。
儲存程式碼並建立測試部署作業。

建立測試部署時，請確認「設定」欄位為「已為目前使用者安裝」，且「設定」方塊下方的文字為「在 AuthMode.None 中測試」。
啟動測試部署作業，並開啟「Extensions」選單。
如果所有選單項目都顯示出來，表示問題已修正。如果您只看到「Help」選單，請返回步驟 1。你可能錯過了服務電話。

編輯器外掛程式授權

授權模式

編輯器外掛程式狀態

授權模式

編輯器外掛程式的授權生命週期

已安裝編輯器外掛程式

編輯器外掛程式已開啟

使用者執行編輯器外掛程式

排解外掛程式選單無法顯示的問題

相關主題