許多以 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() (僅適用於試算表) |
自訂函式 | 所有其他時間,包括: 可安裝的觸發條件 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
中移除或重新排列造成權限錯誤的服務呼叫,請嘗試以下動作:
- 開啟外掛程式的 Apps Script 專案,然後找出
onOpen()
函式。 - 在
onOpen()
函式中搜尋提及 Apps Script 服務或與其相關聯的物件,例如PropertiesService
、SpreadsheetApp
或GmailApp
。 - 如果服務用於建立 UI 元素以外的其他用途,請將其移除,或將其納入註解區塊中。僅保留這些方法:
.getUi()
、.createMenu()
、.addItem()
和.addToUi()
。此外,您也可以尋找及移除函式以外的任何服務。 - 找出可能包含在前一個步驟中加註或移除的程式碼行的函式,尤其是使用該資訊產生的資訊行,並將服務呼叫移至需要這些程式碼的函式。重新排列或重新編寫程式碼集,以配合先前步驟所做的變更。
儲存程式碼並建立測試部署作業。
建立測試部署作業時,請確認「Config」欄位為「Installed for current user」,且設定方塊下方的文字顯示「Test in
AuthMode.None
」啟動測試部署作業,並開啟「Extensions」選單。
如果顯示所有選單項目,表示問題已解決。 如果只顯示「說明」選單,請返回步驟 1。 你可能未接來電。