选择 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 或应用的文件选择器时与应用共享的文件。

敏感范围

范围代码 说明
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 API 范围。使用非敏感范围（例如 drive.file）可以授予每个文件的访问权限，并缩小应用所需特定功能的访问权限。

许多应用无需任何更改即可转换为每个文件的访问权限。

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

云端硬盘文件范围的优势

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

借助 drive.file OAuth 范围，用户可以选择要与您的应用共享的文件。这让他们可以更好地控制应用对其文件的访问权限，并确信应用对文件的访问权限是有限且更安全的。相比之下，要求广泛访问所有云端硬盘文件可能会让用户不愿与您的应用互动。

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

安全地存储刷新令牌

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

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

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

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