选择 Google 云端硬盘 API 范围

本文档包含 Google Drive API 特有的授权和身份验证信息。在阅读本文档之前,请务必阅读了解身份验证和授权中的 Google Workspace 常规身份验证和授权信息。

配置 OAuth 2.0 以进行授权

配置 OAuth 同意屏幕并选择范围,以定义向用户显示的信息和应用审核者,并注册您的应用,以便日后发布。

Drive API 范围

如需定义授予应用的访问权限级别,您需要确定并声明授权范围。授权范围是一个 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/auth/drive.apps.readonly 查看有权访问您云端硬盘的应用。 敏感内容
https://www.googleapis.com/auth/drive 查看和管理您的所有云端硬盘文件。 受限
https://www.googleapis.com/auth/drive.readonly 查看和下载您的所有云端硬盘文件。 受限
https://www.googleapis.com/auth/drive.activity查看和添加您云端硬盘中的文件的活动记录。 受限
https://www.googleapis.com/auth/drive.activity.readonly查看云端硬盘中的文件的活动记录。 受限
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 范围,您的应用可能需要完成 Google 的 OAuth 验证流程。如需确定您的应用应在何时进行验证以及需要哪些类型的验证,请参阅 OAuth API 验证常见问题解答。另请参阅 Google 云端硬盘服务条款

何时使用受限范围

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

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

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

从受限范围迁移现有应用

如果您开发了使用任何受限范围的云端硬盘应用,我们建议您迁移应用以使用非敏感范围,因为此类范围会授予每个文件的访问权限范围,并缩小对应用所需特定功能的访问权限。许多应用都支持按文件访问,无需进行任何更改。如果您使用的是自己的文件选择器,我们建议您改用完全支持不同范围的 Google Picker 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 选择器文件上使用过滤器时,应用可以针对特定云端硬盘文件类型(例如 Google 文档、表格和幻灯片)应用过滤器。

此外,由于 drive.file 不敏感,因此可简化验证流程。

保存刷新令牌

将刷新令牌保存在安全的长期存储空间中,并在有效期内继续使用。