Gerenciar operações de longa duração

Uma operação de longa duração (LRO, na sigla em inglês) é um método de API que leva mais tempo para ser concluído do que o adequado para uma resposta de API. Normalmente, não é recomendável manter a linha de execução de chamada aberta enquanto a tarefa é executada, porque isso oferece uma experiência ruim ao usuário. Em vez disso, é melhor retornar algum tipo de promessa ao usuário e permitir que ele verifique mais tarde.

A API Google Drive retorna uma LRO sempre que você chama o download método no files recurso para fazer o download do conteúdo de um arquivo pela API Drive ou pelas bibliotecas de cliente.

O método retorna um operations recurso para o cliente. É possível usar o recurso operations para recuperar de forma assíncrona o status do método de API pesquisando a operação pelo método get. As LROs na API Drive seguem o padrão de design de LRO do Google Cloud .

Para mais informações, consulte Operações de longa duração.

Visão geral do processo

O diagrama a seguir mostra as etapas gerais de como o método file.download funciona.

1. Chamar files.download: quando o app chama o método download, ele inicia a solicitação de download da API Drive para o arquivo. Para mais informações, consulte Fazer o download de arquivos.

2. Solicitar permissões: a solicitação envia credenciais de autenticação para a API Drive. Se o app exigir a chamada da API Drive usando uma autenticação de usuário que ainda não foi concedida, ele vai pedir que o usuário faça login. O app também pede acesso com escopos especificados ao configurar a autenticação.

3. Iniciar o download: uma solicitação de API Drive é feita para iniciar o download do arquivo. A solicitação pode ser feita para o Google Vids ou algum outro conteúdo do Google Workspace.

4. Iniciar a LRO: uma operação de longa duração começa e gerencia o processo de download

5. Retornar operação pendente: a API Drive retorna uma operação pendente que contém informações sobre o usuário que está fazendo a solicitação e vários campos de metadados de arquivos.

6. Estado pendente inicial: o app recebe a operação pendente com um estado pendente inicial de done=null. Isso indica que o arquivo ainda não está pronto para download e que o status da operação está pendente.

7. Chamar operations.get e verificar o resultado: o app chama o get nos intervalos recomendados para pesquisar o resultado da operação e receber o estado mais recente de uma operação de longa duração. Se o estado pendente de done=false for retornado, o app precisará continuar pesquisando até que a operação retorne o estado concluído (done=true). Para arquivos grandes, espere pesquisar várias vezes. Para mais informações, consulte Acessar os detalhes de uma operação de longa duração.

8. Verificar o estado pendente: se o estado pendente de done=true for retornado da LRO, isso indica que o arquivo está pronto para download e que o status da operação está concluído.

9. Retornar operação concluída com URI de download: quando a LRO é concluída, a API Drive retorna o URI de download e o arquivo fica disponível para o usuário.

Fazer o download de arquivos

Para fazer o download de conteúdo em uma operação de longa duração, use o download método no files recurso. O método usa os parâmetros file_id, mime_type e revision_id:

• Obrigatório. O parâmetro de caminho file_id é o ID do arquivo do qual será feito o download.

• Opcional. O parâmetro de consulta mime_type indica o tipo MIME que o método deve usar. Ele só está disponível ao fazer o download de conteúdo de mídia não blob (como documentos do Google Workspace). Para uma lista completa dos tipos MIME compatíveis, consulte Tipos MIME de exportação para documentos do Google Workspace.

  Se o tipo MIME não estiver definido, o documento do Google Workspace será baixado com um tipo MIME padrão. Para mais informações, consulte Tipos MIME padrão.

• Opcional. O parâmetro de consulta revision_id é o ID da revisão do arquivo do qual será feito o download. Ele só está disponível ao fazer o download de arquivos blob, Google Docs e Planilhas Google. Retorna o código de erro INVALID_ARGUMENT ao fazer o download de uma revisão específica em arquivos não compatíveis.

O método download é a única maneira de fazer o download de arquivos do Vids no formato MP4 e geralmente é mais adequado para fazer o download da maioria dos arquivos de vídeo. Se você tentar exportar arquivos do Google Vids, vai receber um fileNotExportable erro.

Os links de download gerados para o Google Docs ou Planilhas inicialmente retornam um redirecionamento. Clique no novo link para fazer o download do arquivo.

Uma solicitação para o método download que inicia a LRO e a solicitação para buscar o URI de download final precisam usar chaves de recursos. Para mais informações, consulte Acessar arquivos do Drive compartilhados por link usando chaves de recursos.

O protocolo de solicitação é mostrado aqui.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

Substitua FILE_ID pelo fileId do arquivo que você quer baixar.

Tipos MIME padrão

Se um tipo MIME não estiver definido ao fazer o download de conteúdo não blob, os seguintes tipos MIME padrão serão atribuídos:

Resposta do download

Ao chamar o método download, o corpo da resposta consiste em um recurso que representa uma operação de longa duração. O método normalmente retorna um link para fazer o download do conteúdo do arquivo.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

Esta saída inclui os seguintes valores:

• RESOURCE_KEY: uma chave de recurso ajuda a proteger o arquivo contra acesso não intencional. Para mais informações, consulte Acessar arquivos do Drive compartilhados por link usando chaves de recursos.

• NAME: o nome atribuído pelo servidor.

• DOWNLOAD_URI: o URI de download final do arquivo.

Observe que o campo partialDownloadAllowed indica se um download parcial é permitido e é true ao fazer o download do conteúdo do arquivo blob.

Acessar os detalhes de uma operação de longa duração

Operações de longa duração são chamadas de método que podem demorar para serem concluídas. Normalmente, as operações de download recém-criadas são retornadas inicialmente em um estado pendente (done=null), especialmente para arquivos do Vids.

É possível usar o operations recurso que a API Drive fornece para verificar o status da LRO de processamento, incluindo o nome exclusivo atribuído pelo servidor.

O método get recebe o estado mais recente de uma operação de longa duração de forma assíncrona. Os clientes usam este método para pesquisar o resultado da operação em intervalos, conforme recomendado pelo serviço da API.

Pesquisar uma operação de longa duração

Para pesquisar uma LRO disponível, chame repetidamente o get método até que a operação seja concluída. Use uma espera exponencial entre cada solicitação de pesquisa. Por exemplo, pesquise a cada 10 segundos.

Uma LRO permanece disponível por um mínimo de 12 horas, mas, em alguns casos, pode persistir por mais tempo. Essa duração está sujeita a mudanças e pode ser diferente entre os tipos de arquivo. Quando o recurso expira, uma nova solicitação de método download é necessária.

Todas as solicitações para get precisam usar chaves de recursos. Para mais informações, consulte Acessar arquivos do Drive compartilhados por link usando chaves de recursos.

Os protocolos de solicitação são mostrados aqui.

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

O name só é retornado na resposta a uma solicitação de download. Não há outra maneira de recuperá-lo, já que a API Drive não oferece suporte ao método list. Se o valor name for perdido, será necessário gerar uma nova resposta chamando a solicitação do método download novamente.

A resposta de uma solicitação get consiste em um recurso que representa uma operação de longa duração. Para mais informações, consulte Resposta do download.

Quando a resposta contém um estado concluído (done=true), a operação de longa duração terminou.

Fazer o download de uma revisão

É possível usar o valor do headRevisionId campo do recurso files para fazer o download da revisão mais recente. Isso busca a revisão que corresponde aos metadados do arquivo recuperado anteriormente. Para fazer o download dos dados de todas as revisões anteriores do arquivo que ainda estão armazenadas na nuvem, chame o list método no recurso revisions com o parâmetro fileId. Isso retorna todos os revisionIds no arquivo.

Para fazer o download do conteúdo da revisão de arquivos blob, é necessário chamar o get método no revisions recurso com o ID do arquivo a ser baixado, o ID da revisão e o alt parâmetro do sistema. O parâmetro alt=media informa ao servidor que um download de conteúdo está sendo solicitado como um formato de resposta alternativo.

O parâmetro do sistema alt está disponível em todas as APIs REST do Google. Se você usar uma biblioteca de cliente para a API Drive, não será necessário definir esse parâmetro explicitamente.

As revisões do Google Docs, Planilhas, Slides e Vids não podem ser baixadas usando o método get com o parâmetro alt=media. Caso contrário, ele gera um fileNotDownloadable erro.

O protocolo de solicitação é mostrado aqui.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Substitua:

• FILE_ID: o fileId do arquivo que você quer baixar.
• REVISION_ID: o revisionId da revisão que você quer baixar.

As revisões do Google Docs, Desenhos e Slides incrementam automaticamente os números de revisão. No entanto, a série de números pode ter lacunas se as revisões forem excluídas. Portanto, não confie em números sequenciais para recuperar revisões.

Resolver problemas com LROs

Quando uma LRO falha, a resposta inclui um código de erro canônico do Google Cloud.

A tabela a seguir mostra cada código de erro, o código de status HTTP mapeado, uma descrição e uma recomendação de como lidar com o código de erro. Para muitos erros, a ação recomendada é tentar a solicitação novamente usando espera exponencial.

É possível ler mais sobre esse modelo de erro e como trabalhar com ele no Guia de design de API.

Temas relacionados

• Fazer o download e exportar arquivos