Google Picker API

Google 选择器对话框。

Google Picker API 是一种 JavaScript API,您可以在自己的 Web 应用中使用该 API 来让用户选择或 上传 Google 云端硬盘文件。用户可以授权您的应用访问其 云端硬盘数据,让用户能以安全且授权的方式与其文件进行交互。

Google 选择器充当“文件打开”显示云端硬盘中存储的信息的对话框 并具有以下特点:

  • 外观和风格与 Google 云端硬盘界面类似。
  • 多个视图,显示了云端硬盘文件的预览和缩略图。
  • 内嵌模态窗口,用户绝不会离开主应用。

请注意,Google 选择器不允许用户整理、移动或复制同一文件夹中的文件 到另一个位置。为此,您可以使用 Google Drive API 或云端硬盘界面中

应用程序要求

使用 Google 选择器的应用必须遵守所有现有 服务条款。最重要的是,您必须正确识别 。

您还必须有一个 Google Cloud 项目

设置环境

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

启用 API

在使用 Google API 之前,您需要先在 Google Cloud 项目中启用这些 API。 您可以在单个 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 密钥限制

为 Web 应用授权凭据

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

  1. 在 Google Cloud 控制台中,依次点击“菜单”图标 > API 和服务 > 凭据

    进入“凭据”页面

  2. 依次点击创建凭据 > OAuth 客户端 ID
  3. 点击应用类型 > Web 应用
  4. 名称字段中,输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
  5. 添加与您的应用相关的已获授权的 URI: <ph type="x-smartling-placeholder">
      </ph>
    • 客户端应用 (JavaScript) - 在已获授权的 JavaScript 来源下,点击添加 URI。然后,输入要用于浏览器请求的 URI。这用于标识您的应用可以从哪些网域向 OAuth 2.0 服务器发送 API 请求。
    • 服务器端应用(Java、Python 等) - 在已获授权的重定向 URI 下,点击添加 URI。然后,输入 OAuth 2.0 服务器可向其发送响应的端点 URI。
  6. 点击创建。系统会显示“OAuth 客户端创建”屏幕,其中显示了您的新客户端 ID 和客户端密钥。

    记下客户端 ID。客户端密钥不用于 Web 应用。

  7. 点击 OK。新创建的凭据会显示在 OAuth 2.0 客户端 ID 下。
重要提示:您的应用必须发送具有访问权限的视图的 OAuth 2.0 访问令牌 私有用户数据。Picker要请求访问令牌,请参阅使用 OAuth 2.0 访问 Google API

显示 Google 选择器

本指南的其余部分介绍了如何从 Web 应用加载和显示 Google 选择器。接收者 查看完整示例,请参阅 Google 选择器代码示例

加载 Google 选择器库

如需加载 Google 选择器库,请调用 gapi.load(),并提供库名称和 要在成功加载后调用的回调函数:

    <script>
      let tokenClient;
      let accessToken = null;
      let pickerInited = false;
      let gisInited = false;

      // Use the API Loader script to load google.picker
      function onApiLoad() {
        gapi.load('picker', onPickerApiLoad);
      }

      function onPickerApiLoad() {
        pickerInited = true;
      }

      function gisLoaded() {
        // TODO(developer): Replace with your client ID and required scopes.
        tokenClient = google.accounts.oauth2.initTokenClient({
          client_id: 'CLIENT_ID',
          scope: 'SCOPES',
          callback: '', // defined later
        });
        gisInited = true;
    }
    </script>
    <!-- Load the Google API Loader script. -->
    <script async defer src="https://apis.google.com/js/api.js" onload="onApiLoad()"></script>
    <script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>
    

替换以下内容:

  • CLIENT_ID:您的 Web 应用的客户端 ID。
  • SCOPES:您需要请求访问 Google API 的一个或多个 OAuth 2.0 范围,具体取决于您所需的访问权限级别。 如需了解详情,请参阅 Google API 的 OAuth 2.0 范围

google.accounts.oauth2 JavaScript 库可帮助您提示用户同意,并获取处理用户数据的访问令牌。 initTokenClient() 方法会使用您的 Web 应用的客户端 ID 初始化新的令牌客户端。如需了解详情,请参阅使用令牌模型

onApiLoad() 函数用于加载 Google 选择器库。通过 在 Google 选择器库之后调用 onPickerApiLoad() 回调函数 成功加载。

显示 Google 选择器

createPicker() 函数会检查以确保 Google Picker API 完成加载 并创建一个 OAuth 令牌使用 setAppId 字段来设置 允许该应用访问用户文件的云端硬盘应用 ID。该函数 创建 Google 选择器的实例并显示该实例:

    // Create and render a Google Picker object for selecting from Drive.
    function createPicker() {
      const showPicker = () => {
        // TODO(developer): Replace with your API key
        const picker = new google.picker.PickerBuilder()
            .addView(google.picker.ViewId.DOCS)
            .setOAuthToken(accessToken)
            .setDeveloperKey('API_KEY')
            .setCallback(pickerCallback)
            .setAppId(APP_ID)
            .build();
        picker.setVisible(true);
      }

      // Request an access token.
      tokenClient.callback = async (response) => {
        if (response.error !== undefined) {
          throw (response);
        }
        accessToken = response.access_token;
        showPicker();
      };

      if (accessToken === null) {
        // Prompt the user to select a Google Account and ask for consent to share their data
        // when establishing a new session.
        tokenClient.requestAccessToken({prompt: 'consent'});
      } else {
        // Skip display of account chooser and consent dialog for an existing session.
        tokenClient.requestAccessToken({prompt: ''});
      }
    }
    

如需创建 Google 选择器实例,您必须创建一个 Picker 对象(使用 PickerBuilder)。通过 PickerBuilder 接受 View、OAuth 令牌、 开发者密钥,以及一个在成功时调用的回调函数 (pickerCallback)。

Picker 对象一次渲染一个 View。请至少指定一个数据视图 ViewId (google.​picker.​ViewId.*) 或 类型 (google.​picker.​*View)。按类型指定视图 控制视图的渲染方式。

如果向 Google 选择器添加了多个视图,用户可以通过执行以下操作来切换视图: 点击左侧的某个标签标签页可以使用 ViewGroup 对象进行逻辑分组。

实现 Google 选择器回调

Google 选择器回调可用于回应 Google 选择器中的用户互动,例如 选择某个文件,或按“取消”。Response 对象用于传达有关用户所做选择的信息。

    // A simple callback implementation.
    function pickerCallback(data) {
      let url = 'nothing';
      if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
        let doc = data[google.picker.Response.DOCUMENTS][0];
        url = doc[google.picker.Document.URL];
      }
      let message = `You picked: ${url}`;
      document.getElementById('result').innerText = message;
    }
    

该回调会接收一个 JSON 编码的 data 对象。此对象包含一个 Action 用户使用 Google 选择器 (google.picker.Response.ACTION) 执行的操作。 如果用户选择 Document 项, google.picker.Response.DOCUMENTS 数组也 填充。在此示例中,google.picker.Document.URL 显示在主页上。 如需详细了解数据字段,请参阅 JSON 参考

过滤特定文件类型

使用 ViewGroup 过滤特定项。 以下代码示例展示了“Google 云端硬盘”子视图只显示文档和演示文稿。

    let picker = new google.picker.PickerBuilder()
        .addViewGroup(
          new google.picker.ViewGroup(google.picker.ViewId.DOCS)
              .addView(google.picker.ViewId.DOCUMENTS)
              .addView(google.picker.ViewId.PRESENTATIONS))
        .setOAuthToken(oauthToken)
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    
如需查看有效视图类型的列表,请参阅 ViewId

调整 Google 选择器的外观

您可以使用 Feature 对象来开启或关闭各种视图的功能。 要微调 Google 选择器窗口的外观,请使用 PickerBuilder.enableFeature()PickerBuilder.disableFeature() 函数。例如,如果您只有一个视图,则可能需要将 导航窗格 (Feature.NAV_HIDDEN),为用户提供更多空间来查看各项。

以下代码示例展示了使用此功能的电子表格搜索选择器的示例:

     let picker = new google.picker.PickerBuilder()
         .addView(google.picker.ViewId.SPREADSHEETS)
         .enableFeature(google.picker.Feature.NAV_HIDDEN)
         .setDeveloperKey(developerKey)
         .setCallback(pickerCallback)
         .build();
     

以其他语言呈现 Google 选择器

通过向 PickerBuilder 提供语言区域来指定界面语言 (使用 setLocale(locale) 方法)。

以下代码示例展示了如何将语言区域设置为法语:

    let picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.IMAGE_SEARCH)
        .setLocale('fr')
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

以下是目前支持的语言区域列表:

af
am
ar
bg
bn
ca
cs
da
de
el
en
en-GB
es
es-419
et
eu
fa
fi
fil
fr
fr-CA
gl
gu
hi
hr
hu
id
is
it
iw
ja
kn
ko
lt
lv
ml
mr
ms
nl
no
pl
pt-BR
pt-PT
ro
ru
sk
sl
sr
sv
sw
ta
te
th
tr
uk
ur
vi
zh-CN
zh-HK
zh-TW
zu