As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Proteção da integridade de dados com somas de verificação

O Amazon Simple Storage Service (Amazon S3) oferece a capacidade de especificar uma soma de verificação ao fazer upload de um objeto. Quando você especifica uma soma de verificação, ela é armazenada com o objeto e pode ser validada quando o objeto é baixado.

As somas de verificação fornecem uma camada adicional de integridade de dados quando você transfere arquivos. Com somas de verificação, você pode verificar a consistência de dados confirmando que o arquivo recebido corresponde ao arquivo original. Consulte mais informações sobre as somas de verificação no Amazon S3 no Guia do usuário do Amazon Simple Storage Service, incluindo os algoritmos compatíveis.

Você tem a flexibilidade de escolher o algoritmo mais adequado às suas necessidades e deixar que o SDK calcule a soma de verificação. Como alternativa, você pode fornecer um valor de soma de verificação pré-computado usando um dos algoritmos compatíveis.

Discutimos somas de verificação em duas fases de solicitação: upload de um objeto e download de um objeto.

Fazer upload de um objeto

Você carrega objetos para o Amazon S3 com o SDK para Kotlin usando a função putObject com um parâmetro de solicitação. O tipo de dados da solicitação fornece a propriedade checksumAlgorithm para habilitar o cálculo da soma de verificação.

O trecho de código a seguir mostra uma solicitação para fazer upload de um objeto com uma soma de verificação CRC32. Quando o SDK envia a solicitação, ele calcula a soma de verificação CRC32 e carrega o objeto. O Amazon S3 armazena a soma de verificação com o objeto.

val request = PutObjectRequest {
    bucket = "amzn-s3-demo-bucket"
    key = "key"
    checksumAlgorithm = ChecksumAlgorithm.CRC32
}

Se você não fornecer um algoritmo de soma de verificação na solicitação, o comportamento da soma de verificação varia conforme a versão do SDK utilizado, conforme mostrado na tabela a seguir.

Comportamento da soma de verificação quando nenhum algoritmo de soma de verificação é fornecido

Usar um valor de soma de verificação pré-calculado

Um valor de soma de verificação pré-calculado fornecido com a solicitação desabilita a computação automática pelo SDK e, em vez disso, usa o valor fornecido.

O exemplo a seguir mostra uma solicitação com uma soma de SHA256 verificação pré-calculada.

val request = PutObjectRequest {
    bucket = "amzn-s3-demo-bucket"
    key = "key"
    body = ByteStream.fromFile(File("file_to_upload.txt"))
    checksumAlgorithm = ChecksumAlgorithm.SHA256
    checksumSha256 = "cfb6d06da6e6f51c22ae3e549e33959dbb754db75a93665b8b579605464ce299"
}

Se o Amazon S3 determinar que o valor da soma de verificação está incorreto para o algoritmo especificado, o serviço retornará uma resposta de erro.

Carregamentos fracionados

Você também pode usar somas de verificação com carregamentos fracionados.

Você deve especificar o algoritmo de soma de verificação na solicitação CreateMultipartUpload e em cada solicitação UploadPart. Como etapa final, você deve especificar a soma de verificação de cada parte no CompleteMultipartUpload. O exemplo a seguir mostra como criar um carregamento fracionado com o algoritmo de soma de verificação especificado.

val multipartUpload = s3.createMultipartUpload {
    bucket = "amzn-s3-demo-bucket"
    key = "key"
    checksumAlgorithm = ChecksumAlgorithm.Sha1
}

val partFilesToUpload = listOf("data-part1.csv", "data-part2.csv", "data-part3.csv")

val completedParts = partFilesToUpload
    .mapIndexed { i, fileName ->
        val uploadPartResponse = s3.uploadPart {
            bucket = "amzn-s3-demo-bucket"
            key = "key"
            body = ByteStream.fromFile(File(fileName))
            uploadId = multipartUpload.uploadId
            partNumber = i + 1 // Part numbers begin at 1.
            checksumAlgorithm = ChecksumAlgorithm.Sha1
        }

        CompletedPart {
            eTag = uploadPartResponse.eTag
            partNumber = i + 1
            checksumSha1 = uploadPartResponse.checksumSha1
        }
    }

s3.completeMultipartUpload {
    uploadId = multipartUpload.uploadId
    bucket = "amzn-s3-demo-bucket"
    key = "key"
    multipartUpload {
        parts = completedParts
    }
}

Fazer download de um objeto

Quando você usa o método getObject para baixar um objeto, o SDK valida automaticamente a soma de verificação quando a propriedade checksumMode do compilador do GetObjectRequest está definida como ChecksumMode.Enabled.

A solicitação no trecho a seguir direciona o SDK a validar a soma de verificação na resposta calculando a soma de verificação e comparando os valores.

val request = GetObjectRequest {
    bucket = "amzn-s3-demo-bucket"
    key = "key"
    checksumMode = ChecksumMode.Enabled
}

Se você usa uma versão 1.4.0 ou posterior do SDK, ele verifica automaticamente a integridade das solicitações getObject sem adicionar checksumMode = ChecksumMode.Enabled à solicitação.

Validação assíncrona

Como o SDK para Kotlin usa respostas de streaming ao baixar um objeto do Amazon S3, a soma de verificação será calculada à medida que você consome o objeto. Portanto, você deve consumir o objeto para que a soma de verificação seja validada.

O exemplo a seguir mostra como validar uma soma de verificação consumindo totalmente a resposta.

val request = GetObjectRequest {
    bucket = "amzn-s3-demo-bucket"
    key = "key"
    checksumMode = checksumMode.Enabled
}

val response = s3Client.getObject(request) {
    println(response.body?.decodeToString()) // Fully consume the object.
    // The checksum is valid.
}

Por outro lado, o código no exemplo a seguir não usa o objeto de forma alguma, então a soma de verificação não é validada.

s3Client.getObject(request) {
    println("Got the object.")
}

Se a soma de verificação calculada pelo SDK não corresponder à soma de verificação esperada enviada com a resposta, o SDK lançará uma ChecksumMismatchException.