扩展 · Cloudflare R2 docs

R2 在基本 S3 API 之上实现了一些扩展。本页概述这些额外可用功能。本页描述的部分功能需要设置自定义请求头。有关如何设置的示例，请参阅配置自定义请求头。

使用 Unicode 的扩展元数据

Workers R2 API 原生支持键和值中的 Unicode，无需对 customMetadata 字段进行额外编码或解码。这些字段映射到 R2 S3 兼容 API 端点中使用的 x-amz-meta- 前缀请求头。

HTTP 请求头名称和值只能包含 ASCII 字符，这只是 Unicode 字符库的一小部分。为便于用户使用，R2 遵循 RFC 2047 ↗，在存储前自动解码所有 x-amz-meta-* 请求头值。检索时，含 Unicode 的元数据值会在渲染响应前进行 RFC 2047 编码。元数据值的长度限制应用于解码后的 Unicode 值。

这些请求头映射到 R2 绑定（binding）中的 httpMetadata 字段：

HTTP 请求头	属性名
`Content-Encoding`	`httpMetadata.contentEncoding`
`Content-Type`	`httpMetadata.contentType`
`Content-Language`	`httpMetadata.contentLanguage`
`Content-Disposition`	`httpMetadata.contentDisposition`
`Cache-Control`	`httpMetadata.cacheControl`
`Expires`	`httpMetadata.expires`

若在对象键名中使用 Unicode，请参阅 Unicode 互操作性。

上传时自动创建存储桶

若按需创建存储桶，您可能在上传时假设目标存储桶已存在。此时若收到 NoSuchBucket 错误，通常会发起 CreateBucket 操作。但这种方式可能引发问题：若请求体已被部分消费，上传必须中止。其他对象存储提供商的常见做法是使用 HTTP 100 ↗ 响应检测是否应发送请求体，或是否须先创建存储桶再重试上传。但 Cloudflare 不支持 HTTP 100 响应。即使支持，仍会因额外往返而增加延迟。

为支持向可能尚不存在的存储桶发送流式请求体上传，PutObject 或 CreateMultipartUpload 等上传操作允许指定请求头，确保不会返回 NoSuchBucket 错误。若上传时存储桶尚不存在，将隐式实例化，并执行以下 CreateBucket 请求：

PUT / HTTP/1.1
Host: bucket.account.r2.cloudflarestorage.com
<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <LocationConstraint>auto</LocationConstraint>
</CreateBucketConfiguration>

这仅在按需创建存储桶时有用，因为您事先不知道存储桶名称或首选访问位置。例如，每个客户对应一个存储桶，存储桶在首次上传时创建而非注册时。此类情况下，支持超过 1,000 个存储桶账户的 ListBuckets 扩展也可能有用。

PutObject 和 CreateMultipartUpload

cf-create-bucket-if-missing

添加 cf-create-bucket-if-missing 请求头并设为 true，可在存储桶尚不存在时隐式创建。有关何时添加此请求头的详细说明，请参阅上传时自动创建存储桶。

CopyObject

MERGE 元数据指令

x-amz-metadata-directive 除标准 COPY 和 REPLACE 选项外，还支持 MERGE 值。使用时，MERGE 结合 COPY 和 REPLACE：从源对象 COPY 所有元数据键，并用请求中指定的新值 REPLACE 对应键。无法使用 MERGE 从源对象移除现有元数据键——请改用 REPLACE。

`ListBuckets`

ListBuckets 支持与 R2 中 ListObjectsV2 相同的所有搜索参数，因为部分客户可能拥有超过 1,000 个存储桶。由于现有 S3 库等工具可能无法设置这些搜索参数，这些值也可通过请求头传入。请求头中的值优先于搜索参数。

搜索参数	HTTP 请求头	含义
`prefix`	`cf-prefix`	仅显示具有此前缀的存储桶。
`start-after`	`cf-start-after`	显示名称在账户中按字典序排列在此之后的存储桶。
`continuation-token`	`cf-continuation-token`	从先前返回的 continuation token 继续列出。
`max-keys`	`cf-max-keys`	返回的存储桶最大数量。默认和最大值为 `1000`。

XML 响应包含 NextContinuationToken 和 IsTruncated 元素（如适用）。由于现有 S3 API 可能无法访问这些值，它们也出现在响应请求头中：

XML 响应元素	HTTP 响应请求头	含义
`IsTruncated`	`cf-is-truncated`	若返回的存储桶列表并非账户中全部存储桶，则设为 `true`。
`NextContinuationToken`	`cf-next-continuation-token`	设为 continuation token，供后续 `ListBuckets` 调用以继续列出。
`StartAfter`		请求中传入的 start-after 值。
`KeyCount`		返回的存储桶数量。
`ContinuationToken`		请求中提供的 continuation token。
`MaxKeys`		请求中指定的 max keys。

`CopyObject` 中对目标对象的条件操作

CopyObject 已通过 x-amz-copy-source-if-... 请求头支持源对象相关条件，符合 S3 API 规范。此外，R2 还支持一组 R2 专用请求头，使 CopyObject 操作可对目标对象设置条件：

cf-copy-destination-if-match
cf-copy-destination-if-none-match
cf-copy-destination-if-modified-since
cf-copy-destination-if-unmodified-since

这些请求头的工作方式类似于 PutObject 上支持的同名条件请求头。当目标对象的先前状态与指定条件不匹配时，CopyObject 操作将被拒绝并返回 412 PreconditionFailed 错误代码。

相对于 `x-amz-copy-source-if` 的非原子性

x-amz-copy-source-if-... 请求头保证在选定复制操作的源对象时进行检查，cf-copy-destination-if-... 请求头保证在对象提交到存储桶状态时进行检查。但选定源对象进行复制的时间点，与目标对象提交到存储桶状态的时间点不一定相同。因此 cf-copy-destination-if-... 请求头相对于 x-amz-copy-source-if... 请求头并非原子操作。