选择 Google 云端硬盘 API 范围

本文档包含 Google Drive API 专用授权和身份验证信息。在阅读本文档之前,请务必参阅 了解身份验证和授权,了解 Google Workspace 的一般身份验证和授权信息。

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

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

在用户安装您的应用时,系统会要求用户验证该应用使用的范围。通常,您应尽可能选择最窄的范围,并避免请求应用不需要的范围。用户更乐意向描述清晰的有限范围授予访问权限。

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

Drive API 支持以下范围:

范围代码 说明 用法
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder
在您的 Google 云端硬盘中查看和管理该应用自己的配置数据。 建议
非敏感
https://www.googleapis.com/auth/drive.install 允许应用显示为“打开方式”或“新建”菜单中的选项。 推荐
不敏感
https://www.googleapis.com/auth/drive.file 使用 Google Picker API 或应用的文件选择器创建新的云端硬盘文件,或修改您使用应用打开的文件或用户与应用共享的现有文件。 推荐
不敏感
https://www.googleapis.com/auth/drive.apps.readonly 查看有权访问您云端硬盘的应用。 敏感内容
https://www.googleapis.com/auth/drive 查看和管理您的所有云端硬盘文件。 受限
https://www.googleapis.com/auth/drive.readonly 查看和下载您的所有云端硬盘文件。 受限
https://www.googleapis.com/auth/drive.activity 查看 Google 云端硬盘中的文件的更改历史记录并添加活动记录。 受限
https://www.googleapis.com/auth/drive.activity.readonly 查看云端硬盘中文件的活动记录。 受限
https://www.googleapis.com/auth/drive.meet.readonly 查看由 Google Meet 创建或修改的云端硬盘文件。 受限
https://www.googleapis.com/auth/drive.metadata 查看和管理您云端硬盘中文件的元数据。 受限
https://www.googleapis.com/auth/drive.metadata.readonly 查看云端硬盘中的文件的元数据。 受限
https://www.googleapis.com/auth/drive.scripts 修改用 Google Apps 脚本语言编写的脚本的行为。 受限

根据以下定义,上表中的“用量”列表示每个范围的敏感度:

  • 推荐 / 不敏感:这些范围提供最小范围的授权访问权限,并且只需进行基本应用验证。如需了解此要求,请参阅验证要求

  • 推荐 / 敏感:这些范围可提供对用户为您的应用授权的特定 Google 用户数据的访问权限。您需要完成额外的应用验证。如需了解此要求,请参阅敏感和受限范围要求

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

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

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

OAuth 验证

如需使用某些 OAuth 范围,您的应用可能需要按照 OAuth 应用验证帮助中心中的说明操作。请参阅 OAuth 应用常见问题解答,确定您的应用何时应进行验证以及需要进行哪种类型的验证。另请参阅 Google 云端硬盘服务条款

何时使用受限范围

对于云端硬盘,只有以下类型的应用可以访问受限范围:

  1. 提供本地同步或自动备份用户云端硬盘文件的平台专用应用和 Web 应用。
  2. 效率应用和教育应用,其界面可能涉及与云端硬盘文件(或其元数据或权限)的互动。效率应用包括任务管理、记事、工作组通信和课堂协作应用。
  3. 报告和安全应用,可为用户或客户提供有关文件共享或访问方式的分析洞见。

如需继续使用受限范围,您应为应用准备受限范围验证

从受限范围迁移现有应用

如果您使用了任何受限范围开发了 Google 云端硬盘应用,我们建议您迁移应用以使用非敏感范围,因为该范围会授予按文件访问范围,并缩小对应用所需特定功能的访问权限。许多应用无需任何更改即可使用按文件访问权限。如果您使用的是自己的文件选择器,我们建议您改用 Google Picker API,该 API 完全支持不同的镜重。

drive.file OAuth 范围的优势

使用 drive.file OAuth 范围和 Google Picker API 可优化应用的用户体验和安全性。

借助 drive.file OAuth 范围,用户可以选择要与您的应用共享哪些文件。这样,他们可以更好地控制自己的文件,并对您的应用对其文件的访问权限更加放心,因为访问权限受到限制且更安全。相反,如果要求对所有云端硬盘文件拥有广泛的访问权限,可能会让用户不愿与您的应用互动。以下是您应使用 drive.file 作用域的一些原因:

  • 易用性drive.file 范围适用于所有 Drive API REST 资源,这意味着您可以像使用更广泛的 OAuth 范围一样使用它。

  • 功能:Google Picker API 提供与云端硬盘界面类似的接口。其中包括几个用于显示云端硬盘文件预览和缩略图的视图,以及一个内嵌的模态窗口,以便用户无需离开主应用。

  • 便捷:在对 Google Picker 文件使用过滤条件时,应用可以对特定的云端硬盘文件类型(例如 Google 文档、表格和照片)应用过滤条件。

此外,由于 drive.file 是非敏感数据,因此可以简化验证流程。

保存刷新令牌

将刷新令牌保存在安全的长期存储空间中,只要它们仍然有效,您就可以继续使用。