Para validar a integridade de dados e detectar mudanças, o Cloud Storage recomenda o uso de somas de verificação ao transferir dados de e para seus buckets. Esta página fornece informações sobre como as somas de verificação são usadas no Cloud Storage e como especificá-las ao enviar solicitações.
Evitar a corrupção de dados usando somas de verificação
Os dados podem ser corrompidos durante a transferência de ou para a nuvem devido a bugs de software ou hardware, erros de memória ou roteador, distúrbios elétricos ou mudanças nos dados de origem durante uploads de arquivos de período estendido.
Para ajudar a proteger contra a corrupção de dados, o Cloud Storage oferece suporte ao uso de somas de verificação CRC32C e MD5 para verificar a integridade dos dados e detectar mudanças neles.
O CRC32C é o método de validação recomendado para realizar verificações de integridade. A validação usando hashes MD5 é compatível com uploads de arquivo único, mas não é compatível com objetos enviados em partes, como objetos compostos e objetos enviados usando um upload de várias partes da API XML.
Somas de verificação para gravações de dados
Para gravações de objetos, o cliente calcula o checksum do arquivo local e o anexa aos cabeçalhos HTTP da solicitação de upload do objeto. O servidor
recebe o payload de dados, calcula a própria soma de verificação e
valida os dados comparando as duas somas de verificação após a conclusão do upload.
Se as somas de verificação corresponderem, o objeto será armazenado no Cloud Storage com as somas de verificação. Se as somas de verificação não corresponderem, a solicitação de gravação será rejeitada com um erro BadRequestException: 400.
Validação do lado do servidor para gravações de dados
O Cloud Storage realiza a validação do lado do servidor nos seguintes casos:
Quando você fornece o hash MD5 ou CRC32C de um objeto em uma solicitação de upload de objeto. Para saber mais sobre os tipos de uploads de objetos, consulte Uploads de objetos.
Quando você faz uma solicitação de cópia ou regravação no Cloud Storage. Para solicitações de cópia e regravação de objetos, o Cloud Storage automaticamente realiza a validação do lado do servidor com base em uma soma de verificação não editável armazenada com o objeto de origem.
Uploads de solicitação única (mídia) da API JSON
Para uploads de mídia da API JSON, é possível especificar somas de verificação no cabeçalho X-Goog-Hash da solicitação. Exemplo:
curl -X POST --data-binary @Desktop/dog-pic.jpeg \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: image/jpeg" \
-H "X-Goog-Hash: crc32c=n03x6A==" \
"https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=media&name=dog-pic.jpeg"Uploads de várias partes da API JSON
Para uploads de várias partes da API JSON, é possível especificar somas de verificação como parte do contêiner de solicitação, na seção de metadados do objeto ou em uma terceira string de limite. Para mais detalhes sobre a estrutura JSON e as chaves válidas de um objeto, consulte a representação do recurso de objetos.
O exemplo a seguir especifica um checksum CRC32C na parte de metadados do objeto de um contêiner de solicitação:
--separator_string
Content-Type: application/json; charset=UTF-8
{
"name":"my-document.txt",
"crc32c": "n03x6A=="
}
--separator_string
Content-Type: text/plain
This is a text file.
--separator_string--
O exemplo a seguir especifica um checksum CRC32C na terceira string de limite de um contêiner de solicitação:
--separator_string
Content-Type: application/json; charset=UTF-8
{
"name":"my-document.txt"
}
--separator_string
Content-Type: text/plain
This is a text file.
--separator_string
Content-Type: application/json; charset=UTF-8
{ "crc32c": "n03x6A==" }
--separator_string--
Uploads retomáveis da API JSON
Para uploads retomáveis da API JSON, é possível especificar somas de verificação no cabeçalho X-Goog-Hash da solicitação final que conclui o upload. Exemplo:
curl -i -X PUT --data-binary @Desktop/dog-pic.jpeg \
-H "Content-Length: 2000000" \
-H "X-Goog-Hash: crc32c=n03x6A==" \
"SESSION_URI"A soma de verificação especificada na solicitação final é calculada com base no objeto inteiro, não apenas nos dados do objeto na solicitação final.
Uploads de solicitação única da API XML
Para uploads de solicitação única da API XML, é possível especificar somas de verificação no
x-goog-hash cabeçalho da solicitação.
Exemplo:
curl -X PUT --data-binary @Desktop/dog-pic.jpeg \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: image/jpeg" \
-H "x-goog-hash: crc32c=n03x6A==" \
"https://storage.googleapis.com/my-bucket/dog-pic.jpeg"Os uploads de solicitação única da API XML também aceitam o cabeçalho Content-MD5 HTTP padrão . Para mais detalhes, consulte a especificação Content-MD5.
Uploads de várias partes da API XML
Para uploads de várias partes da API XML, é possível especificar uma soma de verificação para cada parte do upload. Para especificar uma soma de verificação individual para uma parte do upload, inclua o
x-goog-hash cabeçalho na solicitação dessa parte específica.
Exemplo:
PUT /dog-pic.jpeg?partNumber=1&uploadId=ABgVH8 HTTP/1.1 Host: my-bucket.storage.googleapis.com Content-Length: 1000000 x-goog-hash: crc32c=n03x6A==
Somente as somas de verificação CRC32C podem ser usadas para verificar a integridade de uploads de várias partes da API XML. As somas de verificação MD5 não são aceitas.
Uploads do gRPC
Ao fazer upload de objetos usando gRPC, é possível especificar somas de verificação no nível do objeto
na primeira ou última mensagem WriteObject de qualquer solicitação de upload, seja um
upload único ou um upload retomável.
Além disso, o gRPC oferece suporte a somas de verificação por mensagem. Cada mensagem WriteObject contém blocos de dados de até 2 MiB, e cada bloco pode incluir a própria soma de verificação. É possível especificar somas de verificação por mensagem no lugar ou ao lado de uma soma de verificação no nível do objeto.
Uploads compostos paralelos
No caso de uploads compostos paralelos, é necessário realizar uma verificação de integridade para cada upload de componente e, em seguida, usar as condições prévias com a solicitação de composição de upload para proteção contra disputas. As solicitações de composição não recebem validação do lado do servidor. Portanto, é necessário realizar a validação do lado do cliente no novo objeto composto se você quiser uma verificação de integridade de ponta a ponta.
Cópias e regravações da Google Cloud CLI
Na CLI gcloud, os dados copiados de ou para um
bucket do Cloud Storage são validados automaticamente. Para comandos cp, mv e rsync, a CLI gcloud usa somas de verificação MD5 ou CRC32C para determinar se há uma diferença entre a versão de um objeto encontrado na origem e a versão encontrada no destino. Quando a soma de verificação dos dados de origem não corresponde à soma de verificação dos dados de destino, a CLI gcloud exclui a cópia inválida e gera uma mensagem de aviso.
Isso raramente acontece. Se isso acontecer, repita a operação.
Essa validação automática ocorre depois que o objeto é finalizado, e os objetos inválidos ficam visíveis por 1 a 3 segundos antes de serem identificados e excluídos. Além disso, a CLI gcloud pode ser interrompida após a conclusão do upload, mas antes de realizar a validação, deixando o objeto inválido no lugar. Esses problemas podem ser evitados ao fazer upload de
arquivos individuais para o Cloud Storage com a validação do lado do servidor,
que ocorre quando você usa a flag --content-md5 para especificar um hash MD5.
A CLI do Google Cloud ignora a flag --content-md5 para objetos que não têm um hash MD5.
Detecção de mudanças para rsync
O gcloud storage rsync comando compara somas de verificação nos seguintes
cenários para determinar se é necessário pular uma transferência:
A origem e o destino são buckets do Cloud Storage, e o objeto tem uma soma de verificação MD5 ou CRC32C em ambos os buckets.
O objeto não tem um horário de modificação do arquivo (
mtime) na origem ou destino.
Nos casos em que um objeto tem um valor mtime na origem e destino, como quando a origem e o destino são sistemas de arquivos, o comando rsync compara o tamanho de objeto e o valor mtime, em vez de usar somas de verificação. Da mesma forma, se a origem for um bucket e o destino for um sistema de arquivos local, o comando rsync usará o horário de criação do objeto de origem como substituto de mtime, e o comando não usa somas de verificação.
Se mtime e as somas de verificação não estiverem disponíveis, o rsync só vai comparar os tamanhos dos arquivos ao determinar se há uma mudança entre a versão de origem de um objeto e a versão de destino. Por exemplo, nem mtime nem as somas de verificação estão
disponíveis ao comparar objetos compostos com objetos em um provedor de nuvem
que não oferece suporte a CRC32C, porque objetos compostos não têm somas de verificação MD5.
Validação do lado do cliente para gravações de dados
É possível realizar uma validação do lado do cliente dos uploads emitindo uma solicitação para os metadados do objeto enviado, comparando o valor de hash do objeto enviado com o valor esperado e excluindo o objeto em caso de incompatibilidade. Esse método é útil se o hash MD5 ou CRC32C do objeto não for conhecido no início do upload.
A tabela a seguir contém a versão mínima de cada cliente do Cloud Storage que oferece suporte a somas de verificação de gravação de objetos.
| Cliente | Versão que oferece suporte a somas de verificação de gravação de objetos |
|---|---|
| Biblioteca de cliente C++ do Cloud Storage | 2.46 e versões mais recentes |
| Biblioteca de cliente Go do Cloud Storage | 1.60.0 e versões mais recentes |
| Biblioteca de cliente Java do Cloud Storage | 2.62 e versões mais recentes |
| Biblioteca de cliente Node.js do Cloud Storage | 7.19.0 e versões mais recentes |
| Biblioteca de cliente PHP do Cloud Storage | 1.51.0 e versões mais recentes |
| Biblioteca de cliente Python do Cloud Storage | 3.7.0 e versões mais recentes |
| Biblioteca de cliente Ruby do Cloud Storage | 1.60.0 |
| Biblioteca de cliente .NET do Cloud Storage | 2.3.0 e versões mais recentes. Recomendamos a versão 4.15.0, que oferece validação de checksum do lado do servidor. |
| conector do Cloud Storage |
|
| Cloud Storage FUSE | 3.8.0 e versões mais recentes |
| Google Cloud CLI |
Somas de verificação para leituras e downloads de dados
Para leituras e downloads de objetos, o servidor envia o objeto com a soma de verificação armazenada na resposta. O cliente calcula a própria soma de verificação do arquivo lido ou baixado com base nos bytes recebidos e compara as duas somas de verificação para verificar a integridade dos dados.
Validação do lado do cliente para leituras e downloads
Por padrão, todos os SDKs da biblioteca de cliente do Cloud Storage oferecem suporte ao cálculo de somas de verificação para downloads e leituras de objetos. A tabela a seguir contém informações sobre como desativar as somas de verificação de download ou leitura de objetos para cada SDK da biblioteca de cliente.
| Biblioteca de cliente | Instruções para desativar as somas de verificação de leitura ou download de objetos |
|---|---|
| Biblioteca de cliente C++ do Cloud Storage | Na biblioteca de cliente C++, desative a verificação de soma de verificação definindo DownloadChecksumValidationOption como o valor
ChecksumAlgorithm::kNone. |
| Biblioteca de cliente Go do Cloud Storage | Na biblioteca de cliente Go, desative a verificação de checksum por fornecendo opções de leitor na inicialização. Transmita
WithDisableReaderChecksum() ao chamar
NewReader ou transmita WithDisableMRDReadChecksum()
ao chamar NewMultiRangeDownloader. |
| Biblioteca de cliente Java do Cloud Storage | Para desativar a validação interna da soma de verificação CRC32C em caminhos de leitura na
biblioteca de cliente Java, transmita a propriedade do sistema JVM
-Dcom.google.cloud.storage.Hasher.read=disabled, que desativa
o hasher interno para leituras. Se você quiser desativar a soma de verificação
globalmente em leituras e gravações, use
-Dcom.google.cloud.storage.Hasher.default=disabled em vez disso.
|
| Biblioteca de cliente Node.js do Cloud Storage | Na biblioteca de cliente Node.js, desative a validação de checksum transmitindo { validation: false } no objeto de opção de configuração fornecido para chamadas de método de download. |
| Biblioteca de cliente PHP do Cloud Storage | Na biblioteca de cliente PHP, desative a validação de checksum em caminhos de leitura da API JSON e API XML transmitindo 'validate' => false ou 'validate' => 'none' dentro da matriz de opções associativas ($options['validate']) ao chamar métodos de download. |
| Biblioteca de cliente Python do Cloud Storage | Na biblioteca de cliente Python, a desativação da verificação de checksum depende do transporte do cliente: para o cliente JSON, transmita checksum=None (com suporte em métodos como download_to_file), enquanto para o cliente gRPC, defina enable_checksum=False. |
| Biblioteca de cliente Ruby do Cloud Storage | Na biblioteca de cliente Ruby, desative a verificação de checksum transmitindo argumentos de palavra-chave (checksum: ou verify:) diretamente para métodos de download, definindo especificamente verify: none ou verify: false. |
| Biblioteca de cliente .NET do Cloud Storage | Na biblioteca de cliente .NET, desative a verificação de checksum definindo a ChecksumValidation propriedade como DownloadValidationMode.Never no DownloadObjectOptions objeto transmitido para chamadas de método de download. |
Como realizar verificações de integridade de dados em objetos baixados ou lidos
Em alguns casos, o aplicativo pode precisar calcular de forma independente a soma de verificação do arquivo baixado ou lido usando os bytes recebidos e compará-lo com o hash fornecido pelo servidor para verificar a integridade dos dados.
Para realizar uma verificação de integridade dos dados baixados, calcule o checksum à medida que os dados são recebidos e compare os resultados com o checksum fornecido pelo servidor.
As somas de verificação do lado do servidor são baseadas no objeto completo, já que são armazenadas no Cloud Storage. Isso significa que os seguintes tipos de downloads não podem ser validados em relação às somas de verificação fornecidas pelo servidor:
Downloads que passam por transcodificação descompressiva: a soma de verificação fornecida pelo servidor representa o objeto em seu estado compactado, enquanto a compactação dos dados veiculados é removida e, consequentemente, já um valor de soma de verificação diferente.
Uma resposta que contém somente uma parte dos dados do objeto: esse tipo de resposta ocorre para
Rangesolicitações.As leituras de intervalo do gRPC são uma exceção a esse marcador e oferecem suporte à validação de ponta a ponta. Nas leituras de intervalo do gRPC, o Cloud Storage valida os dados incluindo uma soma de verificação CRC32C exclusiva em cada bloco de resposta individual de um stream, o que permite que o cliente verifique instantaneamente se o bloco específico de dados não foi corrompido durante a transferência. Para uma validação mais ampla, o stream também fornece a soma de verificação completa de todo o objeto, que clientes avançados podem usar para calcular um total contínuo e verificar a integridade do arquivo maior.
Se o aplicativo precisar ler intervalos de objetos em vez de objetos completos de uma só vez, recomendamos o uso do gRPC. Caso contrário, recomendamos o uso de solicitações de intervalo apenas para reiniciar a transferência de um objeto inteiro após o último deslocamento recebido, em que é possível calcular e validar o checksum após a conclusão da transferência.
Ao validar o download, uma incompatibilidade entre a soma de verificação calculada e a soma de verificação fornecida pelo servidor indica que os dados foram corrompidos durante a transferência. Nesses casos, descarte os dados corrompidos e use a lógica de repetição recomendada para repetir a solicitação.
A seguir
- Saiba mais sobre uploads de objetos e downloads de objetos em Cloud Storage.
- Aprenda mais sobre estratégias de repetição do Cloud Storage.