Apps Script 必須取得使用者授權,才能存取內建 Google 服務或進階 Google 服務的私人資料。
Google 服務授權的運作方式
如果指令碼需要存取 Google 服務,一般會遵循下列程序:
- 偵測:Apps Script 會掃描指令碼,找出使用的服務 (例如
SpreadsheetApp或GmailApp)。 - 範圍判斷:根據掃描結果,Apps Script 會找出執行指令碼所需的一組 OAuth 範圍。
- 授權檢查:指令碼執行時,會檢查使用者是否已授權這些範圍。
- 使用者提示:如果缺少授權,系統會顯示對話方塊,要求使用者授予權限。
- 執行:授權指令碼後,指令碼就能存取要求的使用者資料。
權限和指令碼類型
指令碼的執行身分 (以及可存取的資料) 會因指令碼的執行情境而異,如下表所示。
| 指令碼類型 | 指令碼執行身分... |
|---|---|
| 獨立、 外掛程式或 繫結至 Google 文件、試算表、簡報或表單 | 使用者在鍵盤前 |
| 試算表中的自訂函式 | 匿名使用者; 不過,配額限制 會計入鍵盤上的使用者 |
| 網頁應用程式或 Google 協作平台小工具 | 鍵盤使用者或指令碼擁有者,視部署應用程式時選取的選項而定 |
| 可安裝的觸發條件 | 建立觸發條件的使用者 |
授予存取權
Apps Script 會掃描程式碼,自動判斷授權範圍 (例如存取 Google 試算表檔案或 Gmail)。即使程式碼已加上註解,仍可產生授權要求。如果指令碼需要授權,執行時會顯示這裡所示的授權對話方塊。
如果程式碼變更後新增了服務,先前授權的指令碼也會要求額外授權。如果您以網路應用程式的形式存取指令碼,且該應用程式以指令碼擁有者的使用者身分執行,指令碼可能不會要求授權。
撤銷存取權
如要撤銷指令碼的資料存取權,請按照下列步驟操作:
- 前往 Google 帳戶的權限頁面。(如要日後前往這個頁面,請前往 Google.com,然後按一下畫面右上角的帳戶相片。接著依序點選「我的帳戶」、「登入與安全性」部分下方的「已連結的應用程式和網站」,然後點選「管理應用程式」。
- 按一下要撤銷授權的指令碼名稱,然後按一下右側的「移除」,接著在隨即顯示的對話方塊中按一下「確定」。
將範圍限制在目前的文件
如果您要建構外掛程式或其他使用試算表服務、文件服務、簡報服務或表單服務的指令碼,可以強制授權對話方塊只要求存取外掛程式或指令碼使用的檔案,而不是使用者所有的試算表、文件或表單。如要這麼做,請在檔案層級的註解中加入下列 JsDoc 註解:
/**
* @OnlyCurrentDoc
*/
如果指令碼包含宣告 @OnlyCurrentDoc 的程式庫,但主要指令碼實際需要存取的不只是目前檔案,則可以使用相反的註解 @NotOnlyCurrentDoc。
外掛程式的授權生命週期
Google 試算表、文件、簡報和表單的外掛程式通常會採用與繫結至文件的指令碼相同的授權模式。不過,在某些情況下,onOpen(e) 和 onEdit(e) 函式會在無授權模式下執行,這會造成一些額外的複雜情況。詳情請參閱外掛程式授權生命週期指南。
OAuth 應用程式使用者人數上限
使用 OAuth 存取 Google 使用者資料的應用程式 (包括 Apps Script 專案) 均受授權限制。詳情請參閱「OAuth 應用程式使用者限制」。
使用 Apps Script 時的重新驗證行為
Apps Script 不會強制執行您在 Google Cloud 服務設定中設定的重新驗證頻率。這是因為 Apps Script 可以使用觸發條件自動執行,而觸發條件的運作不需要使用者直接互動。這些自動執行的作業不會觸發重新驗證提示。在您指定的時間 (例如 12 小時) 過後,Apps Script 應用程式不會自動要求您重新驗證。
在資訊清單中設定明確的範圍
Apps Script 會掃描程式碼中的函式呼叫,自動判斷所需範圍。如需進一步控管,您可以在專案資訊清單 (appsscript.json) 中明確設定範圍。建議您為已發布的指令碼執行這項操作,確保您使用的是最低必要權限。
如需操作說明,請參閱「設定明確範圍」。
疑難排解
- 執行觸發條件時發生「需要授權」錯誤:觸發條件必須由建立者授權。如果您新增的程式碼需要新的權限,就必須在指令碼編輯器中手動執行一次函式,觸發授權對話方塊。
- 範圍未更新:如果您已更新程式碼,但授權對話方塊未反映變更,請嘗試儲存專案並重新整理編輯器。如果您在資訊清單中使用明確範圍,請務必將新範圍新增至
oauthScopes陣列。 - 「這個應用程式遭到封鎖」或未經驗證的應用程式警告:如果指令碼使用機密或受限制的範圍,但尚未通過 Google 驗證,就會發生這種情況。請參閱「OAuth 用戶端驗證」。