Configurar uma integração com a IU do Drive

Para mostrar seu app no Google Drive quando um usuário cria ou abre um arquivo, primeiro configure uma integração da 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, ative-as 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 interface do Google Drive, ative a API Drive. Isso dá acesso à API e aos recursos de integração da interface.

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

    Ativar a API

Configurar a integração da interface 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 de baixo do painel APIs e serviços, clique em API Google Drive. A página de configuração da API Google Drive vai aparecer.
  3. Selecione a guia Integração da interface do Drive.
  4. (Opcional) Digite um nome no campo Nome do aplicativo. O nome do aplicativo é mostrado aos usuários na guia "Gerenciar apps" nas configurações do Drive.
  5. (Opcional) Digite uma descrição curta de uma linha no campo Descrição curta. A descrição curta é mostrada aos usuários na guia "Gerenciar apps" nas configurações do Drive.
  6. (Opcional) Digite uma descrição completa no campo Descrição longa.

  7. Faça o upload de um ou mais ícones de aplicativo para mostrar na lista de apps conectados do Drive 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 interface do Drive, digite 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 precisa estar 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 a usuários selecionados, cada versão precisará usar um URL exclusivo. Em seguida, você pode criar configurações de app diferentes para cada versão.
    • Você precisa verificar 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 interface do Drive para seu app. Para informações sobre o conteúdo do parâmetro state, consulte O parâmetro state.

  9. (Opcional) Digite os tipos MIME e as 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 seu app foi criado exclusivamente para abrir. Por exemplo, seu app pode abrir um formato integrado para camadas e edição de imagens. Inclua apenas tipos de mídia padrão e verifique se eles não têm erros de digitação. Se o app só abrir arquivos de atalho ou de atalho de terceiros, deixe o tipo MIME em branco.

  10. (Opcional) Digite os tipos MIME e as extensões de arquivo secundárias nos campos Tipos MIME secundários e Extensões de arquivo secundárias. Os tipos MIME e as extensões de arquivo secundárias representam arquivos que seu app pode abrir, mas não são específicos dele. Por exemplo, seu app pode ser um editor de imagens que abre imagens PNG e JPG. Inclua apenas tipos de mídia padrão e verifique se eles não têm erros de digitação. Se o app só abrir arquivos de atalho ou de atalho de terceiros, deixe o tipo MIME em branco.

  11. Para usar o botão “Novo” da interface do Drive e permitir que os usuários criem um arquivo com seu app, marque a caixa Criando arquivos. Os campos Novo URL e Nome do documento (opcional) vão aparecer.

    • Esse URL precisa conter um nome de domínio totalmente qualificado. localhost não funciona.
    • Você precisa verificar 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 interface do Drive para 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 seu aplicativo.

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

  14. (Opcional) Se o app precisar gerenciar arquivos em drives compartilhados, marque a caixa Suporte a drives compartilhados. Para mais informações sobre como oferecer suporte a drives compartilhados no seu app, consulte Implementar suporte a drives compartilhados.

  15. Clique em Enviar.

Solicitar o escopo drive.install

Para permitir que os 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 à interface do Drive. Ao solicitar esse escopo, os usuários recebem uma caixa de diálogo semelhante a esta:

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

Para mais informações sobre os 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 informações.

O parâmetro state

Por padrão, um parâmetro state é anexado ao URL de abertura e ao novo URL para transmitir dados da interface do Drive para 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 Aplicativo de URL
{ids} Uma lista separada por vírgulas dos IDs de arquivo que estão sendo abertos. Abrir URL
{exportIds} Uma lista separada por vírgulas dos IDs de arquivo que estão sendo exportados. Usado apenas ao abrir arquivos do Google Workspace. Abrir URL
{resourceKeys} Um dicionário JSON de IDs de arquivo mapeados para as respectivas chaves de recursos. Abrir URL
{folderId} O ID da pasta mãe. Novo URL
{folderResourceKey} A chave de recurso da pasta mãe. Novo URL
{userId} O ID do perfil que identifica o usuário. Abrir URL e Novo URL
{action} A ação sendo realizada. O valor é open ao usar um URL de abertura ou create ao usar um novo URL. Abrir URL e Novo URL

O parâmetro state é codificado por URL. Portanto, seu app precisa processar os caracteres de escape e analisá-lo como JSON. Os apps podem detectar o valor create no parâmetro state para verificar uma solicitação de criação de 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 de abertura

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

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

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

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