狙擊鏡

使用者必須授權外掛程式，以及存取其資料的其他應用程式 或代表他們行事當使用者首次執行外掛程式時， 外掛程式 UI 顯示開始授權流程的授權提示。

在這個流程中，提示訊息會告訴使用者應用程式需要執行什麼動作 所需的權限舉例來說，外掛程式可能需要讀取 使用者的電子郵件訊息，或在日曆中建立活動。外掛程式指令碼 專案會將這些個別權限定義為 OAuth 範圍。

在資訊清單中宣告範圍 使用網址字串在授權流程中，Apps Script 會顯示 以清楚易懂的方式說明使用者範圍舉例來說，您的 Google Workspace 外掛程式 使用「朗讀目前訊息」也就是在資訊清單中寫入 https://www.googleapis.com/auth/gmail.addons.current.message.readonly。過程中 在授權流程中，擁有此範圍的外掛程式會要求使用者允許 外掛程式：在外掛程式執行期間查看電子郵件。

查看範圍

如要查看指令碼專案目前所需的範圍，請執行 包括：

1. 開啟指令碼專案。
2. 按一下左側的「總覽」。 info_outline。
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 用戶端驗證 才能發布詳情請參閱下列指南：

• Apps Script 的 OAuth 用戶端驗證
• 未驗證的應用程式
• OAuth 驗證常見問題
• Google API 服務：使用者資料政策

受限制的範圍

特定範圍受到限制，並且必須遵守額外的規則 如何保護使用者資料如果日後想要發布 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 資訊清單欄位 設為 READ 或 READ_WRITE
寫入使用者產生的事件資料	https://www.googleapis.com/auth/calendar.addons.current.event.write 如果外掛程式需要寫入使用者產生的事件資料，則為必要屬性。 允許外掛程式編輯使用者產生的事件資料。這項資料是 僅適用於 addOns.calendar.eventAccess 資訊清單欄位 設為 WRITE 或 READ_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 應用程式中插入資源連結。 詳情請參閱 使用 @ 選單建立第三方資源。