拡張機能

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 バインディングの 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 バケットあり、アカウント登録時ではなく、そのバケットへの最初のアップロード時に作成する場合です。こうしたケースでは、1,000 を超えるバケットを持つアカウントにも対応する ListBuckets 拡張も役立つことがあります。

PutObject と CreateMultipartUpload

cf-create-bucket-if-missing

値が true の cf-create-bucket-if-missing ヘッダーを付けると、バケットがまだない場合に暗黙的に作成します。このヘッダーを付ける場面の詳細は、アップロード時のバケット自動作成を参照してください。

CopyObject

MERGE メタデータディレクティブ

x-amz-metadata-directive には、標準の COPY と REPLACE に加えて MERGE を指定できます。MERGE は COPY と REPLACE の組み合わせです。ソースオブジェクトのメタデータキーを COPY し、リクエストで指定したキーは新しい値で REPLACE します。MERGE でソースから既存のメタデータキーを削除することはできません。削除するには REPLACE を使います。

`ListBuckets`

R2 の ListBuckets は、ListObjectsV2 と同じ検索パラメーターをすべてサポートします。1,000 を超えるバケットを持つ顧客がいるためです。既存の S3 ライブラリなどのツールでは、これらの検索パラメーターを設定できないことがあるため、ヘッダーでも同じ値を送れます。ヘッダーの値が検索パラメーターより優先されます。

検索パラメーター	HTTP ヘッダー	意味
`prefix`	`cf-prefix`	このプレフィックスのバケットだけを表示します。
`start-after`	`cf-start-after`	辞書順で、指定した名前より後のバケットを表示します。
`continuation-token`	`cf-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`	一覧を再開するために、次の `ListBuckets` に渡す継続トークンです。
`StartAfter`		リクエストで渡された start-after の値です。
`KeyCount`		返されたバケット数です。
`ContinuationToken`		リクエストで指定された継続トークンです。
`MaxKeys`		リクエストで指定された max keys です。

`CopyObject` における宛先オブジェクトの条件付き操作

CopyObject は、S3 API 準拠の一環として、x-amz-copy-source-if-... ヘッダーでソースオブジェクトに関する条件をすでにサポートしています。これに加え、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... ヘッダーに対して原子的ではありません。