将 Google Picker 集成到桌面应用和移动应用中

本文档介绍了如何使用 Google Picker API 将 Google Picker 集成到桌面应用和移动应用中。

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

功能

Google Picker 具有以下几项功能：

  • 与 Google 云端硬盘 界面类似的外观和风格。
  • 多个视图，用于显示云端硬盘文件的预览和缩略图。
  • 预过滤的视图，仅显示特定文件类型（例如 PDF 或图片）或特定文件夹。
  • 在用户默认浏览器的新标签页中重定向到 Google Picker。

请注意，虽然您可以使用 Google Picker 选择和上传文件，但它不允许用户整理、移动或复制文件。如需管理文件，您必须使用 Google Drive API 或 云端硬盘界面。

前提条件

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

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

设置环境

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

启用 API

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

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

    启用 API

设置身份验证和授权

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

为桌面应用授权凭据

如需创建 OAuth 2.0 客户端 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，以读取和修改用户之前授予访问权限的文件。

为移动应用授权凭据

如需创建 OAuth 2.0 客户端 ID，请按照为移动应用授权凭据 下的步骤操作。

为 Web 应用授权凭据

如需创建 OAuth 2.0 客户端 ID，请按照为 Web 应用授权凭据 下的步骤操作。

显示 Google Picker

桌面应用和移动应用的 Google Picker API 会在用户默认浏览器的新标签页中重定向到 Google Picker。用户授予访问权限并选择相关文件后，Google Picker 会通过回调网址返回到调用应用。

如需让 Google Picker API 在客户端页面中打开，请改用 Web 应用的 Google Picker API。如需了解详情，请参阅将 Google Picker 集成到 Web 应用中。

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

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

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

  2. 新浏览器标签页的网址接受所有标准 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 网址。

  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 概览。

将 Google Picker 与 Android 应用搭配使用

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

为移动应用授权凭据

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

如需在授权期间显示 Google Picker，请创建 AuthorizationRequest ，并在 AuthorizationRequest.ResourceParameter 对象上使用 PICKER_OAUTH_TRIGGER 资源参数。

构建 AuthorizationRequest 时：

  • 使用 drive.file 范围。

  • 将 setOptOutIncludingGrantedScopes 调用设为 true，以确保返回的令牌仅适用于 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 列表，用于过滤搜索结果。如果未设置，则视图中会显示所有文件。
  • PICKER_ALLOW_FOLDER_SELECTION：允许用户选择文件夹。

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

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