狙擊鏡

使用者必須授權外掛程式,以及存取其資料的其他應用程式 或代表他們行事當使用者首次執行外掛程式時, 外掛程式 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 外掛程式範圍

有幾個範圍是專門針對 可協助保護 Gmail 使用者的 Google Workspace 外掛程式 資料。您必須 明確新增這些範圍 以及其他應用程式 需要外掛程式的程式碼

以下是擴充 Gmail 的 Google Workspace 外掛程式常用範圍。 您必須將標示為必要的項目加進 Google Workspace 外掛程式資訊清單 (如果外掛程式擴充為適用) Gmail。

另外,請務必替換您的https://mail.google.com 這個外掛程式,且範圍較小,可讓外掛程式進行互動 變得十分重要

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

如果外掛程式有使用,則為必要屬性 Compose 動作觸發條件 允許外掛程式暫時建立新的草稿訊息及 以及回覆內容詳情請參閱 撰寫郵件草稿 瞭解詳情;這個範圍通常會用於 撰寫動作。 需要存取權杖。

讀取開放式訊息中繼資料 https://www.googleapis.com/auth/gmail.addons.current.message.metadata

可暫時存取開放郵件中繼資料 (例如 主旨或收件者)。禁止朗讀郵件內容 因此需要存取權杖

如果外掛程式在 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

讀取任何電子郵件中繼資料和內容,包括開啟的郵件。 如果您需要讀取其他郵件的相關資訊,例如 系統在執行搜尋查詢或閱讀整個郵件串時觸發。

存取權杖

為保護使用者資料,以下 Gmail 範圍中使用的 Gmail 範圍 僅限 Google Workspace 外掛程式授權 暫時存取使用者資料。如要啟用暫時存取權,您必須呼叫 函式 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 外掛程式的常用範圍,適用於 Google 文件、試算表、 和簡報

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

如果外掛程式存取 Apps Script Docs API,則為必要元素。 授予暫時存取開啟文件內容的權限。

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

如果外掛程式存取 Apps Script Sheets API,則為必要屬性。 授予暫時存取試算表內容的權限。

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

如果外掛程式存取 Apps Script Slides API,則為必要屬性。 授予目前簡報內容的暫時存取權。

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

必須安裝此外掛程式才能使用 onFileScopeGrantedTrigger 以及是否可存取 Docs、Sheets、Slides 或 Drive API。 使用 Apps Script 進階雲端硬碟 服務。但如果是要使用 基本雲端硬碟服務, 不過,檔案授權是以個別檔案為基礎, 則會因使用者取消授權而撤銷。

其他範圍

如果您的外掛程式使用其他 Apps Script 服務,可能會需要額外的範圍。 在大部分的情況下,您可以允許 Apps Script 偵測這些範圍並更新 資訊清單。編輯資訊清單的範圍清單時,請勿移除 任何範圍,除非您使用更合適的替代選項來取代。 例如縮小範圍

以下是一些 Apps Script 範圍常用的清單,供你參考 搭配 Google Workspace 外掛程式:

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

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

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

允許專案 UrlFetch敬上 要求。如果專案使用 OAuth2 for Apps Script 程式庫。

讀取使用者的語言代碼和時區 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 應用程式中插入資源連結。 詳情請參閱 使用 @ 選單建立第三方資源。