本文包含 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.labels |
查看及編輯電子郵件標籤。 |
機密範圍
| 範圍代碼 | 說明 |
|---|---|
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.send |
代表您傳送電子郵件。 |
受限制的範圍
| 範圍代碼 | 說明 |
|---|---|
https://mail.google.com/ |
閱讀、撰寫、傳送及永久刪除 Gmail 中的所有電子郵件。
注意：只有在應用程式需要立即永久刪除郵件串和郵件 (略過垃圾桶) 時，才要求這個範圍。您可以使用限制較少的範圍執行所有其他動作。 |
https://www.googleapis.com/auth/gmail.readonly |
查看你的電子郵件和設定。 |
https://www.googleapis.com/auth/gmail.compose |
管理草稿和傳送電子郵件。 |
https://www.googleapis.com/auth/gmail.insert |
在您的 Gmail 信箱中新增電子郵件。 |
https://www.googleapis.com/auth/gmail.modify |
在您的 Gmail 帳戶中閱讀、撰寫及傳送電子郵件。這個範圍不允許立即永久刪除對話串和訊息，略過垃圾桶。 |
https://www.googleapis.com/auth/gmail.metadata |
查看標籤和標頭這類電子郵件中繼資料 (不包括電子郵件內文)。 |
https://www.googleapis.com/auth/gmail.settings.basic |
查看、編輯、建立或變更您的 Gmail 電子郵件設定和篩選器。 |
https://www.googleapis.com/auth/gmail.settings.sharing |
管理您的機密郵件設定，包括誰能管理您的郵件。
注意：受這個範圍保護的作業僅限管理用途。只有使用具備全網域委派的服務帳戶，Google Workspace 客戶才能使用這些 API。 |
根據下列定義，上表中的範圍代表其敏感度：
非敏感：這些範圍提供的授權範圍最小，且僅需通過基本的 OAuth 應用程式驗證。詳情請參閱「驗證規定」。
機密：這些範圍可存取使用者授權應用程式存取的特定 Google 使用者資料，且需要額外的 OAuth 應用程式驗證。詳情請參閱「敏感和受限制範圍規定」。
受限制：這些範圍提供廣泛的 Google 使用者資料存取權，且需要通過受限制範圍 OAuth 應用程式驗證。詳情請參閱《Google API 服務使用者資料政策》和「特定 API 範圍附加規定」。
如果您在伺服器上儲存 (或傳輸) 受限制範圍的資料，就必須接受安全性評估。
如要進一步瞭解您在要求存取使用者資料時，使用及存取 Gmail API 的相關規定，請參閱 Google Workspace API 使用者資料和開發人員政策。
如果應用程式需要存取任何其他 Google API，也可以新增這些範圍。如要進一步瞭解 Google API 範圍，請參閱「使用 OAuth 2.0 存取 Google API」。
如要進一步瞭解特定 OAuth 2.0 範圍，請參閱「Google API 適用的 OAuth 2.0 範圍」。
OAuth 驗證
使用特定機密 OAuth 範圍時，應用程式可能需要完成 Google 的 OAuth 驗證程序。 請參閱 OAuth 應用程式驗證常見問題，判斷是否需要驗證，以及需要哪種驗證。