API Google Picker

Caixa de diálogo de seletor do Google.

O seletor do Google é uma caixa de diálogo "Arquivo aberto" para as informações armazenadas no Google Drive. O seletor do Google tem estes recursos:

  • Uma aparência parecida com a da IU do Google Drive.
  • Várias visualizações mostrando visualizações e miniaturas de arquivos do Drive.
  • Uma janela modal in-line para que os usuários nunca saiam do aplicativo principal.

A API Google Picker é uma API JavaScript que você pode usar nos seus apps da Web para permitir que os usuários abram ou façam upload de arquivos do Drive.

Requisitos de aplicativos

Os aplicativos que usam o seletor do Google precisam obedecer a todos os Termos de Serviço existentes. O mais importante é que você precisa se identificar corretamente nas solicitações.

Você também precisa ter um projeto do Google Cloud.

Configurar o 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, você precisa 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.

    Ativar a API

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 arquivos do Google Workspace compartilhados com 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:

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > Chave de API.
  3. A nova chave de API será exibida.
    • Clique em Copiar para copiar a chave de API a ser usada no código do app. A chave de API também pode ser encontrada na seção "Chaves de API" das credenciais do projeto.
    • Clique em Restringir chave para atualizar as configurações avançadas e limitar o uso da chave de API. Para mais detalhes, consulte Como aplicar restrições de chave de API.

Autorizar credenciais de um aplicativo da Web

Para se autenticar como usuário final e acessar os dados do usuário no seu app, crie um ou mais IDs do cliente OAuth 2.0. Um ID do cliente é usado para identificar um único app nos servidores OAuth do Google. Se o aplicativo for executado em várias plataformas, crie um ID do cliente separado para cada uma.

  1. No Console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. Clique em Tipo de aplicativo > Aplicativo da Web.
  4. No campo Nome, digite um nome para a credencial. Esse nome só é mostrado no console do Google Cloud.
  5. Adicione URIs autorizados relacionados ao seu app:
    • Apps do lado do cliente (JavaScript): em Origens JavaScript autorizadas, clique em Adicionar URI. Em seguida, digite um URI para usar nas solicitações do navegador. Identifica os domínios de que 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.
  6. Clique em Criar. A tela criada pelo cliente OAuth é exibida, mostrando seu novo ID e chave secreta do cliente.

    Anote o ID do cliente. Chaves secretas do cliente não são usadas em aplicativos da Web.

  7. Clique em OK. A credencial recém-criada aparece em IDs do cliente OAuth 2.0.
  8. Opcional: se você estiver criando credenciais como pré-requisito para um guia de início rápido do JavaScript, também precisará gerar uma chave de API.
Importante: seu aplicativo precisa enviar um token de acesso do OAuth 2.0 com visualizações que acessam dados particulares do usuário ao criar um objeto Picker. Para solicitar um token de acesso, consulte Usar o OAuth 2.0 para acessar as APIs do Google.

Exibir o seletor do Google

O restante deste guia aborda como carregar e exibir o seletor do Google em um app da Web. Para ver o exemplo completo, navegue até a amostra de código do seletor do Google.

Carregar a biblioteca do 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: '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>
    

A função onApiLoad() carrega as bibliotecas do seletor do Google. A função de callback onPickerApiLoad() é chamada depois que a biblioteca do seletor do Google é carregada.

Exibir o seletor do Google

A função createPicker() verifica se a API Google Picker termina de carregar e se um token OAuth é criado. Em seguida, 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('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: ''});
      }
    }
    

Para criar uma instância do seletor do Google, você precisa fornecer um View, um oauthToken, um developerKey e uma função de callback para sucesso (pickerCallback).

Um objeto Picker renderiza um View por vez. Especifique pelo menos uma visualização, seja 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 vão alternar de uma visualização para outra clicando em uma guia à esquerda. As guias podem ser agrupadas de maneira lógica com objetos ViewGroup.

Implementar o callback do seletor

Um callback do seletor pode ser usado para reagir às interações do usuário no seletor, como selecionar um arquivo ou pressionar "Cancelar".

    // 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 todas as ações que o usuário executa com o seletor do Google (google.picker.Response.ACTION). Se o usuário selecionar um item, a matriz google.picker.Response.DOCUMENTS também será preenchida. Neste exemplo, a google.picker.Document.URL é mostrada na página principal. Para detalhes sobre os campos de dados, consulte a referência JSON.

Filtrar tipos de arquivo específicos

Use uma ViewGroup para filtrar itens específicos. No exemplo a seguir, 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();
    

Ajustar a aparência do seletor do Google

Use a função PickerBuilder.enableFeature() para ajustar a aparência da janela do seletor do Google. Por exemplo, se você tiver apenas uma visualização, convém ocultar o painel de navegação para dar aos usuários mais espaço para ver itens. Veja um exemplo de um seletor de pesquisa de planilhas que demonstra 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 IU fornecendo a localidade para a instância PickerBuilder usando o método setLocale(locale). Veja a seguir um exemplo em francês:

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

Veja a lista de localidades compatíveis no momento:

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