Uploads recuperáveis

Acessar 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. Isso é diferente de um upload de solicitação única, 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.

  • Use um upload retomável se estiver fazendo o upload de arquivos grandes ou usando uma conexão lenta. Para ver os exemplos de tamanho de arquivo para usar uploads retomáveis, consulte Considerações sobre tamanho do upload.

  • Um upload retomável precisa ser concluído dentro de uma semana após o início.

  • Apenas uploads retomáveis concluídos são exibidos no bucket e, se aplicável, eles substituem um objeto existente com o mesmo nome.

    • O tempo de criação do objeto é baseado na conclusão do upload.
    • Todos os metadados de objeto definidos pelo usuário são especificados na solicitação inicial. Esses metadados são aplicados ao objeto quando o upload é concluído.

  • Um upload retomável finalizado é considerado uma operação de classe A.

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 usa uploads retomáveis nos comandos gsutil cp e gsutil rsync ao fazer upload de dados no Cloud Storage. Se o upload for interrompido, será possível retomá-lo executando o mesmo comando usado para iniciar o upload. Ao retomar um upload de gsutil cp que inclua vários arquivos, use a sinalização -n para evitar o reenvio de arquivos que já foram concluídos.

É possível definir o tamanho mínimo para executar uploads retomáveis com o parâmetro resumable_threshold no arquivo de configuração boto. O valor padrão de resumable_threshold é de 8 MiB.

Bibliotecas de 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

Por padrão, os uploads retomáveis ocorrem automaticamente quando o arquivo é maior que 16 MiB. Você altera o limite para realizar uploads retomáveis com Writer.ChunkSize. Os uploads retomáveis sempre são fragmentados ao usar a biblioteca de cliente Go.

Java

Os uploads retomáveis são controlados pelo método writer. Se preferir, use o método createFrom para especificar um tamanho de corte para executar uploads retomáveis.

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 XML do Cloud Storage usa uma solicitação POST Object que inclui o cabeçalho x-goog-resumable: start 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 Como fazer transferências por 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, mas pode ser cancelado antes da expiração. Se fizer uma solicitação usando um URI de sessão que não é mais válido, você receberá um dos seguintes erros:

  • Um código de status 410 Gone se tiver passado menos de uma semana desde o início do upload.
  • Um código de status 404 Not Found se tiver passado mais de uma semana desde o início do upload.

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.

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.

Dados reenviados

Depois que o Cloud Storage mantém bytes em um upload retomável, eles não podem ser substituídos e o Cloud Storage ignora tentativas de fazer isso. Por isso, não envie dados diferentes ao voltar para um deslocamento enviado anteriormente.

Por exemplo, digamos que você esteja fazendo o upload de um objeto de 100.000 bytes e sua conexão seja interrompida. Ao verificar o status, você descobre que 50.000 bytes foram enviados e mantidos. Se você tentar reiniciar o upload no byte 40.000, o Cloud Storage ignorará os bytes enviados de 40.000 para 50.000. O Cloud Storage começa a manter os dados enviados no byte 50.001.

A seguir