宣布支持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 和这项新功能的看法 ！