API Google Picker

A API Google Picker é uma API JavaScript que pode ser usada nos seus apps da Web para permitir que os usuários selecionem ou fazer o upload de arquivos do Google Drive. Os usuários podem conceder permissão para que seus apps acessem os dados do Drive, oferecendo uma forma segura e autorizada de interagir com os arquivos.

O Seletor do Google funciona como um "Arquivo aberto" caixa de diálogo para informações armazenadas no Drive e tem estes recursos:

• Aparência semelhante à interface do Google Drive.
• Várias visualizações mostrando visualizações e imagens em miniatura dos arquivos do Drive.
• Uma janela modal inline para que os usuários nunca saiam do aplicativo principal.

O Seletor do Google não permite que os usuários organizem, movam ou copiem arquivos de uma pasta ao outro. Para isso, você pode usar a API Google Drive ou na interface do Google Drive.

Requisitos de aplicativos

Os aplicativos que usam o Seletor do Google devem obedecer a todas as políticas Termos de Serviço. Mais importante ainda, você deve identificar corretamente nas suas solicitações.

Configurar o ambiente

Para começar a usar a API Google Picker, configure 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

Criar 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, de forma anônima, como arquivos do Google Workspace compartilhados usando a opção com este link" configuração de compartilhamento. Para mais detalhes, consulte Faça a autenticação usando chaves de API.

Para criar uma chave de API, siga estas etapas:

1. No console do Google Cloud, acesse o menu menu > APIs e Serviços > Credenciais.

   Ir para Credenciais

2. Clique em Criar credenciais >. Chave de API.
3. Sua nova chave de API será exibida.
   • Clique em Copiar content_copy para copiar a chave de API e usá-la no código do app. A chave de API também pode ser nas "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 de chave de API.

Autorizar credenciais para um aplicativo da Web

Para autenticar usuários finais e acessar os dados deles 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, crie um ID do cliente separado para cada plataforma.

1. No console do Google Cloud, acesse Menu 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 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 dos quais seu aplicativo pode enviar solicitações de API para o servidor OAuth 2.0.
   • Apps do lado do servidor (Java, Python e mais): em URIs de redirecionamento autorizados, clique em Adicionar URI. Em seguida, insira um URI de endpoint para o qual o servidor OAuth 2.0 pode enviar respostas.
6. Clique em Criar. A tela criada pelo cliente OAuth será exibida, mostrando o novo ID e a chave secreta do cliente.

   Anote o ID do cliente. As chaves secretas não são usadas para aplicativos da Web.

7. Clique em OK. A credencial recém-criada aparece em IDs do cliente do OAuth 2.0.

Mostrar o Seletor do Google

Carregar a biblioteca do Google Picker

Para carregar a biblioteca do Google Picker, chame gapi.load() com o nome da biblioteca e um função de callback a ser invocada 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 mais informações, consulte Escopos do OAuth 2.0 para APIs do Google (em inglês).

A biblioteca JavaScript google.accounts.oauth2 ajuda você a solicitar o consentimento do usuário e receber um token de acesso para trabalhar com os 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 do Google Picker. A A função de callback onPickerApiLoad() é chamada após a biblioteca do Google Picker. carrega com sucesso.

Mostrar o Seletor do Google

A função createPicker() verifica se a API Google Picker foi carregada e a criação de um token OAuth. Use o setAppId para definir ID do app do Drive para permitir que o app acesse os arquivos do usuário. Em seguida, essa função cria uma instância do Google Picker 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 Google Picker, crie um objeto Picker objeto usando o PickerBuilder. A PickerBuilder recebe um View, um token OAuth, um chave de desenvolvedor e uma função de callback para chamar se a operação for bem-sucedida (pickerCallback).

O objeto Picker renderiza uma 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 controle sobre como a visualização é renderizada.

Se mais de uma vista for adicionada ao seletor do Google, os usuários poderão alternar entre as visualizações clicando em uma guia à esquerda. As guias podem ser agrupadas de maneira lógica com objetos ViewGroup.

Implementar o callback do seletor do Google

Um callback do Google Picker pode ser usado para reagir às interações do usuário no Google Picker, como selecionando um arquivo ou pressionando Cancelar. O 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 um 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 é preenchida. Neste exemplo, o google.picker.Document.URL é mostrado na página principal. Para detalhes sobre campos de dados, consulte a Referência JSON.

Filtrar tipos de arquivo específicos

Use um ViewGroup como uma forma de filtrar itens específicos. O exemplo de código a seguir mostra como 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 Google Picker

Você pode usar o objeto Feature para ativar ou desativar recursos para várias visualizações. Para ajustar a aparência da janela do Seletor do Google, use o função PickerBuilder.enableFeature() ou PickerBuilder.disableFeature(). Por exemplo, se você tiver apenas uma visualização, convém ocultar painel de navegação (Feature.NAV_HIDDEN) para dar aos usuários mais espaço para ver os 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 ao PickerBuilder usando o método setLocale(locale).

O exemplo de código a seguir mostra como definir a localidade para 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 aceitas atualmente: