編輯者外掛程式授權

許多 Apps Script 應用程式的授權流程相當簡單明瞭,因為 有人嘗試執行指令碼專案時,會要求提供任何缺少的必要權限 以便使用。

授權模型 編輯器外掛程式為 但可能的原因如下:

  • 使用者建立檔案時,使用者會安裝的所有外掛程式 列在 [擴充功能] 選單 如果使用者尚未授權這些外掛程式

  • 這些外掛程式適用於 可與協作者共用的 Google 雲端硬碟。協作者: 已安裝編輯器外掛程式,即可在文件中查看 供檔案建立者使用

  • 編輯器外掛程式會自動執行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 模式下執行後, 外掛程式可以使用使用者授權的所有範圍。

Apps Script 通過授權模式 做為 Apps Script 的 authMode 屬性 事件參數e;值 e.authMode 對應 Apps Script 中的常數 ScriptApp.AuthMode 列舉。

授權模式適用於所有 Apps Script 執行方法, 包括從指令碼編輯器、選單項目或 Apps Script 執行 google.script.run 呼叫。不過 只有在指令碼將結果執行時,才能檢查 e.authMode 屬性 觸發條件,例如 onOpen()onEdit()onInstall()自訂函式 在 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() 函式尚未執行。 以下範例說明如何呼叫 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,請嘗試以下動作:

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

    建立測試部署作業時,請確認 Config 欄位 「Installed for 目前使用者」,且「設定」方塊下方的文字顯示: AuthMode.None 中測試

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

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