哈希值和 ETag:最佳做法

Cloud Storage 建议您验证传入/传出存储桶的数据。本页面介绍使用 CRC32C 或 MD5 校验和执行验证的最佳实践。

使用哈希值来防止数据损坏

上传到云中或从云中下载时,存在多种方法可以造成数据损坏:

  • 客户端或服务器计算机或路径上的路由器发生的内存错误
  • 软件错误(例如,客户使用的库中发生软件错误)
  • 上传时间较长时更改源文件

Cloud Storage 支持两种类型的哈希值,供您检查数据的完整性:CRC32C 和 MD5。CRC32C 是执行完整性检查的推荐验证方法。偏好 MD5 的客户可以使用该哈希值,但 MD5 哈希值不适用于复合对象或通过 XML API 分段上传创建的对象。

CRC32C

所有 Cloud Storage 对象都具有 CRC32C 哈希值。用于计算 CRC32C 的库包括:

Base64 编码的 CRC32C 采用大端序字节顺序。

MD5

Cloud Storage 支持对符合以下条件的对象使用 MD5 哈希:

此哈希值仅适用于完整对象,因此不能对部分下载(因执行范围 GET 请求而导致)执行完整性检查。

ETag

如果满足以下所有条件,则对象的 ETag 标头会返回对象的 MD5 值:

在所有其他情况下,用户不应根据规范做出与在 ETag 中使用的值有关的任何假设(除非它们会随着基础数据或元数据的更改而发生更改)。

当从 XML API 请求时,同一对象可能具有与 JSON API 相比不同的 ETag 值。

验证

您可以对下载的数据动态执行哈希处理并将结果与服务器提供的哈希值进行比较,以此来执行下载完整性检查。您应丢弃具有错误哈希值的下载数据,并应使用重试逻辑来避免可能代价高昂的无限循环。

在以下情况下,Cloud Storage 会执行服务器端验证:

  • 在 Cloud Storage 中执行复制或重写请求时。

  • 在上传请求中提供对象的预期 MD5 或 CRC32C 哈希值。仅当您提供的哈希值与 Cloud Storage 计算的值匹配时,Cloud Storage 才会创建对象。 如果不匹配,请求会被拒绝并显示 BadRequestException: 400 错误。

或者,用户可以选择通过如下方法执行其上传的客户端验证:针对上传的对象的元数据发出请求,比较报告的哈希值,并在不匹配的情况下删除对象。如果在上传开始时不知道对象的 MD5 或 CRC32C 哈希值,则此方法很有用。为避免出现竞态条件(导致独立进程删除或替换彼此的数据),请使用对象世代和前提条件

在进行并行复合上传时,用户应对上传的每个组件执行完整性检查,然后在合成请求中使用组件前提条件来防止出现竞争条件。对象合成功能不提供服务器端 MD5 验证,因此,希望执行端到端完整性检查的用户应将客户端验证应用于新的复合对象。

XML API

在 XML API 中,系统通过 x-goog-hash 标头展示并接受 base64 编码的 MD5 和 CRC32C 哈希值。在过去,MD5 用作对象的 ETag,但用户应避免做出这种假设,因为一些对象将使用不透明的 ETag 值,这些值无法保证在对象更改时也会发生更改。

您可以通过 x-goog-hash 请求标头提供本地计算的哈希值,以便执行服务器端上传验证。此外,您可以使用标准 HTTP Content-MD5 标头提供 MD5(请参阅规范)。

JSON API

在 JSON API 中,对象资源 md5Hashcrc32c 属性分别包含 base64 编码的 MD5 和 CRC32C 哈希值。您可以选择提供任意一种元数据属性。在可续传上传或 JSON API 分段上传中提供任意一种属性后,会为新对象触发服务器端验证。如果 Cloud Storage 为任一属性计算出的值与提供的值不匹配,则不会创建该对象。如果没有在上传中提供这些属性,Cloud Storage 会计算这些值并将其写入对象的元数据。

Google Cloud CLI

对于 Google Cloud CLI,系统会验证复制到 Cloud Storage 存储桶或从其中复制的数据。这适用于 cpmvrsync 命令。如果源数据的校验和与目标数据的校验和不匹配,则 gcloud CLI 会删除无效副本并输出一条警告消息。很少发生这种情况。如果发生这种情况,您应重试操作。

此自动验证操作发生在对象本身最终确定之后,因此无效对象在被识别和删除之前可显示 1-3 秒钟。此外,gcloud CLI 可能会在上传完成之后但在执行验证之前被中断,使无效对象保留下来。使用服务器端验证将单个文件上传到 Cloud Storage 时可避免这些问题,进行此操作时使用标志 --content-md5=MD5

后续步骤