Visão geral dos apps para computador e dispositivos móveis

A API Google Picker é uma maneira de permitir que os usuários selecionem ou façam upload de arquivos do Google Drive. Os usuários podem conceder permissão aos apps para computador e dispositivos móveis para acessar os dados do Drive, oferecendo uma maneira segura e autorizada de interagir com os arquivos.

O Google Picker funciona como uma caixa de diálogo "Abrir arquivo" para arquivos armazenados no Drive e tem vários recursos:

Aparência semelhante à da interface do Google Drive UI.
Várias visualizações mostrando prévias e miniaturas de arquivos do Drive.
Um redirecionamento para o Google Picker em uma nova guia no navegador padrão do usuário.

O Google Picker não permite que os usuários organizem, movam ou copiem arquivos de uma pasta para outra. Para gerenciar arquivos, use a API Google Drive ou a interface do Drive.

Pré-requisitos

Os apps que usam o Google Picker precisam obedecer a todos os Termos de Serviço atuais. O mais importante é que você se identifique corretamente nas solicitações.

Você também precisa ter um projeto na nuvem.

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, ative-as em um projeto na nuvem 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 dados disponíveis publicamente de forma anônima, como arquivos do Google Workspace compartilhados usando a configuração de compartilhamento "Qualquer pessoa na Internet com este link". Para mais detalhes, consulte Gerenciar chaves de API.

Para criar uma chave de API, siga estas etapas:

No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
Ir para Credenciais
Clique em Criar credenciais > Chave de API.
Sua nova chave de API será exibida.
- Clique em Copy para copiar a chave de API e usar no código do app. A chave de API também pode ser encontrada na seção "Chaves de API" das credenciais do projeto.
- Para evitar o uso não autorizado, recomendamos restringir os locais e as APIs em que a chave de API pode ser usada. Para mais detalhes, consulte Adicionar restrições de API.

Autorizar credenciais para um app para computador

Para autenticar usuários finais e acessar dados do usuário no 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 app for executado em várias plataformas, crie um ID do cliente separado para cada plataforma.

No console de APIs do Google, acesse Menu > Plataforma de autenticação do Google > Clientes.
Acessar clientes
Clique em Criar cliente.
Clique em Tipo de aplicativo > App para computador.
No campo Nome, digite um nome para a credencial. Esse nome só é mostrado no console de APIs do Google.
Clique em Criar.
A credencial recém-criada aparece em "IDs do cliente OAuth 2.0".

Para que os apps recebam autorização para arquivos concedidos anteriormente, siga estas etapas:

Você precisa receber um token OAuth 2.0 com o escopo drive.file, drive ou drive.readonly usando estas instruções: Como usar o OAuth 2.0 para acessar as APIs do Google. Para mais informações sobre escopos, consulte Escolher escopos da API Google Drive.
Transmita o token OAuth 2.0 para a API Drive para ler e modificar arquivos em que o usuário concedeu acesso anteriormente.

Mostrar o Google Picker

A API Google Picker para apps para computador redireciona para o Google Picker em uma nova guia no navegador padrão do usuário. Depois que o usuário concede acesso e escolhe os arquivos relevantes, o Google Picker retorna ao app de chamada pelo URL de callback. Para que a API Google Picker seja aberta em uma página do cliente, use a API Google Picker para apps da Web. Para mais informações, consulte Visão geral dos apps da Web.

Para permitir que os usuários concedam acesso a outros arquivos ou escolham arquivos para uso no fluxo de apps para computador, siga estas etapas:

Solicite acesso ao escopo drive.file para abrir a página de acesso do OAuth 2.0 em uma nova guia do navegador usando estas instruções: Como usar o OAuth 2.0 para acessar as APIs do Google. Para mais informações sobre escopos, consulte Escolher escopos da API Google Drive.

Somente o escopo drive.file é permitido para apps para computador, e ele não pode ser combinado com nenhum outro escopo.

O URL da nova guia do navegador aceita todos os parâmetros de string de consulta OAuth padrão.

Anexe os parâmetros de URL prompt e trigger_onepick à solicitação de URL de autorização do OAuth 2.0:

Parâmetro	Descrição	Status
`prompt=consent`	Solicitar acesso ao arquivo.	Obrigatório
`trigger_onepick=true`	Ativar o Google Picker.	Obrigatório

Também é possível personalizar o Google Picker com vários parâmetros opcionais:

Parâmetro	Descrição	Status
`allow_multiple=true`	Se verdadeiro, permite que o usuário selecione vários arquivos.	Opcional
`mimetypes=MIMETYPES`	Uma lista separada por vírgulas de tipos MIME para filtrar os resultados da pesquisa. Se não estiver definido, os arquivos de todos os tipos MIME serão mostrados na visualização.	Opcional
`file_ids=FILE_IDS`	Uma lista separada por vírgulas de IDs de arquivo para filtrar os resultados da pesquisa. Se não estiver definido, todos os arquivos serão mostrados na visualização.	Opcional
`allow_folder_selection=true`	Se verdadeiro, permite que o usuário também selecione pastas.	Opcional

O exemplo a seguir mostra uma solicitação de URL de autorização do OAuth 2.0:

https://accounts.google.com/o/oauth2/v2/auth? \
client_id=CLIENT_ID \
&scope=https://www.googleapis.com/auth/drive.file \
&redirect_uri=REDIRECT_URI \
&response_type=code \
&access_type=offline \
&prompt=consent \
&trigger_onepick=true

Substitua:

CLIENT_ID: o ID do cliente do app para computador.
REDIRECT_URI: para onde o servidor de autorização redireciona o navegador do usuário após a autenticação. Por exemplo, https://www.cymbalgroup.com/oauth2callback.

O redirect_uri especificado precisa ser um URL HTTPS público. Se você quiser usar um protocolo personalizado ou um URL localhost para o redirect_uri, use um URL HTTPS público que redirecione para o protocolo personalizado ou URL localhost.

Depois que o usuário concede acesso e escolhe os arquivos relevantes, o OAuth redireciona para o redirect_uri especificado na solicitação com os seguintes parâmetros de URL anexados:
- picked_file_ids: se o usuário concedeu acesso e escolheu arquivos, uma lista separada por vírgulas de IDs de arquivo selecionados.
- code: o token de acesso ou o código de acesso com base no response_type parâmetro definido na solicitação. Esse parâmetro inclui um novo código de autorização.
- scope: os escopos incluídos na solicitação.
- error: se o usuário cancelou a solicitação no fluxo de consentimento, um erro será mostrado.
O exemplo a seguir mostra uma resposta de URL de autorização do OAuth 2.0:
```
https://REDIRECT_URI?picked_file_ids=PICKED_FILE_IDS&code=CODE&scope=SCOPES
```
Os apps precisam trocar o código de autorização da etapa 3 por um novo token OAuth 2.0. Para mais informações, consulte Trocar o código de autorização por tokens de atualização e acesso.
Os apps podem usar os IDs de arquivo do parâmetro de URL na etapa 3 e o token OAuth 2.0 recebido na etapa 4 para chamar a API Drive. Para mais informações, consulte Visão geral da API Google Drive.

Usar o Google Picker com o Android

Também é possível usar o Google Picker no app para dispositivos móveis Android.

Autorizar credenciais para um app para dispositivos móveis

Para usar o Google Picker no app Android, autorize os usuários usando o OAuth 2.0, semelhante aos apps para computador. Para detalhes sobre a autenticação do Android, consulte Autorizar o acesso aos dados do usuário do Google.

Para mostrar o Google Picker durante a autorização, crie um AuthorizationRequest e use PICKER_OAUTH_TRIGGER com AuthorizationRequest.ResourceParameter.

Ao criar a AuthorizationRequest:

Use o escopo https://www.googleapis.com/auth/drive.file.
Chame setOptOutIncludingGrantedScopes(true) para garantir que o token retornado seja apenas para o https://www.googleapis.com/auth/drive.file escopo e não para nenhum escopo concedido anteriormente.
Defina o campo AuthorizationRequest.Prompt como CONSENT para solicitar o consentimento do usuário, mesmo que ele tenha sido concedido antes. Esse campo só é aplicável a solicitações que incluem parâmetros de recursos.
Opcionalmente, use o operador de bitmap "OR" (|) para definir também o AuthorizationRequest.Prompt campo como SELECT_ACCOUNT para permitir que o usuário selecione uma conta antes que a solicitação de consentimento seja mostrada.

Chamar o Google Picker

Semelhante aos apps para computador, é possível personalizar o Google Picker com vários parâmetros opcionais:

PICKER_ALLOW_MULTIPLE: permite que os usuários selecionem vários arquivos.
PICKER_MIMETYPES: retorna uma lista separada por vírgulas de tipos MIME para filtrar os resultados da pesquisa. Se não estiver definido, os arquivos de todos os tipos MIME serão mostrados na visualização.
PICKER_FILE_IDS: retorna uma lista separada por vírgulas de IDs de arquivo para filtrar os resultados da pesquisa. Se não estiver definido, todos os arquivos serão mostrados na visualização.

Para mais informações sobre os parâmetros opcionais em apps para computador, consulte Mostrar o Google Picker.

Depois que o usuário concede acesso e escolhe os arquivos relevantes, o getTokenResponseParams objeto do AuthorizationResult recurso é retornado. Se o usuário concedeu acesso, esse objeto contém o valor picked_file_ids, que é uma lista separada por vírgulas de IDs de arquivo selecionados.

Escolher escopos da API Google Drive