Uploads recuperáveis

Acessar os exemplos

Nesta página, você aprenderá sobre uploads retomáveis no Cloud Storage. Os uploads recuperáveis são o método recomendado para fazer o upload de arquivos grandes, porque você não precisa reiniciá-los desde o início em caso de falha de rede enquanto o upload estiver em andamento.

Introdução

Um upload retomável permite retomar operações de transferência de dados no Cloud Storage depois que uma falha de comunicação interrompe o fluxo de dados. Os uploads retomáveis enviam várias solicitações, cada uma contendo uma parte do objeto que você está enviando. Eles são diferentes do upload simples, que contém todos os dados do objeto em uma única solicitação e precisa ser reiniciado desde o início se falhar em parte.

Como as ferramentas e as APIs usam uploads retomáveis

Dependendo de como você interage com o Cloud Storage, os uploads retomáveis podem ser gerenciados automaticamente em seu nome. Clique em uma guia na tabela abaixo para saber mais:

Console

O Console do Cloud gerencia automaticamente os uploads retomáveis em seu nome. No entanto, se você atualizar ou sair do Console do Cloud enquanto um upload estiver em andamento, o upload será cancelado.

gsutil

A ferramenta de linha de comando gsutil permite definir um tamanho mínimo para executar uploads recuperáveis com o parâmetro resumable_threshold no arquivo de configuração boto. O valor padrão de resumable_threshold é 8 MiB.

Bibliotecas cliente

C++

É possível alternar o uso de uploads retomáveis como parte do método WriteObject.

C#

É possível iniciar um upload retomável com CreateObjectUploader.

Go

Você controla o tamanho mínimo para realizar uploads retomáveis com Writer.ChunkSize. O Go sempre executa uploads retomáveis em partes.

Java

Os uploads retomáveis são controlados pelo método writer.

Node.js

Os uploads retomáveis são gerenciados automaticamente ao usar o método createWriteStream.

PHP

Os uploads retomáveis são gerenciados automaticamente em seu nome, mas podem ser controlados diretamente usando a opção resumable.

Python

Os uploads retomáveis ocorrem automaticamente quando o arquivo é maior que 8 MiB. Outra opção é usar a mídia retomável para gerenciar uploads recuperáveis por conta própria.

Ruby

Todos os uploads são tratados como uploads retomáveis.

APIs REST

API JSON

A API JSON do Cloud Storage usa uma solicitação POST Object que inclui o parâmetro de consulta uploadType=resumable para iniciar o upload retomável. Essa solicitação retorna como URI de sessão que você usa em uma ou mais solicitações PUT Object para fazer upload dos dados do objeto. Para ver um guia passo a passo de como criar sua própria lógica para upload retomável, consulte Como fazer uploads retomáveis.

API XML

A API JSON do Cloud Storage usa uma solicitação POST Object que inclui o parâmetro de consulta uploadType=resumable para iniciar o upload retomável. Essa solicitação retorna como URI de sessão que você usa em uma ou mais solicitações PUT Object para fazer upload dos dados do objeto. Para ver um guia passo a passo de como criar sua própria lógica para upload retomável, consulte Como fazer uploads retomáveis.

Uploads retomáveis de tamanho desconhecido

O mecanismo de upload recuperável suporta transferências cujo tamanho do arquivo não é conhecido com antecedência. Isso pode ser útil para casos como a compactação de um objeto durante o upload, uma vez que é difícil prever o tamanho exato do arquivo compactado no início de uma transferência. O mecanismo é útil caso queira fazer o streaming de uma transferência que pode ser retomada após ser interrompida ou se a codificação de transferência fragmentada não funcionar em seu aplicativo.

Para mais informações, consulte Transferências de streaming.

Considerações

Esta seção é útil se você estiver criando seu próprio cliente que envia solicitações de upload retomáveis diretamente para a API JSON ou XML.

URIs de sessão

Ao iniciar um upload retomável, o Cloud Storage retorna um URI de sessão, que é usado nas próximas solicitações para fazer upload dos dados reais. Um exemplo de URI de sessão na API JSON é:

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Um exemplo de URI de sessão na API XML é:

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Esse URI de sessão atua como um token de autenticação. Por isso as solicitações que o utilizam não precisam ser assinadas e podem ser usadas por qualquer pessoa para fazer upload de dados para o bucket de destino sem a necessidade de nenhuma outra autenticação. Por isso, seja criterioso ao compartilhar o URI de sessão e apenas o compartilhe por HTTPS.

Um URI de sessão expira após uma semana. Caso use um URI de sessão expirado em uma solicitação, você receberá um código de status 404 Not Found. Nesse caso, é necessário iniciar um novo upload retomável, conseguir um novo URI de sessão e iniciar o upload desde o início usando o novo URI de sessão.

Desempenho do upload

Os uploads retomáveis são fixados na região em que são iniciados. Por exemplo, se você iniciar um upload retomável nos EUA e fornecer o URI de sessão a um cliente na Ásia, o upload ainda passará pelos EUA. Continuar um upload retomável em uma região onde ele não foi iniciado pode causar lentidão.

Se você usar uma instância do Compute Engine para iniciar um upload retomável, ela precisará estar no mesmo local do bucket do Cloud Storage em que foi feito upload. Em seguida, use um serviço de IP geográfico para escolher a região do Compute Engine para onde encaminhará solicitações de clientes. Isso ajudará a manter o tráfego localizado em uma região geográfica.

Diretrizes de repetição

  • Repita quaisquer solicitações que retornem os seguintes códigos de status:

    • 408 Request Timeout
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout

  • Gerencie os erros 404 Not Found iniciando um novo upload retomável.

  • Ao realizar solicitações de repetição, use a espera exponencial truncada.

Verificações de integridade

É recomendável solicitar uma verificação de integridade do objeto final enviado para se certificar de que ele corresponda ao arquivo de origem. Para isso, calcule o resumo MD5 do arquivo de origem e adicione-o ao cabeçalho da solicitação Content-MD5.

A verificação da integridade do arquivo enviado é especialmente importante se você estiver fazendo upload de um arquivo grande durante um longo período, porque a chance de o arquivo de origem ser modificado durante a operação é maior.

A seguir