Configurar uma integração com a IU do Drive

Para exibir seu app no Google Drive quando um usuário criar ou abrir um arquivo, configure uma integração com a interface do usuário (IU) do Drive. A configuração também é necessária para listar seu app no Google Workspace Marketplace.

Ativar a API Drive

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.

Para começar a integração com a IU do Google Drive, ative a API Drive. Assim, você tem acesso à API e aos recursos de integração da IU.

  • No console do Google Cloud, ative a API Google Drive.

    Ativar a API

Configurar a integração com a IU do Drive

  1. No Console de APIs do Google, acesse Menu > APIs e serviços > APIs e serviços ativados.

    Acessar APIs e serviços ativados

  2. Na parte inferior do painel de APIs e serviços, clique em API Google Drive. A página de configuração da API Google Drive será exibida.
  3. Selecione a guia Integração com a IU do Drive.
  4. (Opcional) Digite um nome no campo Nome do aplicativo. O nome do aplicativo é exibido para os usuários na guia "Gerenciar aplicativos" nas configurações do Google Drive.
  5. (Opcional) Insira uma descrição curta de uma linha no campo Descrição curta. A descrição breve é exibida aos usuários na guia "Gerenciar apps" nas configurações do Drive.
  6. (Opcional) Insira uma descrição completa no campo Descrição longa.

  7. Faça upload de um ou mais ícones de aplicativo para exibir na lista de apps do Drive conectados de um usuário e no menu de contexto "Abrir com". Os ícones precisam estar no formato PNG com um plano de fundo transparente. Os ícones podem levar até 24 horas para aparecer no Drive.

  8. Para usar o item de menu "Abrir com" da IU do Drive, insira o URL do seu app no campo Abrir URL. Esse URL é usado pelo menu de contexto "Abrir com".

    • Esse URL precisa conter um nome de domínio totalmente qualificado. localhost não funciona.
    • Esse URL deve ser acessível aos usuários pretendidos do seu aplicativo. Se você tiver várias versões do aplicativo, como uma para lançamento público e outra para lançamento restrito para usuários selecionados, cada uma vai usar um URL exclusivo. Em seguida, você pode criar configurações de app diferentes para cada versão.
    • Verifique a propriedade deste URL antes de listar seu app no Google Workspace Marketplace.
    • Por padrão, um parâmetro de consulta state é anexado a esse URL para transmitir dados da IU do Drive ao seu app. Para informações sobre o conteúdo do parâmetro state, consulte O parâmetro state.

  9. (Opcional) Digite tipos MIME e extensões de arquivo padrão nos campos Tipos MIME padrão e Extensões de arquivo padrão. Os tipos MIME e as extensões de arquivo padrão representam arquivos que o app foi criado exclusivamente para abrir. Por exemplo, o app pode abrir um formato integrado para criar camadas e editar imagens. Inclua somente tipos de mídia padrão e verifique se não há erros de digitação ou ortografia. Caso seu app só abra atalhos ou arquivos de atalhos de terceiros, deixe o tipo MIME em branco.

  10. (Opcional) Digite tipos MIME secundários e extensões de arquivo nos campos Tipos MIME secundários e Extensões de arquivo secundárias. Tipos MIME e extensões de arquivo secundários representam arquivos que seu app pode abrir, mas não são específicos para ele. Por exemplo, seu app pode ser um app de edição de imagens que abre imagens PNG e JPG. Inclua somente tipos de mídia padrão e verifique se não há erros de digitação ou ortografia. Caso seu app só abra atalhos ou arquivos de atalhos de terceiros, deixe o tipo MIME em branco.

  11. Para usar o botão "Novo" da IU do Drive e pedir que os usuários criem um arquivo com seu app, marque a caixa Criar arquivos. Os campos Novo URL e Nome do documento opcionais são exibidos.

    • Esse URL precisa conter um nome de domínio totalmente qualificado. localhost não funciona.
    • Verifique a propriedade desse URL antes de listar seu app no Google Workspace Marketplace.
    • Por padrão, um parâmetro de consulta state é anexado a esse URL para transmitir dados da IU do Drive ao seu app. Para informações sobre o conteúdo do parâmetro state, consulte O parâmetro state.

  12. Digite um URL no campo Novo URL. Esse URL é usado pelo botão "Novo" para redirecionar o usuário ao aplicativo.

  13. (Opcional) Se você quiser que seu app abra arquivos compatíveis com o Google Workspace, marque a caixa Importação.

  14. (Opcional) Se o app precisar gerenciar arquivos em drives compartilhados, marque a caixa Suporte a drives compartilhados. Veja mais informações sobre a compatibilidade com drives compartilhados no seu app em Implementar a compatibilidade com drives compartilhados.

  15. Clique em Enviar.

Solicitar o escopo drive.install

Para permitir que apps apareçam como uma opção no menu "Abrir com" ou "Novo", solicite o escopo https://www.googleapis.com/auth/drive.install para integrar à IU do Drive. Ao solicitar esse escopo, os usuários recebem uma caixa de diálogo parecida com esta:

Caixa de diálogo de instalação da IU do Google Drive.
Figura 1. A caixa de diálogo de instalação ao usar escopos para a IU do Drive.

Para mais informações sobre escopos que você pode solicitar para apps do Drive e como fazer isso, consulte Informações de autorização e autenticação específicas da API.

Parâmetro state

Por padrão, um parâmetro state é anexado ao URL de abertura e ao novo URL para transmitir dados da IU do Drive ao seu app. Esse parâmetro contém uma string codificada em JSON com variáveis de modelo e dados sobre a solicitação para seu app. As variáveis incluídas dependem do tipo de URL usado (URL de abertura ou novo URL):

Variável de modelo Descrição Solicitação de URL
{ids} Uma lista separada por vírgulas de IDs de arquivos sendo abertos. Abrir URL
{exportIds} Uma lista separada por vírgulas de IDs de arquivos que estão sendo exportados (usada apenas ao abrir documentos integrados do Google). Abrir URL
{resourceKeys} Um dicionário JSON de IDs de arquivos mapeados para as respectivas chaves de recurso. Abrir URL
{folderId} O ID da pasta mãe. Novo URL
{folderResourceKey} A chave de recurso da pasta pai. Novo URL
{userId} O ID do perfil que identifica o usuário. Abrir URL e Novo URL
{action} A ação que está sendo realizada. O valor é open ao usar um URL aberto ou create ao usar um novo URL. Abrir URL e Novo URL

O parâmetro state é codificado para URL. Portanto, seu app precisa processar os caracteres de escape e analisá-los como JSON. Os apps podem detectar o valor do create no parâmetro state para verificar uma solicitação para criar um arquivo.

Exemplo de informações de estado em JSON para um novo URL

As informações de state para um novo URL são:

{
  "action":"create",
  "folderId":"FOLDER_ID",
  "folderResourceKey":"FOLDER_RESOURCE_KEY",
  "userId":"USER_ID"
}

Exemplo de informações de estado em JSON para um URL aberto

As informações de state para um URL aberto são:

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

Os IDs e as chaves de recurso são usados para buscar metadados de arquivos e fazer o download do conteúdo dele. Depois que o app tiver o ID do arquivo e um token de acesso, ele poderá verificar permissões, buscar os metadados do arquivo e fazer o download do conteúdo do arquivo, conforme descrito no método files.get.

Um app instalado precisa ser capaz de criar, gerenciar e abrir ações iniciadas na IU do Drive. Para saber mais, consulte Integrar com o botão "Novo" da IU do Drive ou Integrar com o menu de contexto "Abrir com" da IU do Drive.