选择 Google 表格 API 范围

本文档包含特定于 Google Sheets API 的授权和身份验证信息。在阅读本文档之前,请务必先阅读了解身份验证和授权,熟悉 Google Workspace 的一般身份验证和授权知识。

请注意,Sheets API 范围适用于电子表格文件,无法限定为特定的工作表。 如需防止修改工作表,请使用 ProtectedRange 定义无法编辑的单元格或单元格范围。如需查看示例,请参阅命名范围和受保护的范围

配置 OAuth 2.0 以进行授权

配置 OAuth 权限请求页面并选择范围,以定义向用户和应用审核者显示哪些信息,并注册应用以便日后发布。

Sheets API 范围

如需定义授予应用的访问权限级别,您需要识别并声明 授权范围。授权范围是 OAuth 2.0 URI 字符串,其中包含 Google Workspace 应用名称、访问的数据类型以及访问权限级别。范围是应用使用 Google Workspace 数据(包括 用户的 Google 账号数据)的请求。

安装应用后,系统会要求用户验证应用使用的范围。通常,您应选择尽可能狭窄的范围,并避免请求应用不需要的范围。用户更容易授予对有限且描述清晰的范围的访问权限。

我们建议尽可能使用非敏感范围,因为这样可以授予每个文件的访问范围,并缩小应用所需特定功能的访问权限。

Sheets API 支持以下范围:

范围代码 说明 用法
https://www.googleapis.com/auth/spreadsheets 查看、修改、创建和删除所有 Google 表格电子表格。 敏感
https://www.googleapis.com/auth/spreadsheets.readonly 查看所有 Google 表格电子表格。 敏感
https://www.googleapis.com/auth/drive.file 仅查看、修改、创建和删除您在此应用中使用的特定 Google 云端硬盘文件。 建议
非敏感
https://www.googleapis.com/auth/drive 查看、修改、创建和删除所有 Google 云端硬盘文件。 受限
https://www.googleapis.com/auth/drive.readonly 查看和下载所有 Google 云端硬盘文件。 受限

下表中的“用法”列根据以下定义指明了每个范围的敏感度:

  • 非敏感:这些范围提供的授权访问范围最小,仅需要进行基本应用验证。如需了解此 要求,请参阅提交应用以供 验证

  • 敏感:这些范围允许访问用户授权您的应用使用的特定 Google 用户数据 。您需要完成 额外的应用验证。如需了解此要求,请参阅 敏感范围和受限范围 的要求

  • 受限:这些范围允许广泛访问 Google 用户数据,并且 需要您完成受限范围验证流程。如需了解此要求,请参阅 Google API 服务用户数据 政策针对特定 API 范围的其他要求。 如果您在服务器上存储(或传输)受限范围数据,则必须完成安全评估。

如果您的应用需要访问任何其他 Google API,您也可以添加这些范围。如需详细了解 Google API 范围,请参阅使用 OAuth 2.0 访问 Google API

如需详细了解特定的 OAuth 2.0 范围,请参阅适用于 Google API的 OAuth 2.0 范围。