桌面应用和移动应用概览

注意： 这是适用于桌面应用和移动应用的 Google Picker API 的 Beta 版 。

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 密钥，请执行以下操作：

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > API 和服务 > 凭据。

   进入“凭据”页面

2. 点击创建凭据 > API 密钥。
3. 系统会显示您的新 API 密钥。
   • 点击“复制”图标 即可复制 API 密钥，以便在应用的代码中使用 。您还可以在项目的凭据的"API 密钥"部分中找到 API 密钥。
   • 为防止未经授权的使用，我们建议您限制 API 密钥 可用于哪些位置和 API。如需了解详情，请参阅 添加 API 限制。

为桌面应用授权凭据

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

1. 在 Google API 控制台中，依次前往“菜单”图标 > Google 身份验证平台 > 客户端。

   进入“客户端”页面

2. 点击创建客户端 。
3. 依次点击应用类型 > 桌面应用。
4. 在名称 字段中，输入凭据的名称。此名称仅在 Google API 控制台中显示。
5. 点击创建 。

   新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

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

1. 您必须使用以下说明获取具有 drive.file、drive 或 drive.readonly 范围的 OAuth 2.0 令牌：使用 OAuth 2.0 访问 Google API。如需详细了解范围， 请参阅选择 Google Drive API 范围。

2. 将 OAuth 2.0 令牌传递给 Drive API，以读取和修改用户之前授予访问权限的文件。

显示 Google Picker

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

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

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

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

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

   您必须将 prompt 和 trigger_onepick 网址参数附加到 OAuth 2.0 授权网址请求：

   参数	说明	状态
   prompt=consent	提示用户授予文件访问权限。	必需
   trigger_onepick=true	启用 Google Picker。	必需

   您还可以使用几个可选参数自定义 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 网址。

3. 用户授予访问权限并选择相关文件后，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
   

4. 应用必须将第 3 步中的授权代码换成新的 OAuth 2.0 令牌。如需了解详情，请参阅将授权代码换成刷新令牌 和访问令牌。

5. 然后，应用可以使用第 3 步中的网址参数中的文件 ID 和第 4 步中获得的 OAuth 2.0 令牌来调用 Drive API。如需了解更多 信息，请参阅 Google Drive API 概览。

在 Android 中使用 Google Picker

您还可以在 Android 移动应用中使用 Google Picker。

为移动应用授权凭据

如需在 Android 应用中使用 Google Picker，您需要使用 OAuth 2.0 授权用户 ，这与桌面应用类似。如需详细了解 Android 身份验证，请参阅 授权访问 Google 用户数据。

如需在授权期间显示 Google Picker，请创建 AuthorizationRequest 并使用 PICKER_OAUTH_TRIGGER 与 AuthorizationRequest.ResourceParameter结合使用。

构建 AuthorizationRequest 时：

• 使用 https://www.googleapis.com/auth/drive.file 范围。
• 调用 setOptOutIncludingGrantedScopes(true) ，以确保返回的令牌仅适用于 https://www.googleapis.com/auth/drive.file 范围，而不适用于之前授予的任何范围。
• 将 AuthorizationRequest.Prompt 字段设置为 CONSENT ，以便即使之前已授予用户权限，系统也会提示用户授予权限。此字段仅适用于包含资源参数的请求。
• 您可以选择使用位图“OR” (|) 运算符将 AuthorizationRequest.Prompt字段也设置为 SELECT_ACCOUNT ，以便在显示同意提示之前让用户选择账号。

调用 Google Picker

与桌面应用类似，您可以使用几个可选参数自定义 Google Picker：

• PICKER_ALLOW_MULTIPLE：允许用户选择多个文件。
• PICKER_MIMETYPES：返回用于过滤搜索结果的 MIME 类型逗号分隔列表。如果未设置，视图中会显示所有 MIME 类型的文件。
• PICKER_FILE_IDS：返回逗号分隔的文件 ID 列表，用于过滤搜索结果。如果未设置，视图中会显示所有文件。

如需详细了解桌面应用中的可选参数，请参阅显示 Google Picker。

用户授予访问权限并选择相关文件后，系统会返回 getTokenResponseParams 资源的 AuthorizationResult 对象。如果用户授予了访问权限，此对象将包含 picked_file_ids 值，该值是所选文件 ID 的英文逗号分隔列表。

相关主题

• 选择 Google Drive API 范围