宣布支持Kotlin 的亚马逊云科技开发工具包中的Amazon S3校验和

我们很高兴地宣布支持Kotlin的亚马逊云科技开发工具包中的Amazon S3校验和！

校验和是根据一组数据计算得出的唯一指纹，可用于检查数据在传输过程中是否被更改或损坏。配置校验和是一项宝贵的预防措施，有助于保持数据的可靠性。

Amazon S3 是一项对象存储服务，可让您指定上传对象时使用的校验和算法或值。使用 Amazon S3 校验和，校验和将在上传和下载期间自动计算和验证。这篇文章介绍了如何在适用于 Kotlin 的亚马逊云科技开发工具包中使用此功能。

目前有四种支持的校验和算法：SHA-1、SHA-256、CRC-32 和 CRC-32C。适用于 Kotlin 的亚马逊云科技开发工具包可以在传输对象时自动计算校验和。如果您已经知道校验和，则提供预先确定的值可以帮助减少传输时客户端的计算量。

上传和下载 S3 对象时，您可以将 Amazon S3 校验和与适用于 Kotlin 的亚马逊云科技开发工具包一起使用。

上传单个对象

对象是使用 S3 的 putObject API 上传的。请求数据类型为你提供了一种启用校验和计算的方法。使用 SHA-256 校验和上传对象的请求可能如下所示：

val request = PutObjectRequest {
    bucket = "bucket"
    key = "key"
    body = ByteStream.fromFile(File("body"))
    checksumAlgorithm = ChecksumAlgorithm.SHA256
}

发送此请求时，将自动计算 SHA-256 校验和并将其应用于正在上传的对象。

使用预先确定的校验和值

提供预先确定的校验和值会禁用 SDK 的自动计算，而是使用提供的值。如果您提供的校验和不正确，则上传将失败并出现异常。

以下示例说明如何在 putObject 请求上定义校验和值：

val request = PutObjectRequest {
    bucket = "bucket"
    key = "key"
    body = ByteStream.fromFile(File("body"))
    checksumAlgorithm = ChecksumAlgorithm.SHA256
    checksumSha256 = "cfb6d06da6e6f51c22ae3e549e33959dbb754db75a93665b8b579605464ce299"
}

请注意，必须在请求中指定 checkSumAlgor tha m 和 checkSumsha256。

确保 checksumAlgorithm 指定的算法 与包含预定值的校验和属性相匹配。否则，提供的校验和将被忽略，并计算出新的校验和。

上传多部分对象

S3 提供分段上传，允许您将对象的上传拆分为多个请求。

您也可以对这些分段上传应用校验和。为此，必须在 createMultipartUpload 请求和每个 uploadPar t 请求中指定校验和算法。此外，C ompleteMultipartUpload 请求必须指定每个部分的校验和。以下是这些请求可能是什么样子的示例。

val multipartUpload = s3.createMultipartUpload {
    bucket = "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 = "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 = "bucket"
    key = "key"
    multipartUpload {
        parts = completedParts
    }
}

下载对象

S3 对象是使用 getObject API 下载的。 通过将请求中的 checksumMode 属性设置为 checks umMode.enabled，你可以在下载对象时选择进行校验和验证。

请注意，如果对象是在没有校验和的情况下上传的，则不会进行任何验证。可以在上传期间使用亚马逊云科技控制台或任何亚马逊云科技开发工具包设置校验和。

在 S3 中，可能有多个与该对象相关的校验和，但只有一个校验和会被验证。验证哪个校验和由以下优先级列表决定：CRC-32C、CRC-32、SHA-1、SHA-256。例如，如果响应同时包含 CRC-32 和 SHA-256 校验和，则只会验证 CRC-32 校验和。

val request = GetObjectRequest {
    bucket = "bucket"
    key = "key"
    checksumMode = ChecksumMode.Enabled
}

发送此请求时，适用于 Kotlin 的亚马逊云科技开发工具包将自动计算校验和，并根据 S3 返回的值进行验证。

验证响应

校验和会在您使用响应正文时进行验证，因为适用于 Kotlin 的亚马逊云科技开发工具包在从 S3 下载对象时使用流式响应。这意味着您必须使用该对象才能验证校验和。如果 校验和无效，则会抛出 checkSummisMatch Exception。以下示例显示如何通过完全使用响应来验证校验和。

val request = GetObjectRequest {
    bucket = "bucket"
    key = "key"
    checksumMode = checksumMode.Enabled
}

s3.getObject(request) {
    println(it.body?.decodeToString())
    // Checksum is valid!
}

在此示例中，响应已被完全消耗，因为 de codeToString () 会将整个正文读入一个字符串。其他完全消耗响应的可能选项包括 WriteToFile () 、tob yteArray ()，或者让 readFrom () 返回的读取器完全耗尽。

在以下示例中，校验和不会被验证，因为未以任何方式使用响应。

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

结论

在这篇博客文章中，您学习了如何通过适用于 Kotlin 的亚马逊云科技开发工具包开始使用 Amazon S3 校验和。要详细了解如何使用此功能以及适用于 Kotlin 的亚马逊云科技开发工具包的其他功能，请访问我们的开发者指南和 API 参考。如果你对如何实现该功能感到好奇，请在 GitHub 上查看其设计。如果您有疑问或遇到任何问题，请在我们的 GitHub 存储库中打开问题。

我们很想在我们的开发者调查中听到你对 SDK 和这项新功能的看法！

亚马逊云科技精选博客