選擇 Gmail API 範圍

本文件包含 Gmail API 專屬授權和驗證資訊。在閱讀本文件之前，請務必詳閱 Google Workspace 的一般驗證和授權資訊，請參閱「瞭解驗證與授權」一文。

設定 OAuth 2.0 以進行授權

設定 OAuth 同意畫面並選擇範圍，定義要向使用者顯示哪些資訊，以及應用程式審查人員，並註冊應用程式以供日後發布。

Gmail API 範圍

如要定義應用程式獲得的存取層級，您必須識別並宣告授權範圍。授權範圍是 OAuth 2.0 URI 字串，內含 Google Workspace 應用程式名稱、存取的資料類型及存取層級。「範圍」是應用程式處理 Google Workspace 資料的要求，包括使用者的 Google 帳戶資料。

當使用者安裝應用程式時，系統會要求使用者驗證應用程式使用的範圍。一般來說，您應該選擇可能最聚焦的範圍，並避免要求應用程式不需要的範圍。使用者更容易授予清楚明瞭的有限範圍存取權。

Gmail API 支援下列範圍：

範圍代碼 說明 適用情境
https://www.googleapis.com/auth/gmail.addons.current.action.compose 在您使用外掛程式時管理草稿及傳送電子郵件。 非敏感
https://www.googleapis.com/auth/gmail.addons.current.message.action 在您使用外掛程式時查看您的電子郵件。 非敏感
https://www.googleapis.com/auth/gmail.addons.current.message.metadata 在外掛程式執行時查看電子郵件中繼資料。 敏感內容
https://www.googleapis.com/auth/gmail.addons.current.message.readonly 在外掛程式執行期間查看電子郵件。 敏感內容
https://www.googleapis.com/auth/gmail.labels 僅建立、讀取、更新及刪除標籤。 非敏感
https://www.googleapis.com/auth/gmail.send 僅傳送訊息。沒有信箱的讀取或修改權限。 敏感內容
https://www.googleapis.com/auth/gmail.readonly 讀取所有資源及其中繼資料，不必進行寫入作業。 受限
https://www.googleapis.com/auth/gmail.compose 建立、讀取、更新及刪除草稿。傳送郵件和草稿。 受限
https://www.googleapis.com/auth/gmail.insert 僅限插入及匯入郵件。 受限
https://www.googleapis.com/auth/gmail.modify 所有讀取/寫入作業，除了立即永久刪除執行緒和訊息以外，略過垃圾桶。 受限
https://www.googleapis.com/auth/gmail.metadata 讀取資源中繼資料，包括標籤、記錄和電子郵件標頭，但不含郵件內文或附件。 受限
https://www.googleapis.com/auth/gmail.settings.basic 管理基本郵件設定。 受限
https://www.googleapis.com/auth/gmail.settings.sharing 管理敏感郵件設定，包括轉寄規則和別名。

注意：受這個範圍保護的作業僅限管理員使用。這類政策僅適用於使用全網域委派功能的 Google Workspace 客戶。		 受限
https://mail.google.com/ 具備帳戶信箱的完整存取權，包括永久刪除執行緒和郵件。只有在應用程式需要立即永久刪除執行緒和郵件，且可略過垃圾桶的情況下，才應要求這個範圍；所有其他動作都可以使用較寬鬆的範圍執行。 受限

上表中的「用量」欄是根據下列定義指出每個範圍的機密程度：

  • 非機密：這些範圍提供的授權存取權最小規模級別，而且只需進行基本應用程式驗證。如要進一步瞭解這項規定，請參閱「驗證準備步驟」。

  • 機密：這些範圍允許存取 Google 使用者資料，並需要經過機密範圍驗證程序。如要瞭解這項規定，請參閱「Google API 服務：使用者資料政策」。這些範圍不需要進行安全性評估。

  • 受限制：這些範圍可讓您廣泛存取 Google 使用者資料，因此需要您完成受限制的範圍驗證程序。如要進一步瞭解這項規定，請參閱「Google API 服務：使用者資料政策」和「特定 API 範圍的附加規定」。如果您將受限制範圍的資料儲存在伺服器 (或傳輸) 中，就必須進行安全性評估。

當您要求存取使用者資料時，有關 Gmail API 的使用和存取方式的其他相關資訊，請參閱「Gmail API 服務使用者資料和開發人員政策」。

如果您的應用程式需要存取任何其他 Google API，您也可以新增這些範圍。如要進一步瞭解 Google API 範圍，請參閱使用 OAuth 2.0 存取 Google API。

OAuth 驗證

使用某些機密 OAuth 範圍時，應用程式可能需要執行 Google 的 OAuth 驗證程序。請參閱 OAuth 驗證常見問題，判斷應用程式應在何時進行驗證，以及所需的驗證類型。另請參閱 Google API 服務：使用者資料政策。