Uploads recuperáveis

Configuração

Nesta página, você aprenderá sobre uploads retomáveis no Cloud Storage. Os uploads retomá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 ser iniciado, mas pode ser cancelado a qualquer momento.

  • 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.

    • Os metadados de objeto definidos pelo usuário são especificados na solicitação inicial. Esses metadados são aplicados ao objeto assim que o upload é concluído.

    • A API JSON também permite a configuração de metadados personalizados na solicitação final ao incluir cabeçalhos com o prefixo X-Goog-Meta- nessa solicitação.

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. Nesta seção, descrevemos o comportamento de upload retomável para diferentes ferramentas e fornecemos orientações sobre como configurar o tamanho apropriado do buffer do aplicativo.

Console

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

Linha de comando

A gcloud CLI usa uploads retomáveis nos comandos gcloud storage cp e gcloud storage rsync ao fazer upload de dados para o Cloud Storage. Se o upload for interrompido, será possível retomá-lo executando o mesmo comando que foi usado para iniciá-lo. Ao retomar um upload que inclui vários arquivos, use a flag --no-clobber para evitar o reenvio de arquivos que já foram concluídos.

Bibliotecas de cliente

C++

As funções em storage::Client funcionam com um comportamento diferente:

Por padrão, UploadFile() faz um upload retomável quando o objeto é maior que 20 MiB. Caso contrário, ele executa um upload simples ou de várias partes. É possível configurar esse limite definindo MaximumSimpleUploadsSizeOption ao criar uma storage::Client.

8 MiB é o tamanho de buffer padrão, que você pode modificar com a opção UploadBufferSizeOption.

A biblioteca de cliente do Python usa um tamanho do buffer igual ao tamanho do bloco. O tamanho do buffer precisa ser um múltiplo de 256 KiB (256 x 1.024 bytes). Ao usar WriteObject() e UploadFile(), considere as vantagens e desvantagens entre a velocidade de upload e o uso de memória. O uso de buffers pequenos para fazer upload de objetos grandes pode tornar o upload lento. Para saber mais sobre a relação entre a velocidade de upload e o tamanho do buffer para C++, consulte a análise detalhada no GitHub.

C#

Durante o upload, a biblioteca de cliente C# sempre realiza uploads retomáveis. É possível iniciar um upload retomável com CreateObjectUploader.

A biblioteca de cliente do C# usa um tamanho do buffer igual ao tamanho do bloco. O tamanho do buffer padrão é de 10 MB, e esse valor pode ser alterado configurando ChunkSize em UploadObjectOptions. O tamanho do buffer precisa ser um múltiplo de 256 KiB (256 x 1.024 bytes). Tamanhos de buffer maiores geralmente tornam os uploads mais rápidos, mas há um equilíbrio entre velocidade e uso de memória.

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.

Os uploads de várias partes ocorrem quando o objeto é menor que Writer.ChunkSize ou quando Writer.ChunkSize é definido como 0, em que os fragmentos ficam desativados. O Writer não será capaz de repetir solicitações se ChunkSize for definido como 0.

A biblioteca de cliente do Go usa um tamanho do buffer igual ao tamanho do bloco. O tamanho do buffer precisa ser um múltiplo de 256 KiB (256 x 1.024 bytes). Tamanhos de buffer maiores geralmente tornam os uploads mais rápidos, mas há um equilíbrio entre velocidade e uso de memória. Se você estiver executando vários uploads retomáveis simultaneamente, defina Writer.ChunkSize como um valor menor que 16 MiB para evitar a sobrecarga de memória.

Observe que o objeto não está finalizado no Cloud Storage até que você chame Writer.Close() e receba uma resposta bem-sucedida. Writer.Close retornará um erro se a solicitação não for bem-sucedida.

Java

A biblioteca de cliente Java tem métodos separados para uploads retomáveis e de várias partes. Os métodos a seguir sempre executam um upload retomável:

O tamanho de buffer padrão é 15 MiB. Você pode definir o tamanho do buffer usando o método WriteChannel#setChunkSize(int) ou transmitindo um parâmetro bufferSize ao método Storage#createFrom. O tamanho do buffer tem um mínimo de 256 KiB. Ao chamar WriteChannel#setChunkSize(int) internamente, o tamanho do buffer é deslocado para um múltiplo de 256 KiB.

O armazenamento em buffer para uploads retomáveis funciona como um limite de limpeza mínimo, em que as gravações menores que o tamanho do buffer são armazenadas em buffer até que uma gravação envie o número de bytes armazenados em buffer acima do tamanho do buffer.

Se você estiver fazendo upload de quantidades menores de dados, use Storage#create(BlobInfo, byte[], Storage.BlobTargetOption...) ou Storage#create(BlobInfo, byte[], int, int, Storage.BlobTargetOption...).

Node.js

Os uploads retomáveis ocorrem automaticamente. É possível desativar os uploads retomáveis definindo resumable em UploadOptions como false. Os uploads retomáveis são gerenciados automaticamente ao usar o método createWriteStream.

Não há tamanho de buffer padrão, e os uploads em partes precisam ser invocados manualmente configurando a opção chunkSize em CreateResumableUploadOptions. Se chunkSize for especificado, os dados serão enviados em solicitações HTTP separadas, cada uma com um payload de tamanho chunkSize. Se nenhum chunkSize for especificado e a biblioteca estiver executando um upload retomável, todos os dados serão transmitidos em uma única solicitação HTTP.

A biblioteca de cliente do Node.js usa um tamanho do buffer igual ao tamanho do bloco. O tamanho do buffer precisa ser um múltiplo de 256 KiB (256 x 1.024 bytes). Tamanhos de buffer maiores geralmente tornam os uploads mais rápidos, mas há uma compensação entre velocidade e uso de memória.

PHP

Por padrão, os uploads retomáveis ocorrem automaticamente quando o tamanho do objeto é maior que 5 MB. Caso contrário, ocorrem uploads de várias partes. Esse limite não pode ser alterado. É possível forçar um upload retomável configurando a opção resumable na função upload.

A biblioteca de cliente do PHP usa um tamanho do buffer igual ao tamanho do bloco. 256 KiB é o tamanho do buffer padrão de um upload retomável. É possível alterá-lo definindo a propriedade chunkSize. O tamanho do buffer precisa ser um múltiplo de 256 KiB (256 x 1.024 bytes). Tamanhos de buffer maiores geralmente tornam os uploads mais rápidos, mas há um equilíbrio entre velocidade e uso de memória.

Python

Os uploads retomáveis ocorrem quando o objeto é maior que 8 MiB, e os uploads de várias partes ocorrem quando o objeto é menor que 8 MiB. Esse limite não pode ser alterado. A biblioteca de cliente do Python usa um tamanho de buffer igual ao tamanho do bloco. O tamanho do buffer padrão usado para um upload retomável é de 100 MiB. Para isso, defina a propriedade blob.chunk_size.

Para sempre executar um upload retomável, independentemente do tamanho do objeto, use a classe storage.BlobWriter ou o método storage.Blob.open(mode='w'). Para esses métodos, o tamanho de buffer padrão é 40 MiB. Também é possível usar a mídia retomável para gerenciar uploads retomáveis.

O tamanho da parte precisa ser um múltiplo de 256 KiB (256 x 1.024 bytes). Tamanhos de bloco maiores geralmente tornam os uploads mais rápidos, mas há uma compensação entre velocidade e uso de memória.

Ruby

A biblioteca de cliente do Ruby trata todos os uploads como uploads retomáveis não divididos.

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 retomável aceita transferências em que o 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 Uploads de streaming.

Desempenho do upload

Como escolher regiões de sessão

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. Para reduzir o tráfego entre regiões e melhorar o desempenho, mantenha uma sessão de upload retomável na região em que ela foi criada.

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.

Como fazer upload em partes

Se possível, evite dividir uma transferência em partes menores e, em vez disso, faça upload de todo o conteúdo de uma só vez. Evitar essa divisão remove os custos de latência e as cobranças por operações de consulta do deslocamento persistente de cada bloco, além de melhorar a capacidade. No entanto, faça upload em partes nas situações a seguir:

  • Seus dados de origem são gerados dinamicamente, e você quer limitar o volume necessário de buffer no lado do cliente em caso de falha no upload.

  • Os clientes têm limitações de tamanho de solicitação, como é o caso de muitos navegadores.

Se você estiver usando a API JSON ou XML e seu cliente receber um erro, ele poderá consultar o servidor quanto ao deslocamento persistente e retomar o upload dos bytes restantes desse deslocamento. O console do Google Cloud, a CLI do Google Cloud e as bibliotecas de cliente lidam com isso automaticamente em seu nome. Consulte Como as ferramentas e as APIs usam uploads retomáveis para mais orientações sobre a divisão em bibliotecas de cliente específicas.

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.

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.

Ao iniciar um upload retomável, o valor x-goog-content-sha256 será ignorado. Portanto, é recomendável definir x-goog-content-sha256 como UNSIGNED-PAYLOAD.

Tentar novamente e reenviar dados

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