本頁面由 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`	所有不會存取使用者資料的服務	所有不會存取使用者資料的服務	所有服務

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

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

已安裝編輯器外掛程式

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

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 中執行。

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

當使用者按一下「擴充功能」選單項目時， Apps Script 會先檢查使用者是否已安裝外掛程式就會提示使用者這麼做如果使用者已授權外掛程式，指令碼就會執行對應 AuthMode.FULL 中的選單項目。在文件、表單、簡報或試算表中啟用外掛程式 (如果尚未啟用)。

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

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

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

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

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

建立測試部署作業時，請確認 Config 欄位「Installed for 目前使用者」，且「設定」方塊下方的文字顯示： 在 AuthMode.None 中測試
啟動測試部署作業，並開啟「Extensions」選單。
如果顯示所有選單項目，表示問題已解決。如果只看到「說明」選單，請返回步驟 1。你可能未接一通服務電話。

編輯者外掛程式授權

授權模式

編輯器外掛程式狀態

授權模式

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

已安裝編輯器外掛程式

編輯器外掛程式已開啟

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

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

相關主題