編輯器外掛程式授權

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

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

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

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

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

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

授權模型

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

編輯器外掛程式狀態

擴充功能選單中的編輯器外掛程式已安裝及/或啟用。

• 使用者或管理員從 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 模式下執行程式碼後，外掛程式就能使用使用者授權的所有範圍。

注意： 只有已發布的編輯器外掛程式才能位於 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 中執行，如下表所示。

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

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

如果目前使用者已安裝外掛程式，或目前檔案已啟用外掛程式，當您開啟該文件、表單、簡報或試算表時，系統就會載入外掛程式。外掛程式會列在「擴充功能」選單中，並開始監聽簡單觸發條件 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() 都無法執行。如果發布的增效工具無法新增選單項目，請檢查瀏覽器的 JavaScript 控制台，看看是否傳回錯誤。接著檢查指令碼，看看 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。 你可能錯過服務電話。

相關主題

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