拡張機能

R2は基本的なS3 APIの上にいくつかの拡張機能を実装しています。このページでは、これらの追加機能について概説します。このページで説明されている機能の一部は、カスタムヘッダーの設定を必要とします。設定方法の例については、カスタムヘッダーの設定を参照してください。

Unicodeを使用した拡張メタデータ

Workers R2 APIは、customMetadataフィールドに対して追加のエンコーディングやデコーディングを必要とせず、キーと値にUnicodeをネイティブにサポートしています。これらのフィールドは、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レスポンスをサポートしていません。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

cf-create-bucket-if-missingヘッダーを値trueで追加すると、バケットがまだ存在しない場合に暗黙的に作成されます。このヘッダーを追加するタイミングについての詳細な説明は、アップロード時のバケット自動作成を参照してください。

PutObject

`PutObject`における条件付き操作

PutObjectは、If-Match ↗、If-None-Match ↗、If-Modified-Since ↗、およびIf-Unmodified-Since ↗ヘッダーを介して条件付きアップロード ↗をサポートしています。これらのヘッダーは、書き込まれるオブジェクトの前の状態が指定された条件と一致しない場合、PutObject操作が412 PreconditionFailedエラーコードで拒否される原因となります。

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`	以前に返された継続トークンからリストを再開します。
`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`		リクエストで指定された最大キーです。

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

CopyObjectは、S3 APIへの準拠の一環として、x-amz-copy-source-if-...ヘッダーを介してソースオブジェクトに関連する条件をすでにサポートしています。これに加えて、R2は宛先オブジェクトに対してCopyObject操作を条件付きにするためのR2特有のヘッダーセットをサポートしています：

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...ヘッダーに対して原子的でないことを意味します。

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings