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

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

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

功能

Google 选择器具有以下几项功能：

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

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

前提条件

使用 Google 选择器的应用必须遵守所有现有的服务条款。最重要的是，您必须在请求中正确表明自己的身份。

您还必须拥有 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 Cloud 控制台中，依次前往“菜单”图标 > Google Auth 平台 > 客户端。

    前往“客户”页面

  2. 点击创建客户端。
  3. 点击应用类型 > 为您的应用选择推荐的应用类型。
  4. 在名称字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
  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 选择器

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

  • Google 选择器界面身份验证界面

    通过触发 Google 选择器来验证您的应用。

  • “Google 登录”和“权限”对话框

    使用 Google 账号登录，并授予所请求的权限。

  • 选择器内的 Google 云端硬盘文件选择界面

    在 Google 选择器中浏览您的 Google 云端硬盘文件，然后选择所需的内容。

  • 文件插入确认界面，显示“插入”按钮

    确认您的选择，然后点按“插入”将文件添加到应用中。

将 Google 选择器集成到您的应用中

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

  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 文件选择器（可选）：

    参数 说明 状态
    prompt=consent 提示用户授予文件访问权限。 必填
    trigger_onepick=true 启用 Google 选择器。 必填
    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。

      选择适合您的应用类型和 OAuth 设置的 redirect_uri。Google 选择器不会施加任何其他限制。

  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 选择器

您还可以在 Android 移动应用中使用 Google 选择器。

为移动应用授权凭据

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

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

构建 AuthorizationRequest 时：

  • 使用 drive.file 范围。

  • 调用 setOptOutIncludingGrantedScopes 以 true，确保返回的令牌仅适用于 drive.file 范围，而不适用于任何之前授予的范围。

  • 将 AuthorizationRequest.Prompt 字段设置为 CONSENT，即使之前已征得用户同意，也会提示用户同意。

  • 您也可以选择使用位图“或”运算符 (|) 将 AuthorizationRequest.Prompt 字段设置为 SELECT_ACCOUNT，以便用户在显示意见征求提示之前选择账号。

调用 Google 选择器

与桌面应用类似，您可以使用多个可选参数来自定义 Google 选择器：

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

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

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