Google Picker API

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Google 选择器对话框。

Google 选择器是存储于 Google 云端硬盘中的信息的“文件打开”对话框。Google 选择器具有以下功能:

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

Google Picker API 是一种 JavaScript API,您可以在 Web 应用中使用该 API 来允许用户打开或上传云端硬盘文件。

应用程序要求

使用 Google 选择器的应用必须遵循所有现有服务条款。最重要的是,您必须在请求中正确地标识自己。

您还必须有一个 Google Cloud 项目

设置您的环境

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

启用 API

在使用 Google API 之前,您需要先在 Google Cloud 项目中启用它们。您可以在单个 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 密钥。
    • 点击“Copy” 以复制您的 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:
    • 客户端应用 (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 下。
  8. 可选:如果您要创建凭据作为 JavaScript 快速入门的前提条件,则还必须生成 API 密钥
重要提示:创建 Picker 对象时,您的应用必须发送包含用户私人数据的视图的 OAuth 2.0 访问令牌。要请求访问令牌,请参阅使用 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: 'YOUR_CLIENT_ID',
          scope: 'YOUR_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>
    

onApiLoad() 函数会加载 Google 选择器库。Google 选择器库成功加载后,系统会调用 onPickerApiLoad() 回调函数。

显示 Google 选择器

createPicker() 函数会检查 Google Picker API 的加载完毕以及 OAuth 令牌的创建。然后,此函数会创建 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('YOUR_API_KEY')
            .setCallback(pickerCallback)
            .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 选择器实例,您必须提供 ViewoauthTokendeveloperKey 以及成功调用时调用的回调函数 (pickerCallback)。

Picker 对象一次渲染一个 View。通过 ViewId (google.​picker.​ViewId.*) 或创建某个类型的实例 (google.​picker.​*View) 指定至少一个视图。按类型指定视图可进一步控制视图的渲染方式。

如果向 Google 选择器添加了多个视图,用户只需点击左侧的标签页,即可从一个视图切换到另一个视图。标签页可以使用 ViewGroup 对象进行逻辑分组。

实现选择器回调

选择器回调可用于响应 Google 选择器中的用户互动(例如选择文件或按“取消”)。

    // 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 对象。此对象包含用户使用 Google 选择器 (google.picker.Response.ACTION) 执行的任何操作。如果用户选择一项,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();
    

调整 Google 选择器的外观

使用 PickerBuilder.enableFeature() 函数微调 Google 选择器窗口的外观。例如,如果您只有一个视图,则可能希望隐藏导航窗格,为用户提供更多空间来查看列表项。以下是展示此功能的电子表格搜索选择器示例:

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

以其他语言呈现 Google 选择器

使用 setLocale(locale) 方法为 PickerBuilder 实例提供语言区域,以指定界面语言。以下是法语示例:

    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