本文档包含特定于 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 |
管理您的敏感邮件设置，包括哪些人可以管理您的邮件。
注意：受此范围保护的操作仅限用于管理用途。这些 API 仅适用于使用具有全网域授权的服务账号的 Google Workspace 客户。 |
上表中的范围表示其敏感程度，具体定义如下：
非敏感：这些范围提供的授权范围最小，仅需要基本的 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 应用验证常见问题解答可帮助您确定是否需要进行验证以及需要进行哪种类型的验证。