选择 Google 云端硬盘 API 范围

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

配置 OAuth 2.0 以进行授权

为了授权您的应用，Google Drive API 要求您在两个位置定义 OAuth 范围：Google Cloud 控制台和您的应用。

在 Google Cloud 控制台中，您必须在应用的 OAuth 权限请求页面配置中声明应用所需的范围。这是您的应用可以请求的最高权限级别。这相当于向 Google 提出的正式请求，声明的范围是 Google 在同意页面上向用户显示的内容。这样一来，用户便可确切了解您的应用请求访问哪些数据和操作。

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

在应用中，当您启动 API 时，必须明确请求该会话所需的特定范围。虽然 Google Cloud 控制台定义了您的应用可以请求的最高权限级别，但代码决定了特定用户的实际权限。这有助于确保应用仅请求特定任务所需的权限。

您可以在应用的代码中一次性以数组形式声明一个或多个 OAuth 范围。

以下代码示例展示了如何声明多个 OAuth 范围：

Java

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

如需查看如何在完整的代码示例中声明和使用范围，请参阅快速入门。

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 或应用的 file picker 时与应用共享的现有文件。

敏感范围

范围代码 说明
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 查看和添加云端硬盘中文件的活动记录。
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 API，您也可以添加这些范围。如需详细了解 Google API 范围，请参阅使用 OAuth 2.0 访问 Google API。

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

受限范围的资格要求

只有特定类型的应用才能使用 Google 云端硬盘的受限范围。如需符合条件，您的应用必须属于以下类别之一：

  1. 备份与同步：提供本地同步或自动备份用户云端硬盘文件的平台专用应用和 Web 应用。

  2. 效率和教育：主要用户界面可能涉及与云端硬盘文件、元数据或权限互动的应用。这些应用包括任务管理、记笔记、工作群组通信和课堂协作应用。

  3. 报告和安全性：可让用户或客户深入了解文件共享或访问方式的应用。

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

从受限范围迁移现有应用

如果您的 Drive 应用使用受限范围，我们建议您迁移到非敏感的 Drive API 范围。使用非敏感范围（例如 drive.file）可以授予每个文件的访问权限，并缩小应用所需特定功能的访问权限。

许多应用无需进行任何更改即可过渡到按文件访问。

如果您使用的是自己的文件选择器，建议您改用 Google Picker API，该 API 完全支持不同的范围。

云端硬盘文件范围的优势

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

借助 drive.file OAuth 范围，用户可以选择要与您的应用共享哪些文件。这样一来，用户可以更好地控制应用对文件的访问权限，并更放心地使用您的应用。相比之下，如果要求对所有云端硬盘文件拥有广泛的访问权限，可能会让用户不愿意与您的应用互动。

以下是您应使用 drive.file 范围的一些原因：

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

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

  • 便利性：应用在使用 Google 选择器文件过滤器时，可以针对某些云端硬盘文件类型（例如 Google 文档、表格和照片）应用过滤器。

  • 简单的验证流程：由于 drive.file 不属于敏感范围，因此可以简化验证流程。

安全地存储刷新令牌

如需使用 Drive API 访问非公开数据，您的应用必须获取用于授予该 API 访问权限的访问令牌。一个访问令牌可以授予对多个 API 的不同程度的访问权限，具体取决于您请求的范围。

由于访问令牌的有效期较短，因此您必须使用刷新令牌才能长期访问 Drive API。借助刷新令牌，您的应用可以请求新的访问令牌。

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

如需了解详情，请参阅使用 OAuth 2.0 访问 Google API。