狙擊鏡

使用者必須授權外掛程式，以及存取其資料的其他應用程式 或代表他們行事使用者首次執行外掛程式時，外掛程式 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 Workspace 外掛程式 (可擴充 Google 日曆) 常用的範圍。

範圍
存取事件中繼資料	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 Workspace 外掛程式常用的範圍，可用於擴充 Google 雲端硬碟。

範圍
讀取所選項目的中繼資料	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 外掛程式常用範圍。 您必須將標示為必要的項目加進 Google Workspace 外掛程式資訊清單 (如果外掛程式擴充為適用) Gmail。

請務必將外掛程式中的廣泛 https://mail.google.com 範圍，替換為較狹隘的範圍組合，以便允許外掛程式需要的互動，但不超過這個範圍。

範圍
建立新草稿	https://www.googleapis.com/auth/gmail.addons.current.action.compose 如果外掛程式使用 Compose 動作觸發事件，則為必要屬性。允許外掛程式暫時建立新的草稿訊息及 以及回覆內容詳情請參閱「撰寫草稿訊息」一文；這個範圍也經常與 Compose 動作搭配使用。需要存取權杖。
讀取開啟的訊息中繼資料	https://www.googleapis.com/auth/gmail.addons.current.message.metadata 授予開啟郵件中繼資料 (例如主旨或收件者) 的臨時存取權。禁止朗讀郵件內容 因此需要存取權杖 如果外掛程式在 Compose 動作中使用中繼資料，則為必要屬性 觸發條件。 適用於 組合動作，如果撰寫觸發條件，則需要使用這個範圍 需要中繼資料的存取權實際上，這個範圍可讓撰寫觸發事件存取回覆電子郵件草稿的收件者清單 (to:、cc: 和 bcc:)。
讀取已開啟的訊息內容	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，以及要存取 Google 文件、試算表、簡報或雲端硬碟 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 要求。如果專案使用 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 應用程式中插入資源的連結。詳情請參閱「透過 @ 選單建立第三方資源」。