A API Google Picker é uma API JavaScript que pode ser usada nos seus apps da Web para permitir que os usuários selecionem ou façam upload de arquivos do Google Drive. Os usuários podem permitir que seus apps acessem os dados do Drive, oferecendo uma maneira segura e autorizada de interagir com os arquivos.
O seletor do Google funciona como uma caixa de diálogo "Arquivo aberto" para informações armazenadas no Drive e tem os seguintes recursos:
- É semelhante à interface do Google Drive.
- Várias visualizações com imagens e miniaturas dos arquivos do Drive.
- Uma janela inline e modal para que os usuários nunca saiam do aplicativo principal.
Observe que o seletor do Google não permite que os usuários organizem, movam ou copiem arquivos de uma pasta para outra. Para fazer isso, use a API Google Drive ou a IU do Drive.
Requisitos de aplicativos
Os aplicativos que usam o seletor do Google precisam obedecer a todos os Termos de Serviço existentes. Acima de tudo, é preciso se identificar corretamente nas solicitações.
Você também precisa ter um projeto do Google Cloud.Configure seu ambiente
Para começar a usar a API Google Picker, você precisa configurar seu ambiente.
Ativar a API
Antes de usar as APIs do Google, é preciso ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.
No console do Google Cloud, ative a API Google Picker.
crie uma chave de API
Uma chave de API é uma string longa que contém letras maiúsculas e minúsculas, números, sublinhados e hifens, como AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe
.
Esse método de autenticação é usado para acessar anonimamente dados disponíveis
publicamente, como os arquivos do Google Workspace compartilhados usando a configuração de compartilhamento "Qualquer pessoa na Internet
com este link". Para mais detalhes, consulte Autenticar usando chaves de API.
Para criar uma chave de API, siga estas etapas:
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > Chave de API.
- Sua nova chave de API será exibida.
- Clique em Copiar para copiar sua chave de API e usá-la no código do app. A chave de API também pode ser encontrada na seção "Chaves de API" das credenciais do seu projeto.
- Clique em Restringir chave para atualizar as configurações avançadas e limitar o uso da sua chave de API. Para mais detalhes, consulte Como aplicar restrições à chave de API.
Autorizar credenciais para um aplicativo da Web
Para autenticar os usuários finais e acessar os dados do usuário no seu app, você precisa criar um ou mais IDs do cliente OAuth 2.0. Um ID do cliente é usado para identificar um único app nos servidores OAuth do Google. Caso seu app seja executado em várias plataformas, você precisará criar um ID do cliente separado para cada uma delas.
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > ID do cliente OAuth.
- Clique em Tipo de aplicativo > Aplicativo da Web.
- No campo Nome, digite um nome para a credencial. Ele só aparece no console do Google Cloud.
- Adicione URIs autorizados relacionados ao seu app:
- Apps do lado do cliente (JavaScript): em Origens JavaScript autorizadas, clique em Adicionar URI. Em seguida, insira um URI a ser usado para solicitações do navegador. Isso identifica os domínios a partir dos quais seu aplicativo pode enviar solicitações de API para o servidor OAuth 2.0.
- Apps do lado do servidor (Java, Python e outros): em URIs de redirecionamento autorizados, clique em Adicionar URI. Em seguida, insira um URI de endpoint para o qual o servidor OAuth 2.0 possa enviar respostas.
- Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
Anote o ID do cliente. As chaves secretas do cliente não são usadas para aplicativos da Web.
- Clique em OK. A credencial recém-criada aparece em IDs do cliente OAuth 2.0.
Picker
. Para solicitar um token de acesso, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.
Mostrar o seletor do Google
O restante deste guia explica como carregar e mostrar o seletor do Google em um app da Web. Para ver o exemplo completo, acesse o exemplo de código do seletor do Google (link em inglês).Carregar a biblioteca de seletor do Google
Para carregar a biblioteca do seletor do Google, chame gapi.load()
com o nome da biblioteca e uma função de callback para invocar após um carregamento bem-sucedido:
<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>
Substitua:
CLIENT_ID
: ID do cliente do seu app da Web.SCOPES
: um ou mais escopos do OAuth 2.0 que você precisa solicitar para acessar as APIs do Google, dependendo do nível de acesso necessário. Para obter mais informações, consulte Escopos do OAuth 2.0 para APIs do Google.
A biblioteca JavaScript google.accounts.oauth2
ajuda a solicitar o consentimento do usuário e a receber um token de acesso para trabalhar com dados do usuário.
O método initTokenClient()
inicializa um novo cliente de token com o ID do cliente do seu app da Web. Para mais informações, consulte Como usar o modelo de token.
A função onApiLoad()
carrega as bibliotecas de seletor do Google. A função de callback onPickerApiLoad()
é chamada depois que a biblioteca de seletor do Google é carregada.
Mostrar o seletor do Google
A função createPicker()
verifica se a API Google Picker termina de carregar e se um token OAuth foi criado. Use o campo
setAppId
para definir o
ID do app Drive e permitir que ele acesse os arquivos do usuário. Essa função cria uma instância do seletor do Google e a exibe:
// 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: ''}); } }
Para criar uma instância do seletor do Google, crie um objeto Picker
usando o PickerBuilder
. O
PickerBuilder
usa um View
, um token OAuth, uma
chave de desenvolvedor e uma função de callback para chamar em caso de sucesso (pickerCallback
).
O objeto Picker
renderiza um View
por vez. Especifique pelo menos uma visualização
por ViewId
(google.picker.ViewId.*
) ou criando uma instância de um
tipo (google.picker.*View
). Especifique a visualização por tipo para ter mais
controle sobre como ela é renderizada.
Se mais de uma visualização for adicionada ao seletor do Google, os usuários poderão alternar de uma visualização para outra
clicando em uma guia à esquerda. As guias podem ser agrupadas logicamente com objetos ViewGroup
.
Implementar o callback do seletor do Google
Um callback do seletor do Google pode ser usado para reagir às interações do usuário, como
selecionar um arquivo ou pressionar "Cancelar". O objeto Response
transmite informações sobre as seleções do usuário.
// 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; }
O callback recebe um objeto data
codificado em JSON. Esse objeto contém uma Action
que o usuário realiza com o seletor do Google (google.picker.Response.ACTION
). Se o usuário selecionar um item Document
, a matriz google.picker.Response.DOCUMENTS
também será preenchida. Neste exemplo, o google.picker.Document.URL
é mostrado na página principal.
Para detalhes sobre os campos de dados, consulte a Referência JSON.
Filtrar tipos de arquivo específicos
Use um ViewGroup
para filtrar itens específicos.
O exemplo de código a seguir mostra como a subvisualização "Google Drive" mostra apenas documentos e apresentações.
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();Para conferir uma lista de tipos de visualização válidos, consulte
ViewId
.
Ajustar a aparência do seletor do Google
Você pode usar o objeto Feature
para ativar ou desativar recursos para várias visualizações.
Para ajustar a aparência da janela de seletor do Google, use a função PickerBuilder.enableFeature()
ou PickerBuilder.disableFeature()
. Por exemplo, caso você tenha apenas uma visualização, oculte o
painel de navegação (Feature.NAV_HIDDEN
) para dar aos usuários mais espaço para mostrar itens.
O exemplo de código a seguir mostra um exemplo de seletor de pesquisa de uma planilha usando esse recurso:
let picker = new google.picker.PickerBuilder() .addView(google.picker.ViewId.SPREADSHEETS) .enableFeature(google.picker.Feature.NAV_HIDDEN) .setDeveloperKey(developerKey) .setCallback(pickerCallback) .build();
Renderizar o seletor do Google em outros idiomas
Especifique o idioma da interface fornecendo a localidade para a instância PickerBuilder
usando o método setLocale(locale)
.
O exemplo de código a seguir mostra como definir a localidade para o francês:
let picker = new google.picker.PickerBuilder() .addView(google.picker.ViewId.IMAGE_SEARCH) .setLocale('fr') .setDeveloperKey(developerKey) .setCallback(pickerCallback) .build();
Veja a seguir a lista de localidades atualmente compatíveis:
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 |