cloudflare-r2

Cloudflare R2 オブジェクトストレージ

ステータス：本番環境で利用可能 ✅ | 最終確認日：2025-12-27 | v3.0.0

目次：クイックスタート • 新機能 • R2 Workers API の基本 • 重要なルール • エージェントとコマンド • リファレンス

---

クイックスタート（5 分）

1. R2 バケットを作成する

bunx wrangler r2 bucket create my-bucket

**バケット名の規則：**3～63 文字で、小文字、数字、ハイフンのみ使用できます。

2. バインディングを設定する

wrangler.jsonc に追加します：

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",          // env.MY_BUCKET
      "bucket_name": "my-bucket",      // Actual bucket
      "preview_bucket_name": "my-bucket-preview"  // Optional: dev bucket
    }
  ]
}

重要：binding はコードからアクセスする際の名前、bucket_name は実際の R2 バケット名です。

3. 基本的なアップロード／ダウンロード

import { Hono } from 'hono';

type Bindings = {
  MY_BUCKET: R2Bucket;
};

const app = new Hono<{ Bindings: Bindings }>();

// Upload
app.put('/upload/:filename', async (c) => {
  const filename = c.req.param('filename');
  const body = await c.req.arrayBuffer();

  const object = await c.env.MY_BUCKET.put(filename, body, {
    httpMetadata: {
      contentType: c.req.header('content-type') || 'application/octet-stream',
    },
  });

  return c.json({
    success: true,
    key: object.key,
    size: object.size,
  });
});

// Download
app.get('/download/:filename', async (c) => {
  const object = await c.env.MY_BUCKET.get(c.req.param('filename'));

  if (!object) {
    return c.json({ error: 'Not found' }, 404);
  }

  return new Response(object.body, {
    headers: {
      'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream',
      'ETag': object.httpEtag,
    },
  });
});

export default app;

セットアップの全手順については、references/setup-guide.md を読み込んでください。

---

R2 の新機能（2025 年）

🆕 R2 SQL 統合 - 分散 SQL を使って CSV／Parquet／JSON データをクエリできます。ETL なしで分析できます。references/r2-sql-integration.md を読み込んでください。

🆕 データカタログ（Apache Iceberg） - テーブルのバージョン管理、過去の時点を指定したクエリ、スキーマの進化に対応します。Spark／Snowflake と統合できます。references/data-catalog-iceberg.md を読み込んでください。

🆕 イベント通知 - オブジェクトの変更（アップロード／削除）をトリガーとして Workers を実行します。画像処理、バックアップ、Webhook を自動化できます。references/event-notifications.md を読み込んでください。

高度な機能 - ストレージクラス、バケットロック（コンプライアンス対応）、tus による再開可能なアップロード、SSE-C 暗号化に対応します。references/advanced-features.md を読み込んでください。

ゼロトラストセキュリティ - SSO、MFA、ID ポリシー、監査ログを備えた Cloudflare Access との統合に対応します。references/cloudflare-access-integration.md を読み込んでください。

パフォーマンスの調整 - キャッシュ戦略、圧縮、範囲リクエスト、ETag、監視のベストプラクティスについて説明します。references/performance-optimization.md を読み込んでください。

---

R2 Workers API の基本 - クイックリファレンス

put() - オブジェクトをアップロードする

await env.MY_BUCKET.put(key, data, options?)

メタデータを付けてアップロードし、onlyIf を使って上書きを防止できます。R2PutOptions の全項目については、references/workers-api.md を読み込んでください。

get() - オブジェクトをダウンロードする

const object = await env.MY_BUCKET.get(key, options?)

R2ObjectBody | null を返します。範囲リクエストや条件付き操作に対応しています。読み取りメソッド（text()、json()、arrayBuffer()、blob()）については、references/workers-api.md を読み込んでください。

head() - メタデータのみを取得する

const object = await env.MY_BUCKET.head(key)

本文をダウンロードせずに、存在の確認やサイズ、etag、メタデータの取得ができます。検証やキャッシュに便利です。

delete() - オブジェクトを削除する

await env.MY_BUCKET.delete(key | keys[])  // Single or bulk (max 1000)

1 回の呼び出しで最大 1000 個のキーを一括削除できます。常に成功します（べき等）。

list() - オブジェクトを一覧表示する

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

カーソルによるページネーション、プレフィックスによるフィルタリング、フォルダー向けのデリミターに対応しています。R2ListOptions については、references/workers-api.md を読み込んでください。

createMultipartUpload() - 大きなファイル（>100MB）

const multipart = await env.MY_BUCKET.createMultipartUpload(key, options?)

100MB のファイルに使用します。パートのアップロードから完了までのマルチパート処理の全手順については、references/common-patterns.md を読み込んでください。

次の場合は references/workers-api.md を読み込んでください：API リファレンス全体、インターフェース定義（R2Object、R2ObjectBody、R2PutOptions、R2GetOptions）、条件付き操作、チェックサム、高度なオプションが必要な場合。

---

重要なルール

必ず実施すること ✅

1. アップロード時に contentType を設定する - 設定しないと、ファイルはバイナリとしてダウンロードされます
2. 複数のオブジェクトには一括削除を使う（最大 1000 個のキー）
3. 静的アセットにはキャッシュヘッダーを設定する（cacheControl）
4. クライアントから大きなファイルをアップロードするには、署名付き URL を使う
5. >100MB のファイルにはマルチパートアップロードを使う
6. ブラウザーからアップロードする前に CORS ポリシーを設定する
7. 署名付き URL に有効期限（1～24 時間）を設定する
8. try/catch でエラーを処理する
9. メタデータだけが必要な場合は get() ではなく head() を使う
10. 上書きを防ぐには条件付き操作を使う

禁止事項 ❌

1. クライアント側のコードで R2 アクセスキーを決して公開しないでください
2. contentType を決して省略しないでください（ファイルがバイナリとしてダウンロードされます）
3. ループ内で決して削除しないでください（一括削除を使用してください）
4. エラー処理なしでアップロードしないでください
5. ブラウザーからのアップロードで CORS を決して省略しないでください
6. 小さなファイル（<5MB）にマルチパートを決して使用しないでください（オーバーヘッドが発生します）
7. 1 回の呼び出しで 1000 個を超えるキーを決して削除しないでください（失敗します）
8. アップロードが成功したと思い込まないでください（必ずレスポンスを確認してください）
9. 署名付き URL の有効期限を決して省略しないでください（セキュリティリスクがあります）
10. バケット名をハードコードしないでください（バインディングを使用してください）

---

主なユースケース

ユースケース 1：画像／アセットのストレージ

app.put('/api/upload/image', async (c) => {
  const file = await c.req.parseBody();
  const image = file['image'] as File;

  await c.env.MY_BUCKET.put(`images/${image.name}`, image.stream(), {
    httpMetadata: {
      contentType: image.type,
      cacheControl: 'public, max-age=31536000, immutable',
    },
  });

  return c.json({ success: true });
});

ユースケース 2：クライアントからの直接アップロード（署名付き URL）

クライアント側のアップロード用に、安全なアップロード URL を生成します。aws4fetch を使用した完全な実装については、templates/r2-presigned-urls.ts を参照してください。

リファレンスにある追加のパターン

次の内容については references/common-patterns.md を読み込んでください：

• マルチパートアップロード（100MB 超のファイル）- パート管理を含む完全なワークフロー
• 一括操作 - ページネーションを用いた一括削除、クリーンアップのパターン
• カスタムメタデータの追跡 - ユーザーファイル、バージョン、承認ワークフロー
• バージョン管理されたファイルストレージ - 最新ポインターのパターンによるバージョン履歴
• バックアップとアーカイブのパターン - 保持ポリシーを用いた自動バックアップ
• サムネイルの生成とキャッシュ - 必要に応じた画像処理
• 静的サイトのホスティング - SPA フォールバックとキャッシュ戦略
• オリジンフォールバック付き CDN - キャッシュ層としての R2

完全なマルチパートの例については、templates/r2-multipart-upload.ts を読み込んでください。

---

利用可能なエージェントとコマンド

自律型エージェント

エージェントは、複雑な複数ステップのワークフローを自動的に処理します。

• r2-setup-automator - R2 のセットアップ全般（バケットの作成 → バインディング → TypeScript 型 → デプロイ）
• multipart-orchestrator - チャンク分割、エラー回復、進行状況の追跡を伴う大容量ファイルのアップロード
• cors-debugger - 設定の生成とテストを伴う、体系的な CORS トラブルシューティング
• s3-migration-planner - AWS S3 から R2 への移行計画、データ転送、コスト分析
• event-notification-setup - Workers、Queues、自動化を用いたイベント駆動型ワークフロー

クイックコマンド

一般的な R2 操作にすばやくアクセスできます。

• /r2-setup - バケットを作成し、wrangler.jsonc でバインディングを設定
• /r2-presigned-url - クライアント側での安全なアップロード／ダウンロード用に署名付き URL を生成
• /r2-cors-debug - CORS 設定の問題を診断して修正
• /r2-multipart-init - 大容量ファイル用のマルチパートアップロードワークフローを初期化

---

リファレンスを読み込むタイミング

コアリファレンス（既存の機能）

references/setup-guide.md - 初回セットアップ、バインディング設定、TypeScript 型、デプロイ手順

references/workers-api.md - API の完全なリファレンス（すべてのメソッドとオプション）、条件付き操作、チェックサム

references/common-patterns.md - マルチパートアップロード、バックオフ付き再試行ロジック、一括操作、キャッシュ戦略

references/s3-compatibility.md - S3 移行ガイド、S3 クライアントライブラリの使用方法、aws4fetch による署名付き URL の署名

references/cors-configuration.md - ブラウザーアクセスの設定、CORS のデバッグ、セキュリティポリシー、Dashboard の設定

新機能のリファレンス（2025）

references/event-notifications.md - イベント駆動型の自動化、Queue 統合、画像処理、Webhook トリガー

references/advanced-features.md - ストレージクラス（コストの最適化）、バケットロック（コンプライアンス）、tus による再開可能なアップロード、SSE-C 暗号化

references/r2-sql-integration.md - R2 データ（CSV／Parquet／JSON）への SQL クエリ、分析パターン、パフォーマンスの調整

references/data-catalog-iceberg.md - Apache Iceberg テーブル、タイムトラベルクエリ、スキーマの進化、Spark／Snowflake との統合

references/cloudflare-access-integration.md - Zero Trust セキュリティ、SSO（Google／Okta／Azure AD）、ID ポリシー、MFA、監査ログ

references/performance-optimization.md - キャッシュ（ブラウザー／CDN／Workers）、圧縮（gzip／Brotli）、Range リクエスト、ETag、モニタリング

---

同梱リソースの使用

リファレンス（references/）

• setup-guide.md - セットアップの全手順（バケット作成 → デプロイ）
• workers-api.md - Workers API の完全なリファレンス（すべてのメソッドとオプション）
• common-patterns.md - 高度なパターン（マルチパート、再試行、バッチ、パフォーマンス）
• s3-compatibility.md - S3 互換性ガイド（移行、aws4fetch、S3 クライアント）
• cors-configuration.md - CORS セットアップガイド（ダッシュボード、シナリオ、トラブルシューティング、セキュリティ）

テンプレート（templates/）

• r2-simple-upload.ts - 基本的なアップロード／ダウンロード Worker
• r2-multipart-upload.ts - マルチパートアップロードの完全な実装
• r2-presigned-urls.ts - 署名付き URL の生成（アップロード＋ダウンロード）
• r2-cors-config.json - CORS 設定の例
• wrangler-r2-config.jsonc - R2 バインディングを含む完全な wrangler.jsonc

---

CORS の設定

ブラウザーでのアップロード／ダウンロード用に CORS を設定します。ダッシュボードでの設定、一般的なシナリオ、トラブルシューティング、セキュリティのベストプラクティスを含む完全なガイドは、references/cors-configuration.md を読み込んでください。

---

エラー処理

try {
  await env.MY_BUCKET.put(key, data);
} catch (error: any) {
  const message = error.message;

  if (message.includes('R2_ERROR')) {
    // Generic R2 error
  } else if (message.includes('exceeded')) {
    // Quota exceeded
  } else if (message.includes('precondition')) {
    // Conditional operation failed (onlyIf)
  }

  console.error('R2 Error:', message);
  return c.json({ error: 'Storage operation failed' }, 500);
}

指数バックオフによる再試行ロジック、サーキットブレーカーパターン、高度なエラー回復については、references/common-patterns.md を読み込んでください。

---

防止できる既知の問題

問題	説明	解決策
CORS エラー	ブラウザーからアップロード／ダウンロードできない	バケットの設定で CORS を設定する
ファイルがバイナリとしてダウンロードされる	content-type が設定されていない	常に httpMetadata.contentType を設定する
署名付き URL のセキュリティ	URL が期限切れにならない	常に X-Amz-Expires を設定する（1～24 時間）
マルチパートの上限	パーツが 100MB 超、または 10,000 パーツ超	パーツを 5MB～100MB にし、最大 10,000 個までにする
一括削除の上限	1000 個を超えるキーの削除に失敗する	削除を 1000 個単位のバッチに分割する
メタデータの超過	カスタムメタデータが 2KB 超	合計を 2KB 未満にする

---

Wrangler コマンド

# Bucket management
wrangler r2 bucket create <BUCKET_NAME>
wrangler r2 bucket list
wrangler r2 bucket delete <BUCKET_NAME>

# Object management
wrangler r2 object put <BUCKET>/<KEY> --file=<PATH>
wrangler r2 object get <BUCKET>/<KEY> --file=<OUTPUT>
wrangler r2 object delete <BUCKET>/<KEY>

# List objects
wrangler r2 object list <BUCKET>
wrangler r2 object list <BUCKET> --prefix="folder/"

---

公式ドキュメント

• R2 の概要: https://developers.cloudflare.com/r2/
• Workers API: https://developers.cloudflare.com/r2/api/workers/workers-api-reference/
• マルチパートアップロード: https://developers.cloudflare.com/r2/api/workers/workers-multipart-usage/
• 署名付き URL: https://developers.cloudflare.com/r2/api/s3/presigned-urls/
• CORS の設定: https://developers.cloudflare.com/r2/buckets/cors/

---

質問や問題がありますか？

1. セットアップの全手順は references/setup-guide.md を確認してください
2. API リファレンスは references/workers-api.md を確認してください
3. 高度なパターンは references/common-patterns.md を参照してください
4. 動作するコード例は templates/ を読み込んでください