狙擊鏡

使用者必須授權外掛程式和其他存取個人資料或代表其執行操作的應用程式。當使用者首次執行外掛程式時,外掛程式 UI 會顯示啟動授權流程的授權提示。

在此流程中,提示會告訴使用者應用程式要執行哪些操作。例如,外掛程式可能會希望取得讀取使用者電子郵件訊息或在日曆中建立活動的權限。外掛程式的指令碼專案會將這些個別權限定義為 OAuth 範圍

您可以使用網址字串,在資訊清單中宣告範圍。在授權流程期間,Apps Script 會向使用者顯示清楚易懂的範圍說明。舉例來說,Google Workspace 外掛程式可能會使用「讀取目前訊息」範圍,此範圍在資訊清單中以 https://www.googleapis.com/auth/gmail.addons.current.message.readonly 寫入。在授權流程中,有這個範圍的外掛程式會要求使用者允許外掛程式:在外掛程式執行時檢視電子郵件

查看範圍

您可以按照下列步驟查看指令碼專案目前需要的範圍:

  1. 開啟指令碼專案。
  2. 按一下左側的「總覽」圖示
  3. 查看「專案 OAuth 範圍」下的範圍。

您也可以在專案資訊清單的 oauthScopes 欄位下方,查看指令碼專案目前的範圍,但前提是必須先明確設定這些範圍。

設定明確範圍

Apps Script 會掃描程式碼,找出需要範圍的函式呼叫,藉此自動判斷指令碼所需的範圍。對大部分的指令碼來說,這種做法可以節省大量時間,但如果是已發布的外掛程式,則應以更直接的方式控管範圍。

舉例來說,Apps Script 可能預設將外掛程式指令碼專案的範圍設為 https://mail.google.com 最寬鬆的範圍。當使用者以這個範圍授權指令碼專案時,該專案就會取得使用者 Gmail 帳戶的完整存取權。針對已發布的外掛程式,您「必須」將此範圍替換為更受限的組合,以涵蓋外掛程式的需求,而非更多。

您可以編輯指令碼專案的「資訊清單」檔案,明確設定指令碼專案使用的範圍。資訊清單欄位 oauthScopes 是外掛程式使用的所有範圍陣列。若要設定專案的範圍,請執行下列操作:

  1. 查看外掛程式目前使用的範圍。決定要進行哪些變更,例如縮小範圍。
  2. 開啟外掛程式的資訊清單檔案
  3. 找到標示 oauthScopes 的頂層欄位。如果沒有,可以新增。
  4. oauthScopes 欄位會指定字串陣列。如要設定專案使用的範圍,請將這個陣列的內容替換成您要使用的範圍。舉例來說,如果是擴充 Gmail 的 Google Workspace 外掛程式,可能會產生下列內容:

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      ...
    }
    
  5. 儲存資訊清單檔案變更。

OAuth 驗證

使用某些機密 OAuth 範圍時,您可能需要先完成 OAuth 用戶端驗證,然後才能發布外掛程式。詳情請參閱下列指南:

受限制的範圍

某些範圍會受限制,並須遵守其他有助於保護使用者資料的規則。如果您打算發布使用一或多個受限制範圍的 Gmail 或編輯器外掛程式,該外掛程式必須符合所有指定限制才能發布。

嘗試發布前,請先參閱受限制範圍的完整清單。如果您的外掛程式使用其中任何一種功能,則在發布之前,請務必遵守特定 API 範圍的額外規定

日曆範圍

以下是擴充 Google 日曆的 Google Workspace 外掛程式常用範圍。

範圍
存取事件中繼資料 https://www.googleapis.com/auth/calendar.addons.execute

如果外掛程式存取日曆活動中繼資料,則為必要屬性。允許外掛程式存取事件中繼資料。

讀取使用者產生的事件資料 https://www.googleapis.com/auth/calendar.addons.current.event.read

如果外掛程式需要讀取使用者產生的事件資料,則為必要參數。 允許外掛程式存取使用者產生的事件資料。只有在 addOns.calendar.eventAccess 資訊清單欄位設為 READREAD_WRITE 時,系統才能提供這項資料。

寫入使用者產生的事件資料 https://www.googleapis.com/auth/calendar.addons.current.event.write

如果外掛程式需要寫入使用者產生的事件資料,則為必要參數。 允許外掛程式編輯使用者產生的事件資料。只有在 addOns.calendar.eventAccess 資訊清單欄位設為 WRITEREAD_WRITE 時,系統才能提供這項資料。

雲端硬碟範圍

以下是可擴充 Google 雲端硬碟的 Google Workspace 外掛程式常用範圍。

範圍
讀取所選項目的中繼資料 https://www.googleapis.com/auth/drive.addons.metadata.readonly

如果外掛程式會實作內容介面,當使用者在雲端硬碟中選取項目時觸發,則為必要屬性。 允許外掛程式針對使用者在 Google 雲端硬碟中選取的項目讀取有限的中繼資料。中繼資料僅限於項目的 ID、標題、MIME 類型、圖示網址,以及外掛程式是否具備存取項目的權限。

個別檔案存取權 https://www.googleapis.com/auth/drive.file

如果外掛程式需要存取個別雲端硬碟檔案,建議採用此設定。使用 Apps Script 進階雲端硬碟服務,授予個別檔案存取權,以便存取應用程式建立或開啟的檔案。但是,這個做法不允許使用基本雲端硬碟服務執行類似動作。檔案授權是按個別檔案授予,當使用者取消授權應用程式時,系統會撤銷該檔案。

請參閱 要求存取所選檔案的範例

Gmail 外掛程式範圍

有些範圍專為 Google Workspace 外掛程式建立,有助於保護使用者的 Gmail 資料。您必須明確將這些範圍新增至外掛程式資訊清單,以及外掛程式程式碼所需的任何其他範圍。

以下是擴充 Gmail 的 Google Workspace 外掛程式常用範圍;如果您的外掛程式擴充 Gmail,就必須將標示為「必要」的範圍加入您的 Google Workspace 外掛程式資訊清單。

此外,請務必將外掛程式中範圍非常廣的 https://mail.google.com 範圍替換為較小的範圍,允許外掛程式所需的互動,避免更多互動。

範圍
建立新草稿 https://www.googleapis.com/auth/gmail.addons.current.action.compose

如果外掛程式使用 組合動作觸發條件,則為必要屬性。 允許外掛程式暫時建立新的訊息和回覆草稿。詳情請參閱「 撰寫草稿訊息」一節;這個範圍也經常與 撰寫動作搭配使用。需要存取權杖。

讀取開啟的郵件/訊息中繼資料 https://www.googleapis.com/auth/gmail.addons.current.message.metadata

授予暫時訊息中繼資料 (例如主旨或收件者) 的暫時存取權。不允許讀取訊息內容,且需要存取權杖。

如果外掛程式在組合動作觸發條件中使用中繼資料,則為必要屬性。針對 組合動作,如果 Compose 觸發條件需要存取中繼資料,就需要這個範圍。實際執行時,這個範圍可讓 Compose 觸發回覆電子郵件草稿的存取收件者清單 (收件者、副本:和密件副本)。

讀取開啟的郵件內容 https://www.googleapis.com/auth/gmail.addons.current.message.action

可在使用者互動時 (例如選取外掛程式選單項目) 存取已開啟訊息的內容。需要存取權杖。

閱讀公開討論串內容 https://www.googleapis.com/auth/gmail.addons.current.message.readonly

授予暫時訊息中繼資料和內容的暫時存取權。同時授予存取公開討論串中其他訊息內容的權限。需要存取權杖。

讀取所有訊息內容和中繼資料 https://www.googleapis.com/auth/gmail.readonly

讀取任何電子郵件的中繼資料和內容,包括已開啟的訊息。 如需讀取其他郵件的相關資訊,例如執行搜尋查詢或讀取整個郵件討論串時,則為必要屬性。

存取權杖

為保護使用者資料,Google Workspace 外掛程式中使用的 Gmail 範圍只會授予使用者資料的臨時存取權。如要啟用臨時存取權,您必須使用存取權杖做為引數,呼叫 GmailApp.setCurrentMessageAccessToken(accessToken) 函式。您必須從動作事件物件取得存取權杖。

以下示範如何設定存取權杖,以允許存取訊息的中繼資料。本範例只需要 https://www.googleapis.com/auth/gmail.addons.current.message.metadata 的範圍。

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

編輯器範圍

以下是適用於擴充文件、試算表和簡報的 Google Workspace 外掛程式常用範圍。

範圍
目前的文件檔案存取權 https://www.googleapis.com/auth/documents.currentonly

如果外掛程式存取 Apps Script Document API,則為必要項目。 授予開放文件內容的臨時存取權。

目前的試算表檔案存取權 https://www.googleapis.com/auth/spreadsheets.currentonly

如果外掛程式存取 Apps ScriptSheet API,則為必要屬性。 授予開放試算表內容的臨時存取權。

目前的簡報檔案存取權 https://www.googleapis.com/auth/presentations.currentonly

如果外掛程式存取 Apps ScriptSlide API,則為必要屬性。 授予開放簡報內容的臨時存取權。

個別檔案存取權 https://www.googleapis.com/auth/drive.file

如果外掛程式是存取 onFileScopeGrantedTrigger,且外掛程式能存取 Google 文件、試算表、簡報或 Drive API,這是必要元素。 使用 Apps Script 進階雲端硬碟服務,授予個別檔案存取權,以便存取應用程式建立或開啟的檔案。但是,這個做法不允許使用基本雲端硬碟服務執行類似動作。檔案授權是按個別檔案授予,並在使用者取消授權應用程式時撤銷。

其他範圍

如果外掛程式使用其他 Apps Script 服務,可能需要額外範圍。 在大多數情況下,您可以讓 Apps Script 偵測這些範圍,並自動更新資訊清單。編輯資訊清單的範圍清單時,除非您想將範圍替換為更適當的替代範圍 (例如較小的範圍),否則請勿移除任何範圍。

以下是經常與 Google Workspace 外掛程式搭配使用的 Apps Script 範圍清單,供您參考:

範圍
讀取使用者的電子郵件地址 https://www.googleapis.com/auth/userinfo.email

允許專案讀取目前使用者的電子郵件地址。

允許呼叫外部服務 https://www.googleapis.com/auth/script.external_request

允許專案發出 UrlFetch 要求。如果專案使用 Apps Script 的 OAuth2 程式庫,也必須符合這個條件。

讀取使用者的語言代碼和時區 https://www.googleapis.com/auth/script.locale

可讓專案記住目前使用者的語言代碼和時區。詳情請參閱「 存取使用者的語言代碼和時區」。

建立觸發條件 https://www.googleapis.com/auth/script.scriptapp

允許專案建立 觸發條件

預覽第三方連結 https://www.googleapis.com/auth/workspace.linkpreview

如果外掛程式預覽來自第三方服務的連結,則為必要屬性。 允許專案在使用者與其互動時,在 Google Workspace 應用程式中查看連結。詳情請參閱「 預覽含有智慧型方塊的連結」一文。

建立第三方資源 https://www.googleapis.com/auth/workspace.linkcreate

如果外掛程式在第三方服務中建立資源,則為必要屬性。 可讓專案讀取使用者提交至資源建立表單的資訊,並在 Google Workspace 應用程式中插入資源連結。詳情請參閱「 透過 @ 選單建立第三方資源」。