Validação de dados e detecção de mudanças com checksums

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 longo período.

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 a soma de verificação do arquivo local e a 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:

• Ao fornecer 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.s3nsapis.fr/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 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 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 uma soma de verificação 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 após a finalização do objeto. 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 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 mostra os clientes no Cloud Storage que oferecem suporte ao cálculo de somas de verificação para gravações de objetos por padrão, incluindo as versões de cliente que oferecem suporte a somas de verificação.

Somas de verificação para leituras de dados

Para 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 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 da soma de verificação em objetos baixados. Seu aplicativo pode precisar calcular de forma independente a soma de verificação 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 os 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 Range solicitações.

  As leituras com intervalo do gRPC são uma exceção a esse marcador e oferecem suporte à validação de ponta a ponta. Em leituras com 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 transmissão. 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 o download de um objeto inteiro após o último deslocamento recebido, em que é possível calcular e validar a soma de verificação após a conclusão do download.

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 transmissão. 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.
• Saiba mais sobre estratégias de repetição do Cloud Storage.