Carregamentos retomáveis

Configuração

Esta página aborda os carregamentos retomáveis no Cloud Storage. Os carregamentos retomáveis são o método recomendado para carregar ficheiros grandes, porque não tem de os reiniciar desde o início se ocorrer uma falha de rede durante o carregamento.

Introdução

Um carregamento retomável permite-lhe retomar as operações de transferência de dados para o Cloud Storage depois de uma falha de comunicação ter interrompido o fluxo de dados. Os carregamentos retomáveis funcionam através do envio de vários pedidos, cada um dos quais contém uma parte do objeto que está a carregar. Isto é diferente de um carregamento de pedido único, que contém todos os dados do objeto num único pedido e tem de ser reiniciado desde o início se falhar a meio.

  • Use um carregamento com opção de retomar o mesmo se estiver a carregar ficheiros grandes ou a carregar através de uma ligação lenta. Por exemplo, os limites de tamanho dos ficheiros para usar carregamentos com opção de retomar o mesmo, consulte as considerações sobre o tamanho do carregamento.

  • Um carregamento retomável tem de ser concluído no prazo de uma semana após o início, mas pode ser cancelado em qualquer altura.

  • Apenas um carregamento retomável concluído aparece no seu contentor e, se aplicável, substitui um objeto existente com o mesmo nome.

    • A hora de criação do objeto baseia-se no momento em que o carregamento é concluído.

    • Os metadados de objetos definidos pelo utilizador são especificados no pedido inicial. Estes metadados são aplicados ao objeto assim que o carregamento estiver concluído.

    • A API JSON também suporta a definição de metadados personalizados no pedido final se incluir cabeçalhos com o prefixo X-Goog-Meta- nesse pedido.

Como as ferramentas e as APIs usam carregamentos com opção de retomar o mesmo

Consoante a forma como interage com o Cloud Storage, os carregamentos retomáveis podem ser geridos automaticamente em seu nome. Esta secção descreve o comportamento de carregamento retomável para diferentes ferramentas e fornece orientações sobre a configuração do tamanho da memória intermédia adequado para a sua aplicação.

Consola

A consola Google Cloud gere os carregamentos retomáveis automaticamente em seu nome. No entanto, se atualizar a página ou sair da Google Cloud consola enquanto um carregamento está em curso, o carregamento é cancelado.

Linha de comandos

A CLI gcloud usa carregamentos retomáveis nos comandos gcloud storage cp e gcloud storage rsync quando carrega dados para o Cloud Storage. Se o carregamento for interrompido, pode retomá-lo executando o mesmo comando que usou para iniciar o carregamento. Quando retomar um carregamento deste tipo que inclua vários ficheiros, use a flag --no-clobber para evitar o novo carregamento de ficheiros que já foram concluídos com êxito.

Bibliotecas cliente

Quando realiza carregamentos retomáveis, as bibliotecas cliente funcionam como wrappers em torno da API JSON do Cloud Storage.

C++

As funções em storage::Client têm um comportamento diferente:

Por predefinição, o UploadFile() faz um carregamento retomável quando o objeto tem mais de 20 MiB. Caso contrário, faz um carregamento simples ou um carregamento em várias partes. Pode configurar este limite definindo MaximumSimpleUploadsSizeOption quando cria um storage::Client.

8 MiB é o tamanho do buffer predefinido, que pode modificar com a opção UploadBufferSizeOption.

A biblioteca de cliente C++ usa um tamanho de buffer igual ao tamanho do fragmento. O tamanho do buffer tem de ser um múltiplo de 256 KiB (256 x 1024 bytes). Quando usar o WriteObject() e o UploadFile(), recomendamos que considere os compromissos entre a velocidade de carregamento e a utilização de memória. A utilização de pequenos buffers para carregar objetos grandes pode tornar o carregamento lento. Para mais informações sobre a relação entre a velocidade de carregamento e o tamanho do buffer para C++, consulte a análise detalhada no GitHub.

C#

Ao carregar, a biblioteca de cliente C# realiza sempre carregamentos retomáveis. Pode iniciar um carregamento retomável com CreateObjectUploader.

A biblioteca de cliente C# usa um tamanho da memória intermédia igual ao tamanho do fragmento. O tamanho do buffer predefinido é de 10 MB e pode alterar este valor definindo ChunkSize em UploadObjectOptions. O tamanho do buffer tem de ser um múltiplo de 256 KiB (256 x 1024 bytes). Normalmente, os tamanhos de buffer maiores tornam os carregamentos mais rápidos, mas tenha em atenção que existe uma compensação entre a velocidade e a utilização de memória.

Go

Por predefinição, os carregamentos retomáveis ocorrem automaticamente quando o ficheiro tem mais de 16 MiB. Altera o limite para realizar carregamentos retomáveis com Writer.ChunkSize. Os carregamentos retomáveis são sempre divididos em blocos quando usa a biblioteca de cliente Go.

Os carregamentos multipartes ocorrem quando o objeto é inferior a Writer.ChunkSize ou quando Writer.ChunkSize está definido como 0, em que a divisão em partes fica desativada. O Writer não consegue repetir pedidos se ChunkSize estiver definido como 0.

A biblioteca de cliente Go usa um tamanho de buffer igual ao tamanho do fragmento. O tamanho do buffer tem de ser um múltiplo de 256 KiB (256 x 1024 bytes). Normalmente, os tamanhos de buffer maiores tornam os carregamentos mais rápidos, mas tenha em atenção que existe uma compensação entre a velocidade e a utilização de memória. Se estiver a executar vários carregamentos retomáveis em simultâneo, deve definir Writer.ChunkSize para um valor inferior a 16 MiB para evitar o aumento excessivo da memória.

Tenha em atenção que o objeto não é finalizado no Cloud Storage até chamar Writer.Close() e receber uma resposta de êxito. Writer.Close devolve um erro se o pedido não for bem-sucedido.

Java

A biblioteca cliente Java tem métodos separados para carregamentos multipartes e retomáveis. Os seguintes métodos fazem sempre um carregamento retomável:

O tamanho da memória intermédia predefinido é de 15 MiB. Pode definir o tamanho do buffer através do método WriteChannel#setChunkSize(int) ou transmitindo um parâmetro bufferSize ao método Storage#createFrom. O tamanho da memória intermédia tem um mínimo rígido de 256 KiB. Quando chama WriteChannel#setChunkSize(int) internamente, o tamanho do buffer é alterado para um múltiplo de 256 KiB.

O armazenamento em buffer para carregamentos retomáveis funciona como um limite mínimo de descarga, em que as escritas inferiores ao tamanho do buffer são armazenadas em buffer até que uma escrita aumente o número de bytes armazenados em buffer acima do tamanho do buffer.

Se carregar quantidades mais pequenas de dados, considere usar Storage#create(BlobInfo, byte[], Storage.BlobTargetOption...) ou Storage#create(BlobInfo, byte[], int, int, Storage.BlobTargetOption...).

Node.js

Os carregamentos retomáveis ocorrem automaticamente. Pode desativar os carregamentos retomáveis definindo resumable em UploadOptions como false. Os carregamentos com opção de retomar o mesmo são geridos automaticamente quando usa o createWriteStream método.

Não existe um tamanho de buffer predefinido e os carregamentos divididos em partes têm de ser invocados manualmente definindo a opção chunkSize em CreateResumableUploadOptions. Se chunkSize for especificado, os dados são enviados em pedidos HTTP separados, cada um com um payload de tamanho chunkSize. Se não for especificado nenhum chunkSize e a biblioteca estiver a fazer um carregamento retomável, todos os dados são transmitidos numa única solicitação HTTP.

A biblioteca de cliente Node.js usa um tamanho de buffer igual ao tamanho do fragmento. O tamanho do buffer tem de ser um múltiplo de 256 KiB (256 x 1024 bytes). Normalmente, os tamanhos de buffer maiores tornam os carregamentos mais rápidos, mas tenha em atenção que existe uma compensação entre a velocidade e a utilização de memória.

PHP

Por predefinição, os carregamentos retomáveis ocorrem automaticamente quando o tamanho do objeto é superior a 5 MB. Caso contrário, ocorrem carregamentos multipartes. Não é possível alterar este limite. Pode forçar um carregamento retomável definindo a opção resumable na função upload.

A biblioteca de cliente PHP usa um tamanho de buffer igual ao tamanho do fragmento. 256 KiB é o tamanho da memória intermédia predefinido para um carregamento retomável e pode alterar o tamanho da memória intermédia definindo a propriedade chunkSize. O tamanho do buffer tem de ser um múltiplo de 256 KiB (256 x 1024 bytes). Normalmente, os tamanhos de buffer maiores tornam os carregamentos mais rápidos, mas tenha em atenção que existe uma compensação entre a velocidade e a utilização de memória.

Python

Os carregamentos retomáveis ocorrem quando o objeto tem mais de 8 MiB e os carregamentos multipartes ocorrem quando o objeto tem menos de 8 MiB. Não é possível alterar este limite. A biblioteca cliente Python usa um tamanho do buffer igual ao tamanho do fragmento. 100 MiB é o tamanho da memória intermédia predefinido usado para um carregamento retomável, e pode alterar o tamanho da memória intermédia definindo a propriedade blob.chunk_size.

Para realizar sempre um carregamento retomável, independentemente do tamanho do objeto, use a classe storage.BlobWriter ou o método storage.Blob.open(mode='w'). Para estes métodos, o tamanho da memória intermédia predefinido é de 40 MiB. Também pode usar o Resumable Media para gerir carregamentos com opção de retomar o mesmo.

O tamanho do fragmento tem de ser um múltiplo de 256 KiB (256 x 1024 bytes). Normalmente, os tamanhos dos blocos maiores tornam os carregamentos mais rápidos, mas tenha em atenção que existe uma compensação entre a velocidade e a utilização de memória.

Ruby

A biblioteca cliente Ruby trata todos os carregamentos como carregamentos retomáveis não divididos em blocos.

APIs REST

API JSON

A API JSON do Cloud Storage usa um pedido POST Object que inclui o parâmetro de consulta uploadType=resumable para iniciar o carregamento retomável. Este pedido devolve um URI de sessão que usa posteriormente num ou mais pedidos PUT Object para carregar os dados do objeto. Para um guia passo a passo sobre como criar a sua própria lógica para carregamentos retomáveis, consulte o artigo Realizar carregamentos retomáveis.

API XML

A API XML do Cloud Storage usa um pedido POST Object que inclui o cabeçalho x-goog-resumable: start para iniciar o carregamento retomável. Este pedido devolve um URI de sessão que usa posteriormente num ou mais pedidos PUT Object para carregar os dados do objeto. Para um guia passo a passo sobre como criar a sua própria lógica para carregamentos retomáveis, consulte o artigo Realizar carregamentos retomáveis.

Carregamentos retomáveis de tamanho desconhecido

O mecanismo de carregamento retomável suporta transferências em que o tamanho do ficheiro não é conhecido antecipadamente. Isto pode ser útil para casos como comprimir um objeto em tempo real durante o carregamento, uma vez que é difícil prever o tamanho exato do ficheiro para o ficheiro comprimido no início de uma transferência. Este mecanismo é útil se quiser transmitir uma transferência que possa ser retomada após ser interrompida ou se a codificação de transferência segmentada não funcionar para a sua aplicação.

Para mais informações, consulte o artigo Carregamentos de streaming.

Desempenho do carregamento

Escolher regiões de sessão

Os carregamentos retomáveis são fixados na região onde os inicia. Por exemplo, se iniciar um carregamento retomável nos EUA e fornecer o URI da sessão a um cliente na Ásia, o carregamento continua a ser feito através dos EUA. Para reduzir o tráfego entre regiões e melhorar o desempenho, deve manter uma sessão de carregamento retomável na região em que foi criada.

Se usar uma instância do Compute Engine para iniciar um carregamento com opção de retomar o mesmo, a instância deve estar na mesma localização que o contentor do Cloud Storage para o qual carrega o conteúdo. Em seguida, pode usar um serviço de IP geográfico para escolher a região do Compute Engine para a qual encaminha os pedidos dos clientes, o que ajuda a manter o tráfego localizado numa região geográfica.

Carregar em partes

Se possível, evite dividir uma transferência em partes mais pequenas e, em vez disso, carregue todo o conteúdo numa única parte. Evitar a divisão em blocos remove os custos de latência adicionais e os encargos de operações da consulta do desvio persistente de cada bloco, bem como melhora o débito. No entanto, deve considerar carregar em partes quando:

  • Os dados de origem estão a ser gerados dinamicamente e quer limitar a quantidade de dados que tem de armazenar no lado do cliente caso o carregamento falhe.

  • Os seus clientes têm limitações de tamanho dos pedidos, como acontece com muitos navegadores.

Se estiver a usar a API JSON ou XML e o seu cliente receber um erro, pode consultar o servidor para obter o desvio persistente e retomar o carregamento dos bytes restantes a partir desse desvio. A Google Cloud consola, a Google Cloud CLI e as bibliotecas de cliente processam esta ação automaticamente em seu nome. Consulte o artigo Como as ferramentas e as APIs usam carregamentos retomáveis para obter mais orientações sobre a divisão em blocos para bibliotecas cliente específicas.

Considerações

Esta secção é útil se estiver a criar o seu próprio cliente que envia pedidos de carregamento retomáveis diretamente para a API JSON ou XML.

URIs de sessão

Quando inicia um carregamento retomável, o Cloud Storage devolve um URI de sessão, que usa em pedidos subsequentes para carregar os dados reais. Um exemplo de um 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 um URI de sessão na API XML é:

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

Este URI de sessão funciona como um token de autenticação, pelo que os pedidos que o usam não precisam de ser assinados e podem ser usados por qualquer pessoa para carregar dados para o contentor de destino sem autenticação adicional. Por este motivo, seja criterioso ao partilhar o URI da sessão e partilhe-o apenas através de HTTPS.

Um URI de sessão expira após uma semana, mas pode ser cancelado antes de expirar. Se fizer um pedido com um URI de sessão que já não seja válido, recebe um dos seguintes erros:

  • Um código de estado 410 Gone se tiver passado menos de uma semana desde que o carregamento foi iniciado.
  • Um código de estado 404 Not Found se tiver passado mais de uma semana desde que o carregamento foi iniciado.

Em ambos os casos, ou se perder o URI da sessão antes de o carregamento estar concluído, tem de iniciar um novo carregamento retomável, obter um novo URI da sessão e iniciar o carregamento desde o início com o novo URI da sessão.

Verificações de integridade

Recomendamos que peça uma verificação de integridade do objeto carregado final para se certificar de que corresponde ao ficheiro de origem. Pode fazê-lo calculando o resumo MD5 do ficheiro de origem e adicionando-o ao cabeçalho do pedido Content-MD5.

A verificação da integridade do ficheiro carregado é particularmente importante se estiver a carregar um ficheiro grande durante um longo período, porque existe uma maior probabilidade de o ficheiro de origem ser modificado durante a operação de carregamento.

No entanto, não pode realizar verificações de integridade em partes ou blocos intermédios de um carregamento retomável, porque os carregamentos retomáveis destinam-se a permitir que retome um carregamento caso seja interrompido inesperadamente.

Voltar a tentar e reenviar dados

Assim que o Cloud Storage persiste bytes num carregamento retomável, esses bytes não podem ser substituídos, e o Cloud Storage ignora as tentativas de o fazer. Por este motivo, não deve enviar dados diferentes quando recua para uma compensação que enviou anteriormente.

Por exemplo, suponhamos que está a carregar um objeto de 100 000 bytes e a sua ligação é interrompida. Quando verifica o estado, descobre que 50 000 bytes foram carregados e mantidos com êxito. Se tentar reiniciar o carregamento no byte 40 000, o Cloud Storage ignora os bytes que enviar de 40 000 a 50 000. O Cloud Storage começa a persistir os dados que envia no byte 50 001.

O que se segue?