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 密钥是包含大小写字母、数字、
下划线和连字符,例如 AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe
。
此身份验证方法用于匿名访问
数据,例如使用“互联网上的任何人”共享的 Google Workspace 文件
“共享设置。有关详情,请参阅
使用 API 密钥进行身份验证。
如需创建 API 密钥,请执行以下操作:
- 在 Google Cloud 控制台中,点击“菜单”图标 > API 和服务 > 凭据。
- 点击创建凭据 > API 密钥。
- 此时将显示您的新 API 密钥。
- 点击“复制”图标 复制 API 密钥,以便在应用代码中使用。API 密钥也可以是 可在“API 密钥”中找到部分。
- 点击限制密钥以更新高级设置并限制密钥的使用 您的 API 密钥。如需了解详情,请参阅应用 API 密钥限制。
为 Web 应用授权凭据
如需对最终用户进行身份验证并访问应用中的用户数据,您需要执行以下操作: 创建一个或多个 OAuth 2.0 客户端 ID。客户端 ID 用于标识 连接到 Google OAuth 服务器。如果您的应用在多个平台上运行 您必须为每个平台创建一个单独的客户端 ID。
- 在 Google Cloud 控制台中,依次点击“菜单”图标 > API 和服务 > 凭据。
- 依次点击创建凭据 > OAuth 客户端 ID。
- 点击应用类型 > Web 应用。
- 在名称字段中,输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
- 添加与您的应用相关的已获授权的 URI:
<ph type="x-smartling-placeholder">
- </ph>
- 客户端应用 (JavaScript) - 在已获授权的 JavaScript 来源下,点击添加 URI。然后,输入要用于浏览器请求的 URI。这用于标识您的应用可以从哪些网域向 OAuth 2.0 服务器发送 API 请求。
- 服务器端应用(Java、Python 等) - 在已获授权的重定向 URI 下,点击添加 URI。然后,输入 OAuth 2.0 服务器可向其发送响应的端点 URI。
- 点击创建。系统会显示“OAuth 客户端创建”屏幕,其中显示了您的新客户端 ID 和客户端密钥。
记下客户端 ID。客户端密钥不用于 Web 应用。
- 点击 OK。新创建的凭据会显示在 OAuth 2.0 客户端 ID 下。
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 |