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 é apropriado 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 de usuário ruim. 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. É possível usar o recurso operations para recuperar de forma assíncrona o status do método da API pesquisando a operação pelo método get(). As LROs na API Drive aderem ao 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 inicializa 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 do usuário que ainda não foi concedida, ele solicitará que o usuário faça login. O app também pede acesso com escopos que você especifica 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 para o Google Vids ou algum outro conteúdo do Google Workspace.

4. Start 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 contendo informações sobre o usuário que fez a solicitação e vários campos de metadados de arquivo.

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 get() nos intervalos recomendados para consultar 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 que a pesquisa seja feita várias vezes. Para mais informações, consulte Conferir os detalhes de uma operação de longa duração.

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

9. Retornar a operação concluída com o URI de download: depois que 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 método download() no recurso files. O método usa os parâmetros de consulta de 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 denota o tipo MIME que o método precisa usar. Ele só está disponível ao fazer o download de conteúdo de mídia que não seja blob, como documentos do Google Workspace. Para conferir uma lista completa de tipos MIME compatíveis, consulte Exportar tipos MIME para documentos do Google Workspace.

  Se o tipo MIME não estiver definido, o documento do Google Workspace será transferido por download 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 feito o download. Ele só está disponível para download de 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 sem suporte.

O método download() é a única maneira de fazer o download de arquivos Vids no formato MP4 e geralmente é mais adequado para fazer o download da maioria dos arquivos de vídeo.

Os links de download gerados para os apps Documentos ou Planilhas Google 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 recurso. Para mais informações, consulte Acessar arquivos do Drive compartilhados por link usando chaves de recurso.

O protocolo da 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 transferir por download.

Tipos MIME padrão

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

Resposta do download

Ao chamar o método download(), o corpo da resposta é 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 seu arquivo contra acesso não autorizado. 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 inicialmente retornadas 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 único atribuído pelo servidor.

O método get() recebe o último estado de uma operação de longa duração de forma assíncrona. Os clientes podem usar esse método para consultar 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 um recesso exponencial entre cada solicitação de pesquisa, por exemplo, 10 segundos.

Uma LRO permanece disponível por no mínimo 12 horas, mas, em alguns casos, pode durar mais. Essa duração está sujeita a mudanças e pode ser diferente entre os tipos de arquivo. Quando o recurso expirar, será 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 recurso.

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 é retornado apenas na resposta a uma solicitação download(). Não há outra maneira de extrair, porque 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 de download.

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

Fazer o download de uma revisão

É possível usar o valor do campo headRevisionId do recurso files para fazer o download da revisão mais recente. Isso busca a revisão que corresponde aos metadados do arquivo que você extraiu anteriormente. Para fazer o download dos 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 da revisão de arquivos blob, chame o método get() no recurso revisions com o ID do arquivo a ser transferido, 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.

As revisões dos apps Documentos, Planilhas, Apresentações e Vídeos Google não podem ser salvas usando o método get() com o URL alt=media . Caso contrário, ele gera 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ê usar uma biblioteca de cliente para a API Drive, não será necessário definir esse parâmetro explicitamente.

O protocolo da 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 fazer o download.
• REVISION_ID: o revisionId da revisão que você quer fazer o download.

As revisões dos apps Documentos, Desenhos e Apresentações Google aumentam 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 recomenda como lidar com ele. Para muitos erros, a ação recomendada é tentar a solicitação novamente usando a espera exponencial.

Leia mais sobre esse modelo de erro e como trabalhar com ele no Guia de design da API.

Temas relacionados

• Fazer o download e exportar arquivos
• Gerenciar revisões de arquivos