コンテンツにスキップ

Workers API リファレンス

Worker内のR2 APIは、R2バケットをWorkerにバインドすることでアクセスされます。あなたが書いたWorkerは、ルートを介してバケットへの外部アクセスを公開したり、内部でR2オブジェクトを操作したりできます。

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

概念

R2は、オブジェクトと呼ばれるデータをバケットと呼ばれるコンテナに整理します。バケットは、R2内でのパフォーマンス、スケーリング、およびアクセスの基本単位です。

バインディングの作成

あなたのR2バケットをWorkerにバインドするには、wrangler.tomlファイルに以下を追加します。bindingプロパティを有効なJavaScript変数識別子に、bucket_nameをあなたのR2バケットの名前に更新してください：

[[r2_buckets]]
binding = 'MY_BUCKET' # <~ 有効なJavaScript変数名
bucket_name = '<YOUR_BUCKET_NAME>'

あなたのWorker内では、バケットバインディングはMY_BUCKET変数の下で利用可能になり、以下に説明するbucket methodsを使用して相互作用を開始できます。

バケットメソッド定義

以下のメソッドは、あなたのコードに注入されたバケットバインディングオブジェクトで利用可能です。

例えば、上記のバインディングを使用して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} は許可されていません。`, {
          status: 405,
          headers: {
            Allow: 'PUT',
          },
        });
    }
  },
};

  • head(keystring) : Promise<R2Object|null>

    • 指定されたキーのR2Objectを取得します。キーが存在する場合はオブジェクトメタデータのみを含み、存在しない場合はnullを返します。

  • get(keystring, optionsR2GetOptionsoptional) : Promise<R2ObjectBody|R2Object|null>

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

  • put(keystring, valueReadableStream|ArrayBuffer|ArrayBufferView|string|null|Blob, optionsR2PutOptionsoptional) : Promise<R2Object|null>

    • 指定されたvalueとメタデータを関連付けられたkeyの下に保存します。書き込みが成功すると、保存されたオブジェクトに関するメタデータを含むR2Objectを返します。
    • optionsで指定された前提条件が失敗した場合、put()はnullを返し、オブジェクトは保存されません。
    • R2の書き込みは強い整合性を持ちます。Promiseが解決されると、すべての後続の読み取り操作はこのキーと値のペアをグローバルに見ることができます。

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

    • 指定されたvaluesとメタデータを関連付けられたkeysの下で削除します。削除が成功すると、voidを返します。
    • R2の削除は強い整合性を持ちます。Promiseが解決されると、すべての後続の読み取り操作は提供されたキーと値のペアをグローバルに見ることができなくなります。

  • list(optionsR2ListOptionsoptional) : Promise<R2Objects>

    • バケット内のR2Objectのリストを含むR2Objectsを返します。
    • 返されるオブジェクトのリストは辞書順に並べられます。
    • 最大1000エントリを返しますが、Worker内のメモリ圧力を最小限に抑えるために少なくなる場合があります。
    • 明示的にリストするオブジェクトの数を設定するには、limitプロパティを設定したR2ListOptionsオブジェクトを提供します。

  • createMultipartUpload(keystring, optionsR2MultipartOptions) : Promise<R2MultipartUpload>

    • マルチパートアップロードを作成します。
    • Promiseは、新しく作成されたマルチパートアップロードを表すR2MultipartUploadオブジェクトに解決されます。マルチパートアップロードが作成されると、マルチパートアップロードはWorkers APIまたはS3 APIを介してグローバルに即座に相互作用できます。

  • resumeMultipartUpload(keystring, uploadIdstring) : R2MultipartUpload

    • 指定されたキーとuploadIdを持つマルチパートアップロードを表すオブジェクトを返します。
    • resumeMultipartUpload操作は、uploadIdの有効性を確認するためのチェックを行わず、対応するアクティブなマルチパートアップロードの存在を確認しません。これは、R2MultipartUploadオブジェクトに対する後続の操作を呼び出す前のレイテンシを最小限に抑えるために行われます。

R2Object 定義

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

  • keystring

    • オブジェクトのキー。

  • versionstring

    • 特定のキーのアップロードに関連付けられたランダムな一意の文字列。

  • sizenumber

    • オブジェクトのサイズ（バイト単位）。

  • etagstring

  • オブジェクトアップロードに関連付けられたetag。

  • httpEtagstring

    • オブジェクトのetagで、ヘッダーとして返されるように引用符で囲まれています。

  • uploadedDate

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

  • httpMetadataR2HTTPMetadata

    • オブジェクトに関連付けられたさまざまなHTTPヘッダー。詳細はHTTPメタデータを参照してください。

  • customMetadataRecord<string, string>

    • オブジェクトに関連付けられたカスタムのユーザー定義メタデータのマップ。

  • range R2Range

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

  • checksums R2Checksums

    • オブジェクトの保存されたチェックサムを含むR2Checksumsオブジェクト。詳細はチェックサムを参照してください。

  • writeHttpMetadata(headersHeaders) : void

    • R2ObjectからhttpMetadataを取得し、それに対応するHTTPヘッダーをHeaders入力オブジェクトに適用します。詳細はHTTPメタデータを参照してください。

  • storageClass”Standard”|“InfrequentAccess”

    • オブジェクトに関連付けられたストレージクラス。詳細はストレージクラスを参照してください。

R2ObjectBody 定義

R2ObjectBodyは、オブジェクトのメタデータとそのボディを組み合わせたものです。オブジェクトをR2バケットからGETしたときに返されます。R2ObjectBodyのキーの完全なリストには、以下のリストとR2Objectから継承されたすべてのキーが含まれます。

  • bodyReadableStream

    • オブジェクトの値。

  • bodyUsedboolean

    • オブジェクトの値が消費されたかどうか。

  • arrayBuffer() : Promise<ArrayBuffer>

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

  • text() : Promise<string>

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

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

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

  • blob() : Promise<Blob>

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

R2MultipartUpload 定義

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

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

  • keystring

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

  • uploadIdstring

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

  • uploadPart(partNumbernumber, valueReadableStream|ArrayBuffer|ArrayBufferView|string|Blob) : Promise<R2UploadedPart>

    • 指定されたパート番号でこのマルチパートアップロードに単一のパートをアップロードします。各パートは、最終パートが小さくなる例外を除いて、サイズが均一でなければなりません。
    • etagとpartNumberを含むR2UploadedPartオブジェクトを返します。これらのR2UploadedPartオブジェクトは、マルチパートアップロードを完了する際に必要です。

  • abort() : Promise<void>

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

  • complete(uploadedPartsR2UploadedPart[]) : Promise<R2Object>

    • 指定されたパーツでマルチパートアップロードを完了します。
    • 完了操作が終了したときに解決されるPromiseを返します。これが発生すると、オブジェクトはすぐに後続の読み取り操作によってグローバルにアクセス可能になります。

メソッド固有のタイプ

R2GetOptions

  • onlyIfR2Conditional |Headers

    • オブジェクトは、R2Conditionalまたは条件付きヘッダーの特定の条件が満たされた場合にのみ返されるべきであることを指定します。詳細は条件付き操作を参照してください。

  • rangeR2Range

    • オブジェクトから返されるべき特定の長さ（オプションのオフセットから）またはバイトのサフィックスを指定します。詳細は範囲読み取りを参照してください。

範囲読み取り

R2GetOptionsは、bodyで返されるデータを制限するために使用できるrangeパラメータを受け入れます。

範囲で使用できる引数のバリエーションは3つあります：

  • オフセットとオプションの長さ。

  • オプションのオフセットと長さ。

  • サフィックス。

  • offsetnumber

    • データの返却を開始するバイト（含む）。

  • lengthnumber

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

  • suffixnumber

    • ファイルの最後のバイトから始まる、ファイルの終わりから返却するバイト数。オブジェクトに存在するよりも多くのバイトが要求された場合、この数よりも少ないバイトが返される場合があります。

R2PutOptions

  • onlyIfR2Conditional |Headers

    • オブジェクトは、R2Conditionalの特定の条件が満たされた場合にのみ保存されるべきであることを指定します。詳細は条件付き操作を参照してください。

  • httpMetadataR2HTTPMetadata |Headersoptional

    • オブジェクトに関連付けられたさまざまなHTTPヘッダー。詳細はHTTPメタデータを参照してください。

  • customMetadataRecord<string, string>optional

    • オブジェクトと共に保存されるカスタムのユーザー定義メタデータのマップ。

  • md5ArrayBuffer |stringoptional

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

  • sha1ArrayBuffer |stringoptional

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

  • sha256ArrayBuffer |stringoptional

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

  • sha384ArrayBuffer |stringoptional

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

  • sha512ArrayBuffer |stringoptional

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

  • storageClass”Standard”|“InfrequentAccess”

    • 提供された場合、オブジェクトのストレージクラスを設定します。そうでない場合、オブジェクトはバケットに関連付けられたデフォルトのストレージクラスに保存されます。詳細はストレージクラスを参照してください。

R2MultipartOptions

  • httpMetadataR2HTTPMetadata |Headersoptional

    • オブジェクトに関連付けられたさまざまなHTTPヘッダー。詳細はHTTPメタデータを参照してください。

  • customMetadataRecord<string, string>optional

    • オブジェクトと共に保存されるカスタムのユーザー定義メタデータのマップ。

  • storageClassstring

    • 提供された場合、オブジェクトのストレージクラスを設定します。そうでない場合、オブジェクトはバケットに関連付けられたデフォルトのストレージクラスに保存されます。詳細はストレージクラスを参照してください。

R2ListOptions

  • limitnumberoptional

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

    • includeが設定されている場合、メタデータに対応するために、レスポンスでlimitよりも少ない結果を受け取ることがあります。

  • prefixstringoptional

    • キーに対して一致するプレフィックス。指定されたプレフィックスで始まるキーのみが返されます。

  • cursorstringoptional

    • オブジェクトのリストを続行する場所を示す不透明なトークン。カーソルは以前のリスト操作から取得できます。

  • delimiterstringoptional

    • キーをグループ化する際に使用する文字。

  • includeArray<string>optional

    • httpMetadataおよび/またはcustomMetadataを含めることができます。含めると、リストによって返されるアイテムには指定されたメタデータが含まれます。

    • 単一のlist操作が返すことができるデータの総量には制限があります。データをリクエストすると、メタデータに対応するために、応答でlimit結果よりも少ない結果が返される場合があります。

    • 互換性の日付は、wrangler.tomlファイルで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;


// ❌ - あなたのリミットが単一の応答に収まらない場合や、
// バケットにオブジェクトがリミットより少ない場合、ここで止まります。
while (listed.objects.length < options.limit) {
  // ...
}


// ✅ - truncatedプロパティを使用して、
// 返されるべきオブジェクトがさらにあるかどうかを確認します
while (truncated) {
  const next = await env.MY_BUCKET.list({
    ...options,
    cursor: cursor,
  });
  listed.objects.push(...next.objects);


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

R2Objects

BUCKET_BINDING.list()によって返されるR2Object配列を含むオブジェクトです。

  • objectsArray<R2Object>

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

  • truncatedboolean

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

  • cursorstringoptional

    • そのポイントからリストを再開するために将来のlist呼び出しに渡すことができるトークン。truncatedがtrueの場合のみ存在します。

  • delimitedPrefixesArray<string>

    • デリミタが指定されている場合、指定されたプレフィックスとデリミタの次の出現の間のすべてのプレフィックスを含みます。

    • 例えば、プレフィックスが提供されず、デリミタが’/‘の場合、foo/bar/bazはfooをデリミタ付きプレフィックスとして返します。foo/が同じ構造とデリミタでプレフィックスとして渡された場合、foo/barがデリミタ付きプレフィックスとして返されます。

条件付き操作

R2GetOptionsおよびR2PutOptionsにR2Conditionalオブジェクトを渡すことができます。get()の条件チェックが失敗した場合、ボディは返されません。これにより、get()のレイテンシが低くなります。

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

  • etagMatchesstringoptional

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

  • etagDoesNotMatchstringoptional

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

  • uploadedBeforeDateoptional

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

  • uploadedAfterDateoptional

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

また、条件付きヘッダーを含むHeadersオブジェクトをR2GetOptionsおよびR2PutOptionsに渡すこともできます。これらの条件付きヘッダーに関する情報は、MDNの条件付きリクエストに関するドキュメント ↗を参照してください。If-Rangeを除くすべての条件付きヘッダーがサポートされています。

条件付きリクエストに関するより具体的な情報は、RFC 7232 ↗を参照してください。

HTTPメタデータ

一般的に、これらのフィールドはオブジェクトが作成されたときに渡されたHTTPメタデータに一致します。GETリクエストを発行する際にオーバーライドすることができ、その場合、指定された値が応答にエコーされます。

  • contentTypestringoptional

  • contentLanguagestringoptional

  • contentDispositionstringoptional

  • contentEncodingstringoptional

  • cacheControlstringoptional

  • cacheExpiryDateoptional

チェックサム

put()バインディングを使用する際にチェックサムが提供された場合、それは返されたオブジェクトのchecksumsプロパティの下で利用可能です。MD5チェックサムは、マルチパートオブジェクトでない場合はデフォルトで含まれます。

  • md5 ArrayBuffer optional

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

  • sha1 ArrayBuffer optional

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

  • sha256 ArrayBuffer optional

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

  • sha384 ArrayBuffer optional

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

  • sha512 ArrayBuffer optional

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

R2UploadedPart

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

  • partNumber number

    • 部分の番号。

  • etag string

    • 部分のetag。

ストレージクラス

R2Objectが保存されるストレージクラス。利用可能なストレージクラスはStandardとInfrequentAccessです。詳細については、ストレージクラスを参照してください。

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings