編輯器外掛程式授權

許多 Google Apps Script 應用程式的授權程序都很簡單。當使用者嘗試使用指令碼專案時，系統會要求提供任何缺少的必要權限。

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

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

• 這些外掛程式適用於 Google 雲端硬碟中的檔案，且可與協作者共用。如果協作者未安裝 Editor 外掛程式，但檔案建立者使用了該外掛程式，協作者仍可在文件中看到。

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

為保護使用者資料，系統會套用授權模式，導致 onOpen 無法使用部分服務。本指南將說明程式碼的功能和使用時機。

授權模型

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

編輯器外掛程式狀態

「擴充功能」選單中的編輯器外掛程式已安裝、啟用或兩者皆是：

• 使用者或管理員從 Google Workspace Marketplace 下載外掛程式，並授權存取 Google 資料後，外掛程式就會安裝給特定使用者。
• 只要有人在文件、表單、簡報或試算表中使用外掛程式，該外掛程式就會啟用。
• 如果使用者協作處理檔案，其中一人使用外掛程式，系統會為該使用者安裝外掛程式，並為該檔案啟用外掛程式。

下表摘要說明已安裝和已啟用之間的差異。以附加元件形式測試指令碼時，您可以在任一或兩種狀態下執行測試。

授權模式

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

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

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

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

只有已發布的 編輯器外掛程式才能位於 AuthMode.NONE； 未發布的 編輯器外掛程式會在 AuthMode.LIMITED 中執行 onOpen。不過，無論採用哪種授權模式，如要這麼做，請測試編輯器外掛程式。

Apps Script 會將授權模式做為 Apps Script 事件參數的 authMode 屬性傳遞，e；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 中執行，如下表所示。

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

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

已安裝編輯器外掛程式

從商店安裝編輯器外掛程式後，其 onInstall 函式會在 AuthMode.FULL 中執行。在這個授權模式中，外掛程式可以執行複雜的設定程序。您也應該使用 onInstall 建立選單項目，因為文件、表單、簡報或試算表已開啟，而您的 onOpen 函式尚未執行。下列範例說明如何從 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();
}

執行 onOpen 函式時，系統會載入整個指令碼，並以與 onOpen 相同的授權模式執行全域陳述式。如果授權模式禁止使用全域陳述式，全域陳述式和 onOpen 都無法執行。如果已發布的外掛程式無法新增選單項目，請查看瀏覽器控制台是否傳回錯誤。接著檢查指令碼，看看 onOpen 函式或全域變數是否呼叫 AuthMode.NONE 不允許的服務。

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

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

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

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

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

• 外掛程式嘗試執行目前授權模式不支援的 Apps Script 服務。

• 外掛程式會在使用者與其互動前，嘗試執行服務呼叫。

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

1. 開啟外掛程式的 Apps Script 專案，然後找出 onOpen 函式。
2. 搜尋 onOpen 函式，找出提及 Apps Script 服務或相關聯物件的部分，例如 PropertiesService、SpreadsheetApp 或 GmailApp。
3. 如果服務用於建立 UI 元素以外的用途，請移除服務或將其包裝在註解區塊中。只保留下列方法：.getUi、.createMenu、.addItem 和 .addToUi。此外，請找出並移除函式外的任何服務。
4. 找出可能含有在上一個步驟中註解或移除的程式碼行的函式，特別是使用這些函式所產生資訊的函式，然後將服務呼叫作業移至需要這些函式的函式。重新排列或重寫程式碼集，以配合上一個步驟所做的變更。
5. 儲存程式碼並建立測試部署作業。 建立測試部署作業時，請確認「設定」欄位為「為目前使用者安裝」，且「設定」方塊下方的文字顯示「在 AuthMode.NONE 中測試」。
6. 啟動測試部署作業，然後開啟「擴充功能」選單。
7. 如果所有選單項目都顯示出來，表示問題已修正。如果只看到「說明」選單，請返回步驟 1。 你可能錯過服務電話。

相關主題

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