編輯器外掛程式授權

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

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

• 使用者建立檔案時，即使尚未授權，所有安裝的擴充功能都會列在「Extensions」選單中。

• 這些外掛程式適用於可與協作者共用的 Google 雲端硬碟檔案。未安裝編輯器外掛程式的協作者，會在檔案建立者使用該外掛程式的文件中看到該外掛程式。

• 編輯器外掛程式會在文件開啟時自動執行 onOpen() 函式。

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

授權模式

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

編輯器外掛程式狀態

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

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

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

授權模式

使用者開啟文件、表單、簡報或試算表時，編輯器外掛程式的 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 中執行，如下表所述。

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

當外掛程式安裝給目前使用者，或在目前檔案中啟用時，開啟該檔案時，系統會載入文件、表單、簡報或試算表的外掛程式。外掛程式會列於「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 發生權限錯誤的服務呼叫，請嘗試下列操作：

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

5. 儲存程式碼並建立測試部署作業。

   建立測試部署時，請確認「設定」欄位為「已為目前使用者安裝」，且「設定」方塊下方的文字為「在 AuthMode.None 中測試」。

6. 啟動測試部署作業，並開啟「Extensions」選單。

7. 如果所有選單項目都顯示出來，表示問題已修正。如果您只看到「Help」選單，請返回步驟 1。 你可能錯過了服務電話。

相關主題

• 網頁應用程式
• 外掛程式類型
• 測試編輯器外掛程式