桌面应用概览

Google Picker API 可让用户选择或上传 Google 云端硬盘文件。用户可以向您的桌面应用授予访问其云端硬盘数据的权限，从而提供一种安全且经过授权的方式来与其文件进行交互。

Google Picker 充当存储在云端硬盘上的文件的“文件打开”对话框，并具有以下几项功能：

与 Google 云端硬盘界面类似的外观和风格。
多个视图，用于显示云端硬盘文件的预览和缩略图。
在用户默认浏览器的新标签页中重定向到 Google Picker。

请注意，Google Picker 不允许用户将文件从一个文件夹整理、移动或复制到另一个文件夹。如需管理文件，您必须使用 Google Drive API 或云端硬盘界面。

前提条件

使用 Google Picker 的应用必须遵守所有现有的 Terms of Service。最重要的是，您必须在请求中正确标识自己。

您还必须拥有一个 Google Cloud 项目。

设置环境

如需开始使用 Google Picker API，您必须设置环境。

启用 API

在使用 Google API 之前，您需要在 Google 云项目中启用它们。您可以在单个 Google Cloud 项目中启用一个或多个 API。

在 Google Cloud 控制台中，启用 Google Picker API。

启用 API

创建 API 密钥

API 密钥是一个长字符串，包含大小写字母、数字、下划线和连字符，例如 AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe。此身份验证方法用于匿名访问公开提供的数据，例如使用“拥有此链接的互联网用户均可”共享设置共享的 Google Workspace 文件。如需了解详情，请参阅管理 API 密钥。

如需创建 API 密钥，请执行以下操作：

在 Google Cloud 控制台中，依次前往“菜单”图标 > API 和服务 > 凭据。
进入“凭据”页面
点击创建凭据 > API 密钥。
系统会显示您的新 API 密钥。
- 点击“复制”图标，复制您的 API 密钥以在应用的代码中使用。您还可以在项目的凭据的"API 密钥"部分中找到 API 密钥。
- 为防止未经授权的使用，我们建议您限制 API 密钥可用于哪些位置和 API。如需了解详情，请参阅添加 API 限制。

为桌面应用授权凭据

如需对最终用户进行身份验证并访问应用中的用户数据，您需要创建一个或多个 OAuth 2.0 客户端 ID。客户端 ID 用于向 Google 的 OAuth 服务器标识单个应用。如果您的应用在多个平台上运行，您必须为每个平台创建一个单独的客户端 ID。

在 Google API 控制台中，依次前往“菜单”图标 > Google 身份验证平台 > 客户端。
进入“客户端”页面
点击创建客户端 。
依次点击应用类型 > 桌面应用。
在名称字段中，输入凭据的名称。此名称仅在 Google API 控制台中显示。
点击创建。
新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

如需让应用获得对之前授予它们的文件进行授权的权限，您必须按照以下步骤操作：

您必须使用以下说明获取具有 drive.file、drive 或 drive.readonly 范围的 OAuth 2.0 令牌：使用 OAuth 2.0 访问 Google API。如需详细了解范围，请参阅选择 Google Drive API 范围。
将 OAuth 2.0 令牌传递给 Drive API，以读取和修改用户之前授予访问权限的文件。

显示 Google Picker

桌面版 Google Picker API 会在用户默认浏览器的新标签页中重定向到 Google Picker。用户授予访问权限并选择相关文件后，Google Picker 会通过回调网址返回到调用应用。如需让 Google Picker API 在客户端页面中打开，请改用 Google Picker API for Web 应用。如需了解详情，请参阅 Web 应用概览。

如需允许用户授予对其他文件的访问权限，或选择文件以在桌面应用流程中使用，请按以下步骤操作：

按照以下说明请求访问 drive.file 范围，以在新浏览器标签页中打开 OAuth 2.0 访问页面：使用 OAuth 2.0 访问 Google API。如需详细了解范围，请参阅选择 Google Drive API 范围。

请注意，桌面应用仅允许使用 drive.file 范围，并且不能与其他任何范围结合使用。

新浏览器标签页的网址接受所有标准 OAuth 查询字符串参数。

您必须将 prompt 和 trigger_onepick 网址参数附加到 OAuth 2.0 授权网址请求中。您还可以使用多个可选参数自定义 Google Picker：

参数	说明	状态
`prompt=consent`	提示用户授予文件访问权限。	必需
`trigger_onepick=true`	启用 Google Picker。	必需
`allow_multiple=true`	如果为 true，则允许用户选择多个文件。	可选
`mimetypes=MIMETYPES`	以逗号分隔的 MIME 类型列表，用于过滤搜索结果。如果未设置，则视图中会显示所有 MIME 类型的文件。	可选
`file_ids=FILE_IDS`	以逗号分隔列表形式的文件 ID，用于过滤搜索结果。如果未设置，则视图中会显示所有文件。	可选
`allow_folder_selection=true`	如果为 true，则允许用户选择文件夹。	可选

以下示例展示了 OAuth 2.0 授权网址请求：

https://accounts.google.com/o/oauth2/v2/auth? \
client_id=CLIENT_ID \
&scope=https://www.googleapis.com/auth/drive.file \
&redirect_uri=REDIRECT_URI \
&response_type=code \
&access_type=offline \
&prompt=consent \
&trigger_onepick=true

替换以下内容：

CLIENT_ID：桌面应用的客户端 ID。
REDIRECT_URI：授权服务器在身份验证成功后将用户浏览器重定向到的位置。例如，https://www.cymbalgroup.com/oauth2callback。

指定的 redirect_uri 必须是公开的 HTTPS 网址。如果您想为 redirect_uri 使用自定义协议或 localhost 网址，则必须使用公开的 HTTPS 网址，然后重定向到自定义协议或 localhost 网址。

用户授予访问权限并选择相关文件后，OAuth 会重定向到请求中指定的 redirect_uri，并附加以下网址参数：
- picked_file_ids：如果用户授予了访问权限并选择了文件，则为所选文件 ID 的英文逗号分隔列表。
- code：根据请求中设置的 response_type 参数，访问令牌或访问代码。此参数包含新的授权代码。
- scope：请求中包含的范围。
- error：如果用户在同意流程中取消了请求，则会显示错误。
以下示例展示了 OAuth 2.0 授权网址响应：
```
https://REDIRECT_URI?picked_file_ids=PICKED_FILE_IDS&code=CODE&scope=SCOPES
```
应用必须将第 3 步中的授权代码换成新的 OAuth 2.0 令牌。如需了解详情，请参阅将授权代码换成刷新令牌和访问令牌。
然后，应用可以使用第 3 步中的网址参数中的文件 ID 和第 4 步中获得的 OAuth 2.0 令牌来调用 Drive API。如需了解更多信息，请参阅 Google Drive API 概览。