Workers API リファレンス

Worker 内の R2 API は、R2 バケットを Worker にバインドして使います。書いた Worker は、ルート経由でバケットへの外部アクセスを公開したり、内部で R2 オブジェクトを操作したりできます。

R2 API には、S3 API との拡張や意味の違いがあります。S3 互換が必要な場合は、S3 互換 API の利用を検討してください。

R2 は、保存するデータ（オブジェクト）を、バケットというコンテナにまとめます。バケットは、R2 におけるパフォーマンス、スケーリング、アクセスの基本単位です。

R2 バケットを Worker にバインドするには、Wrangler ファイルに次を追加します。binding プロパティは有効な JavaScript の変数識別子に、bucket_name は R2 バケット名に更新します。

{
	"r2_buckets": [
		{
			"binding": "MY_BUCKET", // <~ valid JavaScript variable name
			"bucket_name": "<YOUR_BUCKET_NAME>"
		}
	]
}

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "<YOUR_BUCKET_NAME>"

Worker 内では、バケットのバインディングが MY_BUCKET 変数として使えます。以降は、次に説明する バケットのメソッド で操作できます。

コードに注入されるバケットバインディングオブジェクトで、次のメソッドが使えます。

たとえば、上記のバインディングでオブジェクトの PUT リクエストを発行するには、次のようにします。

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		switch (request.method) {
			case "PUT":
				await env.MY_BUCKET.put(key, request.body);
				return new Response(`Put ${key} successfully!`);

			default:
				return new Response(`${request.method} is not allowed.`, {
					status: 405,
					headers: {
						Allow: "PUT",
					},
				});
		}
	},
};

from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse

class Default(WorkerEntrypoint):
	async def fetch(self, request):
		url = urlparse(request.url)
		key = url.path[1:]

		if request.method == "PUT":
			await self.env.MY_BUCKET.put(key, request.body)
			return Response(f"Put {key} successfully!")
		else:
			return Response(
				f"{request.method} is not allowed.",
				status=405,
				headers={"Allow": "PUT"}
			)

• head (key: string): Promise<R2Object | null>

  • 指定したキーのメタデータだけを含む R2Object を取得します。キーが存在すればそのオブジェクト、存在しなければ null です。

• get (key: string, options?: R2GetOptions): Promise<R2ObjectBody | R2Object | null>

  • 指定したキーのオブジェクトメタデータと、オブジェクト本体を ReadableStream として含む R2ObjectBody を取得します。キーが存在すればそのオブジェクト、存在しなければ null です。
  • options で指定した前提条件が満たされない場合、get() は body が未定義の R2Object を返します。

• put (key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob, options?: R2PutOptions): Promise<R2Object | null>

  • 指定した value とメタデータを、関連する key の下に保存します。書き込みが成功すると、保存した Object のメタデータを含む R2Object を返します。
  • options で指定した前提条件が満たされない場合、put() は null を返し、オブジェクトは保存されません。
  • R2 の書き込みは強い一貫性があります。Promise が解決したあと、以降のすべての読み取り操作は、このキーと値のペアをグローバルに参照できます。

• delete (key: string | string[]): Promise<void>

  • 関連する keys の下にある指定の values とメタデータを削除します。削除が成功すると void を返します。
  • R2 の削除は強い一貫性があります。Promise が解決したあと、以降のすべての読み取り操作は、指定したキーと値のペアをグローバルに参照しなくなります。
  • 1 回の呼び出しで最大 1000 個のキーを削除できます。

• list (options?: R2ListOptions): Promise<R2Objects>

  • バケット内の R2Object の一覧を含む R2Objects を返します。
  • 返されるオブジェクトの一覧は辞書順です。
  • 最大 1000 件を返します。Worker 内のメモリ負荷を抑えるため、それより少ない件数になることがあります。
  • 一覧するオブジェクト数を明示するには、limit プロパティを設定した R2ListOptions オブジェクトを渡します。

• createMultipartUpload (key: string, options?: R2MultipartOptions): Promise<R2MultipartUpload>

  • マルチパートアップロードを作成します。
  • 新しく作成したマルチパートアップロードを表す R2MultipartUpload オブジェクトに解決する Promise を返します。作成後は、Workers API または S3 API 経由で、すぐにグローバルに操作できます。

• resumeMultipartUpload (key: string, uploadId: string): R2MultipartUpload

  • 指定したキーと uploadId のマルチパートアップロードを表すオブジェクトを返します。
  • resumeMultipartUpload 操作は、uploadId の妥当性や、対応するアクティブなマルチパートアップロードの存在を検証しません。これは、R2MultipartUpload オブジェクトに対する後続操作をすぐ呼べるように、レイテンシを抑えるためです。

R2Object は、R2 バケットにオブジェクトを PUT したときに作成されます。R2Object は、アップローダーが提供した情報に基づくオブジェクトのメタデータを表します。R2 バケットに PUT したすべてのオブジェクトに、R2Object が作成されます。

• key string

  • オブジェクトのキーです。

• version string

  • キーの特定のアップロードに紐づく、ランダムな一意の文字列です。

• size number

  • オブジェクトのサイズ（バイト）です。

• etag string

• オブジェクトのアップロードに紐づく etag です。

• httpEtag string

  • ヘッダーとして返すために引用符で囲んだ、オブジェクトの etag です。

• uploaded Date

  • オブジェクトがアップロードされた時刻を表す Date オブジェクトです。

• httpMetadata R2HTTPMetadata

  • オブジェクトに紐づく各種 HTTP ヘッダーです。HTTP Metadata を参照してください。

• customMetadata Record<string, string>

  • オブジェクトに紐づく、ユーザー定義のカスタムメタデータのマップです。

• range R2Range 任意

  • 返されたオブジェクトの範囲を含む R2Range オブジェクトです。

• checksums R2Checksums

  • オブジェクトに保存されているチェックサムを含む R2Checksums オブジェクトです。checksums を参照してください。

• writeHttpMetadata (headers: Headers): void

  • R2Object から httpMetadata を取り出し、対応する HTTP ヘッダーを入力の Headers オブジェクトに適用します。HTTP Metadata を参照してください。

• storageClass 'Standard' | 'InfrequentAccess'

  • オブジェクトに紐づくストレージクラスです。Storage Classes を参照してください。

• ssecKeyMd5 string 任意

  • 暗号化に使った SSE-C キーの、16 進数エンコードした MD5 ハッシュです（キーを指定した場合）。ハッシュは、オブジェクトの復号に必要なキーの識別に使えます。

R2ObjectBody は、オブジェクトのメタデータと本体を合わせたものです。R2 バケットからオブジェクトを GET したときに返されます。R2ObjectBody のキーの完全な一覧は、次の一覧に加え、R2Object から継承するすべてのキーです。

• body ReadableStream

  • オブジェクトの値です。

• bodyUsed boolean

  • オブジェクトの値が消費済みかどうかです。

• arrayBuffer (): Promise<ArrayBuffer>

  • オブジェクトの値を含む ArrayBuffer に解決する Promise を返します。

• text (): Promise<string>

  • オブジェクトの値を含む文字列に解決する Promise を返します。

• json <T>() : Promise<T>

  • オブジェクトの値を含む指定のオブジェクトに解決する Promise を返します。

• blob (): Promise<Blob>

  • オブジェクトの値を含むバイナリの Blob に解決する Promise を返します。

R2MultipartUpload オブジェクトは、createMultipartUpload または resumeMultipartUpload を呼び出したときに作成されます。R2MultipartUpload は、進行中のマルチパートアップロードを表します。

未完了のマルチパートアップロードは、7 日後に自動で中止されます。

• key string

  • マルチパートアップロードの key です。

• uploadId string

  • マルチパートアップロードの uploadId です。

• uploadPart (partNumber: number, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob, options?: R2MultipartOptions): Promise<R2UploadedPart>

  • 指定したパート番号で、このマルチパートアップロードに 1 つのパートをアップロードします。各パートのサイズは揃える必要があります。最後のパートだけ、小さくできます。
  • etag と partNumber を含む R2UploadedPart オブジェクトを返します。これらの R2UploadedPart オブジェクトは、マルチパートアップロードを完了するときに必要です。

• abort (): Promise<void>

  • マルチパートアップロードを中止します。アップロードの中止が成功したときに解決する Promise を返します。

• complete (uploadedParts: R2UploadedPart[]): Promise<R2Object>

  • 指定したパートでマルチパートアップロードを完了します。
  • 完了操作が終わったときに解決する Promise を返します。完了後、オブジェクトは以降の読み取り操作からすぐにグローバルにアクセスできます。

• onlyIf R2Conditional | Headers

  • R2Conditional または条件付き Headers の特定条件を満たす場合にだけ、オブジェクトを返すように指定します。条件付き操作 を参照してください。

• range R2Range | Headers 任意

  • R2Range または range の Headers で指定した範囲に従い、オブジェクトの特定の長さ（任意のオフセットから）または末尾のバイトだけを返すように指定します。範囲読み取り を参照してください。

• ssecKey ArrayBuffer | string

  • SSE-C に使うキーを指定します。キーは 32 バイトで、16 進数エンコードした文字列または ArrayBuffer の形式である必要があります。

R2GetOptions は range パラメーターを受け取り、body で返すデータを制限できます。

範囲で使える引数のバリエーションは次の 3 つです。

• オフセットと、任意の長さ。

• 任意のオフセットと、長さ。

• サフィックス。

• offset number

  • データの返却を開始するバイト位置です（この位置を含みます）。

• length number

  • 返すバイト数です。オブジェクトに存在するバイト数より多く要求した場合、この数より少ないバイト数が返ることがあります。

• suffix number

  • ファイル末尾（最後のバイト）から返すバイト数です。オブジェクトに存在するバイト数より多く要求した場合、この数より少ないバイト数が返ることがあります。

• onlyIf R2Conditional | Headers

  • R2Conditional の特定条件を満たす場合にだけ、オブジェクトを保存するように指定します。条件付き操作 を参照してください。

• httpMetadata R2HTTPMetadata | Headers 任意

  • オブジェクトに紐づく各種 HTTP ヘッダーです。HTTP Metadata を参照してください。

• customMetadata Record<string, string> 任意

  • オブジェクトと一緒に保存する、ユーザー定義のカスタムメタデータのマップです。

• md5 ArrayBuffer | string 任意

  • 受信したオブジェクトの整合性を確認するための md5 ハッシュです。

• sha1 ArrayBuffer | string 任意

  • 受信したオブジェクトの整合性を確認するための SHA-1 ハッシュです。

• sha256 ArrayBuffer | string 任意

  • 受信したオブジェクトの整合性を確認するための SHA-256 ハッシュです。

• sha384 ArrayBuffer | string 任意

  • 受信したオブジェクトの整合性を確認するための SHA-384 ハッシュです。

• sha512 ArrayBuffer | string 任意

  • 受信したオブジェクトの整合性を確認するための SHA-512 ハッシュです。

• storageClass 'Standard' | 'InfrequentAccess'

  • 指定した場合、オブジェクトのストレージクラスを設定します。指定しない場合、バケットに紐づくデフォルトのストレージクラスに保存されます。Storage Classes を参照してください。

• ssecKey ArrayBuffer | string

  • SSE-C に使うキーを指定します。キーは 32 バイトで、16 進数エンコードした文字列または ArrayBuffer の形式である必要があります。

• httpMetadata R2HTTPMetadata | Headers 任意

  • オブジェクトに紐づく各種 HTTP ヘッダーです。HTTP Metadata を参照してください。

• customMetadata Record<string, string> 任意

  • オブジェクトと一緒に保存する、ユーザー定義のカスタムメタデータのマップです。

• storageClass string

  • 指定した場合、オブジェクトのストレージクラスを設定します。指定しない場合、バケットに紐づくデフォルトのストレージクラスに保存されます。Storage Classes を参照してください。

• ssecKey ArrayBuffer | string

  • SSE-C に使うキーを指定します。キーは 32 バイトで、16 進数エンコードした文字列または ArrayBuffer の形式である必要があります。

• limit number 任意

  • 返す結果の件数です。デフォルトは 1000、最大は 1000 です。

  • include を設定した場合、メタデータを収めるために、レスポンスの件数が limit より少なくなることがあります。

• prefix string 任意

  • キーと照合するプレフィックスです。指定したプレフィックスで始まるキーだけが返されます。

• cursor string 任意

  • オブジェクトの一覧をどこから続けるかを示す不透明なトークンです。cursor は、以前の list 操作から取得できます。

• delimiter string 任意

  • キーをグループ化するときに使う文字です。

• include Array<string> 任意

  • httpMetadata や customMetadata を含められます。含めた場合、list が返す項目に指定したメタデータが入ります。

  • 1 回の list 操作が返せるデータ量には上限があります。データを要求すると、メタデータを収めるために、レスポンスの件数が limit より少なくなることがあります。

  • Wrangler ファイルの compatibility date を 2022-08-04 以降にする必要があります。そうでない場合は、r2_list_honor_include 互換性フラグを設定します。設定しないと、実際の include オプションに関係なく、include: ['httpMetadata', 'customMetadata'] として扱われます。

  そのため、返されたオブジェクト数を limit と比較しないように注意してください。代わりに、truncated プロパティで list リクエストに続きがあるかを判断します。

const options = {
	limit: 500,
	include: ["customMetadata"],
};

const listed = await env.MY_BUCKET.list(options);

let truncated = listed.truncated;
let cursor = truncated ? listed.cursor : undefined;

// ❌ - if your limit can't fit into a single response or your
// bucket has less objects than the limit, it will get stuck here.
while (listed.objects.length < options.limit) {
	// ...
}

// ✅ - use the truncated property to check if there are more
// objects to be returned
while (truncated) {
	const next = await env.MY_BUCKET.list({
		...options,
		cursor: cursor,
	});
	listed.objects.push(...next.objects);

	truncated = next.truncated;
	cursor = next.cursor;
}

limit = 500
include = ["customMetadata"]

listed = await self.env.MY_BUCKET.list(limit=limit, include=include)

truncated = listed.truncated
cursor = listed.cursor if truncated else None

# ❌ - if your limit can't fit into a single response or your
# bucket has less objects than the limit, it will get stuck here.
while len(listed.objects) < limit:
    ...

# ✅ - use the truncated property to check if there are more
# objects to be returned
while truncated:
    next_page = await self.env.MY_BUCKET.list(limit=limit, include=include, cursor=cursor)
    listed.objects.extend(next_page.objects)

    truncated = next_page.truncated
    cursor = next_page.cursor

BUCKET_BINDING.list() が返す、R2Object 配列を含むオブジェクトです。

• objects Array<R2Object>

  • list リクエストに一致するオブジェクトの配列です。

• truncated boolean

  • true の場合、現在の list リクエストに取得できる結果がまだあることを示します。

• cursor string 任意

  • その地点から一覧を再開するために、以降の list 呼び出しへ渡せるトークンです。truncated が true の場合にだけ存在します。

• delimitedPrefixes Array<string>

  • delimiter を指定した場合、指定したプレフィックスから次の delimiter 出現までのすべてのプレフィックスを含みます。

  • たとえば、プレフィックスを指定せず delimiter が '/' のとき、foo/bar/baz は区切りプレフィックスとして foo を返します。同じ構造と delimiter でプレフィックスに foo/ を渡すと、区切りプレフィックスとして foo/bar が返されます。

R2GetOptions と R2PutOptions に R2Conditional オブジェクトを渡せます。get() の条件チェックが失敗すると、本体は返されません。これにより get() のレイテンシが下がります。

put() の条件チェックが失敗すると、R2Object の代わりに null が返されます。

• etagMatches string 任意

  • オブジェクトの etag が指定した文字列と一致する場合に、操作を実行します。

• etagDoesNotMatch string 任意

  • オブジェクトの etag が指定した文字列と一致しない場合に、操作を実行します。

• uploadedBefore Date 任意

  • オブジェクトが指定した日付より前にアップロードされている場合に、操作を実行します。

• uploadedAfter Date 任意

  • オブジェクトが指定した日付より後にアップロードされている場合に、操作を実行します。

代わりに、条件付きヘッダーを含む Headers オブジェクトを R2GetOptions と R2PutOptions に渡せます。これらの条件付きヘッダーについては、条件付きリクエストに関する MDN のドキュメント ↗ を参照してください。If-Range 以外の条件付きヘッダーに対応しています。

条件付きリクエストの詳細は、RFC 7232 ↗ を参照してください。

一般に、これらのフィールドはオブジェクト作成時に渡された HTTP メタデータと一致します。GET リクエスト時に上書きでき、その場合は指定した値がレスポンスにそのまま返されます。

• contentType string 任意

• contentLanguage string 任意

• contentDisposition string 任意

• contentEncoding string 任意

• cacheControl string 任意

• cacheExpiry Date 任意

put() バインディングでチェックサムを指定した場合、返されるオブジェクトの checksums プロパティで利用できます。マルチパートでないオブジェクトでは、MD5 チェックサムがデフォルトで含まれます。

• md5 ArrayBuffer 任意

  • オブジェクトの MD5 チェックサムです。

• sha1 ArrayBuffer 任意

  • オブジェクトの SHA-1 チェックサムです。

• sha256 ArrayBuffer 任意

  • オブジェクトの SHA-256 チェックサムです。

• sha384 ArrayBuffer 任意

  • オブジェクトの SHA-384 チェックサムです。

• sha512 ArrayBuffer 任意

  • オブジェクトの SHA-512 チェックサムです。

R2UploadedPart オブジェクトは、アップロード済みのパートを表します。R2UploadedPart オブジェクトは uploadPart 操作から返され、completeMultipartUpload 操作に渡す必要があります。

• partNumber number

  • パートの番号です。

• etag string

  • パートの etag です。

R2Object が保存されるストレージクラスです。利用できるストレージクラスは Standard と InfrequentAccess です。詳細は Storage classes を参照してください。