Para validar a integridade de dados e detectar mudanças, o Cloud Storage recomenda que você use checksums ao transferir dados de e para seus buckets. Nesta página, você encontra informações sobre como os checksums são usados no Cloud Storage e como especificá-los ao enviar solicitações.
Evitar a corrupção de dados usando checksums
Às vezes, os dados podem ser corrompidos durante a transferência para ou da 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 por um período prolongado.
Para ajudar a proteger contra corrupção de dados, o Cloud Storage aceita o 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 depois que o upload é concluído.
Se as somas de verificação forem iguais, 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 servidor nos seguintes casos:
Ao fornecer o hash MD5 ou CRC32C de um objeto em uma solicitação de upload. 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 reescrita de objetos, o Cloud Storage realiza automaticamente a validação do lado do servidor com base em um checksum não editável armazenado 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
checksums 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 string de limite de terceiros. Para detalhes sobre a estrutura JSON e as chaves válidas de um objeto, consulte a Representação do recurso "Objetos".
O exemplo a seguir especifica uma soma de verificação 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"O checksum especificado na solicitação final é calculado 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
cabeçalho x-goog-hash 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 um checksum CRC32C para todo o
objeto ou um checksum individual para cada parte do upload. Para especificar um checksum individual para uma parte do upload, inclua o cabeçalho x-goog-hash 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 checksums CRC32C podem ser usados para verificar a integridade de uploads de várias partes da API XML. Checksums MD5 não são compatíveis.
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 na ú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 checksums por mensagem. Cada mensagem WriteObject
contém blocos de dados de até 2 MiB, e cada bloco pode incluir o próprio
checksum. É possível especificar checksums por mensagem em vez de ou junto com um checksum no nível do objeto.
Uploads compostos paralelos
No caso de uploads compostos paralelos, execute uma verificação de integridade para cada upload de componente e use 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, realize a validação do lado do cliente no novo objeto composto se quiser uma verificação de integridade de ponta a ponta.
Cópias e reescritas da Google Cloud CLI
Na CLI gcloud, os dados copiados de ou para um bucket do Cloud Storage são validados automaticamente. Para os 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. Se a soma de verificação dos dados de origem não corresponder à soma de verificação dos dados de destino, a CLI gcloud vai excluir a cópia inválida e imprimir uma mensagem de aviso.
Isso raramente acontece. Se isso acontecer, repita a operação.
Essa validação automática ocorre após a finalização do objeto. Portanto, objetos inválidos ficam visíveis por um a três 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 ao usar 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 comando gcloud storage rsync compara somas de verificação nos seguintes
cenários para determinar se uma transferência precisa ser ignorada:
A origem e o destino são buckets do Cloud Storage, e o objeto tem um checksum 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
checksums. 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 checksums MD5.
Validação do lado do cliente para gravações de dados
Você pode realizar uma validação do lado do cliente dos seus envios 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 mostra os clientes do Cloud Storage que oferecem suporte ao cálculo de checksums para gravações de objetos por padrão, incluindo as versões de cliente que oferecem suporte a checksums.
| Cliente | Versões compatíveis com checksums |
|---|---|
| Biblioteca de cliente C++ do Cloud Storage | 2.46 e mais recentes |
| Biblioteca de cliente do Cloud Storage para Go | 1.60.0 e versões mais recentes |
| Biblioteca de cliente Java do Cloud Storage | 2.62 e mais recentes |
| Biblioteca de cliente do Cloud Storage para Node.js | 7.19.0 e versões mais recentes |
| Biblioteca de cliente do Cloud Storage para PHP | 1.51.0 e versões mais recentes |
| Biblioteca de cliente do Cloud Storage para Python | 3.7.0 e versões mais recentes |
| Biblioteca de cliente Ruby do Cloud Storage | 1.60.0 |
| Conector do Cloud Storage |
|
| Cloud Storage FUSE. | 3.8.0 e versões mais recentes |
| CLI do Google Cloud |
Checksums para leituras de dados
Para downloads de objetos, o servidor envia o objeto com o checksum armazenado na resposta. O cliente calcula a própria soma de verificação do arquivo baixado com base nos bytes recebidos e compara as duas somas de verificação para verificar a integridade dos dados.
Algumas bibliotecas de cliente não realizam automaticamente a validação de checksum em objetos baixados. Talvez seu aplicativo precise calcular de forma independente a checksum do arquivo baixado usando os bytes recebidos e compará-la com o hash fornecido pelo servidor para verificar a integridade de dados.
Validação do lado do cliente para leituras
Para realizar uma verificação de integridade dos dados baixados, calcule a soma de verificação à medida que os dados são recebidos e compare seus resultados com a soma de verificação fornecida 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 solicitações
Range.As leituras de intervalo do gRPC são uma exceção a esse item e oferecem suporte à validação de ponta a ponta. Em leituras por intervalos do gRPC, o Cloud Storage valida os dados incluindo uma soma de verificação CRC32C exclusiva em cada bloco de resposta individual de um fluxo. Isso permite que o cliente verifique instantaneamente se o bloco específico de dados não foi corrompido durante a transmissão. Para uma validação mais ampla, o stream também fornece o checksum completo 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 usar o gRPC. Caso contrário, recomendamos usar solicitações de intervalo apenas para reiniciar o download de um objeto inteiro após o último deslocamento recebido, em que é possível calcular e validar o checksum após a conclusão do download completo.
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 em trânsito. 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 no Cloud Storage.
- Saiba mais sobre estratégias de repetição do Cloud Storage.