編輯器外掛程式授權

許多以 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 事件參數 eauthMode 屬性傳遞;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() (僅適用於試算表)
自訂函式 所有其他時間,包括:
可安裝的觸發條件
onInstall()
google.script.run
使用者資料存取權 僅限語言代碼 僅限語言代碼 僅限語言代碼
存取文件、表單、簡報或試算表 是 - 唯讀
存取使用者介面 新增菜單品項 新增菜單品項
有權存取「Properties
有權存取「Jdbc」,UrlFetch
其他服務 Logger
Utilities
不會存取使用者資料的任何服務 不會存取使用者資料的任何服務 所有服務

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

如果您為目前的使用者安裝外掛程式,或在目前的檔案中啟用外掛程式,則當檔案開啟時,系統會載入文件、表單、簡報或試算表的外掛程式。外掛程式會列在「Extensions」選單中,並開始監聽簡單的觸發條件 onInstall()onOpen()onEdit()。只要按一下「Extensions」(擴充功能) 選單項目,系統就會執行

已安裝編輯器外掛程式

從商店安裝編輯器外掛程式時,其 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();
}

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

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

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

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

如果您的程式碼無法正確管理授權模式,外掛程式選單可能無法顯示。例如:

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

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

如要在 AuthMode.NONE 中移除或重新排列造成權限錯誤的服務呼叫,請嘗試以下動作:

  1. 開啟外掛程式的 Apps Script 專案,然後找出 onOpen() 函式。
  2. onOpen() 函式中搜尋提及 Apps Script 服務或與其相關聯的物件,例如 PropertiesServiceSpreadsheetAppGmailApp
  3. 如果服務用於建立 UI 元素以外的其他用途,請將其移除,或將其納入註解區塊中。僅保留這些方法:.getUi().createMenu().addItem().addToUi()。此外,您也可以尋找及移除函式以外的任何服務。
  4. 找出可能包含在前一個步驟中加註或移除的程式碼行的函式,尤其是使用該資訊產生的資訊行,並將服務呼叫移至需要這些程式碼的函式。重新排列或重新編寫程式碼集,以配合先前步驟所做的變更。
  5. 儲存程式碼並建立測試部署作業。

    建立測試部署作業時,請確認「Config」欄位為「Installed for current user」,且設定方塊下方的文字顯示「Test in AuthMode.None

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

  7. 如果顯示所有選單項目,表示問題已解決。 如果只顯示「說明」選單,請返回步驟 1。 你可能未接來電。