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.
Chamar
files.download: quando o app chama o métododownload(), ele inicializa a solicitação de download da API Drive para o arquivo. Para mais informações, consulte Fazer o download de arquivos.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.
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.
Iniciar LRO: uma operação de longa duração é iniciada e gerencia o processo de download.
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.
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.Chamar
operations.gete verificar o resultado: o app chamaget()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 dedone=falsefor 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.Verificar o estado pendente: se o estado pendente de
done=truefor retornado do LRO, isso significa que o arquivo está pronto para download e que o status da operação foi concluído.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_typedenota 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 ver uma lista completa dos 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 de revisão do arquivo que será transferido por download. Ele só está disponível para download de arquivos blob, Documentos e Planilhas Google. Retorna o código de erroINVALID_ARGUMENTao 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 o Documentos ou o Planilhas Google retornam um redirecionamento inicialmente. 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}/downloadSubstitua 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:
| Tipo de documento | Formato | Tipo MIME | Extensão de arquivo |
|---|---|---|---|
| Google Apps Script | JSON | application/vnd.google-apps.script+json | .json |
| Documentos Google | Microsoft Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document | .docx |
| Desenhos Google | PNG | image/png | .png |
| Formulários Google | CEP | application/zip | .zip |
| Planilhas Google | Microsoft Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx |
| Google Sites | Texto bruto | text/raw | .txt |
| Apresentações Google | Microsoft PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation | .pptx |
| Google Vids | MP4 | application/mp4 | .mp4 |
| Jamboard | application/pdf |
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 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
estado mais recente 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 expira, é necessária 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.
Chamada de método
operations.get(name='NAME');
Substitua NAME pelo nome atribuído ao servidor da operação, conforme
mostrado na resposta à solicitação do método download().
curl
curl -i -H \
'Authorization: Bearer $(gcloud auth print-access-token)" \
'https://googleapis.com/drive/v3/operations/NAME?alt=json'
Substitua NAME pelo nome atribuído ao servidor da operação, conforme
mostrado na resposta à solicitação do método download().
O comando usa o caminho /drive/v3/operations/NAME.
O name só é retornado 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 de 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 vai gerar um
erro
fileNotDownloadable.
O parâmetro de URL alt=media é um parâmetro
do 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=mediaSubstitua:
- FILE_ID: o
fileIddo arquivo que você quer fazer o download. - REVISION_ID: o
revisionIdda revisão que você quer fazer o download.
As revisões dos Documentos, dos Desenhos e das Apresentações Google incrementam automaticamente os números de 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 dela 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.
| Código | Enumeração | Descrição | Ação recomendada |
|---|---|---|---|
| 1 | CANCELLED |
A operação foi cancelada, geralmente pelo autor da chamada. | Execute a operação novamente. |
| 2 | UNKNOWN |
Esse erro pode ser retornado quando um valor Status recebido de outro espaço de endereço pertence a um espaço de erro desconhecido nesse espaço de endereço. Se o erro da API não retornar informações suficientes, ele poderá ser convertido neste erro. |
Tentar novamente com a espera exponencial. |
| 3 | INVALID_ARGUMENT |
O cliente especificou um argumento inválido. Esse erro é diferente de FAILED_PRECONDITION. INVALID_ARGUMENT indica argumentos problemáticos, independentemente do estado do sistema, como um nome de arquivo incorreto. |
Não tente novamente sem resolver o problema. |
| 4 | DEADLINE_EXCEEDED |
O prazo expirou antes do término da operação. Para operações que alteram o estado do sistema, esse erro pode ser retornado mesmo que a operação tenha sido concluída com sucesso. Por exemplo, uma resposta bem-sucedida de um servidor pode ter atrasado tempo suficiente para que o prazo expirasse. | Tentar novamente com a espera exponencial. |
| 5 | NOT_FOUND |
Alguma entidade solicitada, como um recurso FHIR, não foi encontrada. | Não tente novamente sem resolver o problema. |
| 6 | ALREADY_EXISTS |
A entidade que um cliente tentou criar, como uma instância DICOM, já existe. | Não tente novamente sem resolver o problema. |
| 7 | PERMISSION_DENIED |
O autor da chamada não tem permissão para executar a operação especificada. Esse código do erro não indica que a solicitação é válida, que a entidade solicitada existe ou atende a outras condições prévias. | Não tente novamente sem resolver o problema. |
| 8 | RESOURCE_EXHAUSTED |
Alguns recursos foram esgotados, como uma cota por projeto. | Tentar novamente com a espera exponencial. A cota pode ficar disponível com o tempo. |
| 9 | FAILED_PRECONDITION |
A operação foi rejeitada porque o estado do sistema não é o necessário para a execução dela. Por exemplo, o diretório a ser excluído não está vazio ou uma operação rmdir foi aplicada a um elemento que não é um diretório. |
Não tente novamente sem resolver o problema. |
| 10 | ABORTED |
A operação foi cancelada, normalmente devido a um problema de simultaneidade, como falha na verificação do sequenciador ou cancelamento da transação. | Tentar novamente com a espera exponencial. |
| 11 | OUT_OF_RANGE |
Houve uma tentativa da operação depois do intervalo válido, como a busca ou a leitura após o fim do arquivo. Diferentemente de INVALID_ARGUMENT, este erro indica um problema que poderá ser corrigido se o estado do sistema mudar. |
Não tente novamente sem resolver o problema. |
| 12 | UNIMPLEMENTED |
A operação não foi implementada ou não é compatível/não está ativada na API Drive. | Não tente novamente. |
| 13 | INTERNAL |
Erros internos. Isso indica que foi encontrado um erro inesperado no processamento do sistema de base. | Tentar novamente com a espera exponencial. |
| 14 | UNAVAILABLE |
A API Drive não está disponível. Provavelmente, essa é uma condição temporária, que pode ser corrigida com uma nova tentativa com a espera exponencial. Observe que nem sempre é seguro repetir operações não idempotentes. | Tentar novamente com a espera exponencial. |
| 15 | DATA_LOSS |
Perda ou corrupção irrecuperável de dados. | Entre em contato com seu administrador de sistemas. O administrador do sistema pode entrar em contato com um representante de suporte se ocorrer perda ou corrupção de dados. |
| 16 | UNAUTHENTICATED |
A solicitação não tem credenciais válidas de autenticação para a operação. | Não tente novamente sem resolver o problema. |