选择 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 服务：用户数据政策。