Gerenciar operações de longa duração

Uma operação de longa duração (LRO) é um método de API que leva mais tempo para ser concluído do que o adequado para uma resposta da API. Normalmente, não é recomendável manter a thread de chamada aberta enquanto a tarefa é executada, porque isso oferece uma experiência ruim para o 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 método download no recurso files para fazer o download do conteúdo de um arquivo pela API Drive ou pelas bibliotecas de cliente.

O método retorna um recurso operations ao cliente. Use o recurso operations para recuperar de forma assíncrona o status do método da API pesquisando a operação com o 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 de alto nível de como o método file.download funciona.

1. Chamada 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 a autenticação de um usuário que ainda não foi concedida, ele vai pedir que o usuário faça login. Seu app também pede acesso com escopos especificados ao configurar a autenticação.

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

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

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

6. Estado pendente inicial: seu app recebe a operação pendente junto 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. Chame operations.get e verifique o resultado: seu app chama 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, seu 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 Receber detalhes sobre uma operação de longa duração.

8. Verificar 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 a operação concluída com o URI de download: quando a LRO for concluída, a API Drive vai retornar o URI de download, e o arquivo estará disponível para o usuário.

Fazer o download de arquivos

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

• Obrigatório. O parâmetro de consulta file_id é o ID do arquivo a ser baixado.

• 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 de 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 a ser baixado. Ele só está disponível ao baixar arquivos blob, Documentos 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 baixar arquivos do Vids em formato MP4 e geralmente é mais adequado para baixar a maioria dos arquivos de vídeo.

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

Uma solicitação ao método download que inicia a LRO e a solicitação para buscar o URI de download final precisam usar chaves de recurso. 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 for definido ao baixar conteúdo que não seja um 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. Normalmente, o método 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 seu arquivo contra acesso não intencional. Para mais informações, consulte Acessar arquivos do Drive compartilhados por link usando chaves de recurso.

• NAME: o nome atribuído pelo servidor.

• DOWNLOAD_URI: o URI de download final do arquivo.

O campo partialDownloadAllowed indica se um download parcial é permitido. Verdadeiro 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 levar um tempo considerável para serem concluídas. Normalmente, as operações de download recém-criadas são retornadas inicialmente em um estado pendente (done=null), principalmente para arquivos do Vids.

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

O método get recebe de forma assíncrona o estado mais recente de uma operação de longa duração. Os clientes podem usar esse 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 método get até que a operação seja concluída. Use uma espera exponencial entre cada solicitação de pesquisa, como 10 segundos.

Uma LRO fica 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 variar entre os tipos de arquivo. Quando o recurso expira, é necessário fazer uma nova solicitação de método download.

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 download. Não há outra maneira de recuperar o ID, já que a API Drive não é compatível com o método List. Se o valor de name for perdido, gere 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 Fazer o download da resposta.

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

Baixar uma revisão

Use o valor do campo headRevisionId do recurso files para baixar a revisão mais recente. Isso busca a revisão que corresponde aos metadados do arquivo que você recuperou anteriormente. Para baixar os dados de todas as revisões anteriores do arquivo que ainda estão armazenadas na nuvem, chame o método list no recurso revisions com o parâmetro fileId. Isso retorna todos os revisionIds no arquivo.

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

Não é possível baixar revisões dos apps Documentos, Planilhas, Apresentações e Vids usando o método get com o URL alt=media . Caso contrário, ele vai gerar um erro fileNotDownloadable.

O parâmetro de URL alt=media é um parâmetro de sistema disponível em todas as APIs REST do Google. Se você usa uma biblioteca de cliente para a API Drive, não precisa definir esse parâmetro explicitamente.

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 dos apps Documentos, Desenhos e Apresentações Google 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 de LROs

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

A tabela a seguir explica a causa de cada código e dá uma recomendação de como lidar com ele. Para muitos erros, a ação recomendada é tentar a solicitação novamente usando a espera exponencial.

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

Temas relacionados

• Baixar e exportar arquivos