本頁面由 Cloud Translation API 翻譯而成。

狙擊鏡

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

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

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

查看範圍

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

開啟指令碼專案。
按一下左側的「總覽」。。
查看「專案 OAuth 範圍」下方的範圍。

此外，您也可以在專案資訊清單中，查看指令碼專案目前的範圍。 oauthScopes下」欄位中，但前提是您已明確設定這些範圍。

設定明確範圍

Apps Script 會自動掃描指令碼，決定指令碼需要的範圍。對大部分的指令碼來說，這是可節省您的時間，但對於已發布的外掛程式而言，以便更直接地控管範圍

舉例來說，Apps Script 可能會為外掛程式指令碼專案範圍預設為 https://mail.google.com使用者授權指令碼時並授予該專案使用者 Gmail 的完整存取權讓他們使用服務帳戶如果是已發布的外掛程式，您「必須」將這個範圍替換為其中包含外掛程式需求的有限組合。

如要明確設定指令碼專案使用的範圍，請編輯該檔案的資訊清單檔案。資訊清單欄位 oauthScopes 是陣列所需的全部範圍值。如要設定專案的範圍，請執行下列步驟：包括：

查看外掛程式目前使用的範圍。決定內容就需要進行調整例如縮小範圍
開啟外掛程式的資訊清單檔案。
找出標示為 oauthScopes 的頂層欄位。如果沒有即可新增。
oauthScopes 欄位會指定字串陣列。如何設定範圍請將這個陣列的內容替換成以及要使用哪些項目舉例來說，如要擴充 Gmail 的 Google Workspace 外掛程式，您可能會採取下列做法：
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
儲存資訊清單檔案變更。

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` 資訊清單欄位設為 `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 進階雲端硬碟服務。但如果是要使用基本雲端硬碟服務，不過，檔案授權是以個別檔案為基礎，會在使用者取消授權應用程式時撤銷。詳情請參閱要求存取所選檔案的範例。

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 應用程式中插入資源連結。詳情請參閱使用 @ 選單建立第三方資源。