R2

Cloudflare R2 バケットを、AI Search インスタンスのデータソースとして接続できます。AI Search は、バケット内のファイルを自動でインデックスします。

新しいインスタンスを作成するときに、ダッシュボード、REST API、または Wrangler で R2 バケットを接続できます。R2 は任意のデータソースで、組み込みストレージ と併用できます。

R2 を使うインスタンスを初めて作る場合は、ダッシュボードまたは Wrangler CLI をおすすめします。サービス API トークン を自動で作成・登録します。REST API または Workers バインディングを使う場合は、サービス API トークンを自分で作成し、作成リクエストに token_id を渡す必要があります。設定手順は サービス API トークン を参照してください。

始めるには、データを入れた R2 バケットを設定 します。未対応のファイルやサイズ上限を超えるファイルは、インデックス時にスキップされ、エラーとして記録されます。

AI Search は、認識できるファイル名拡張子を優先し、より速いファイル種別判定パスとして使います。ファイル名拡張子のない R2 オブジェクトでは、サポート対象の MIME タイプを明示的な Content-Type メタデータとして設定します。

Content-Type が欠落している、未対応、不正、または application/octet-stream のオブジェクトはサポートされません。対応するファイル種別と MIME タイプは、データソース を参照してください。

オブジェクトパスの include / exclude ルールを定義し、インデックス対象のファイルを制御できます。特定のフォルダーだけをインデックスしたり、検索対象にしたくないファイルを除外したりできます。

たとえば、ドキュメントだけをインデックスし、下書きを除外する場合は次のようにします。

• Include: /docs/**
• Exclude: /docs/drafts/**

パターン構文、フィルタリングの動き、その他の例は パスフィルタリング を参照してください。

対応するファイル種別とサイズ上限は、データソース を参照してください。

検索結果のフィルタリング用に、R2 オブジェクトへカスタムメタデータを付けられます。AI Search は、S3 互換のカスタムヘッダー（x-amz-meta-*）からメタデータを読み取ります。

メタデータを抽出するには、先に AI Search の設定で スキーマを定義 する必要があります。

await env.MY_BUCKET.put("docs/document.pdf", fileContent, {
	customMetadata: {
		category: "documentation",
		version: "2.5",
		is_public: "true",
	},
});

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const client = new S3Client({
	region: "auto",
	endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
	credentials: {
		accessKeyId: R2_ACCESS_KEY_ID,
		secretAccessKey: R2_SECRET_ACCESS_KEY,
	},
});

await client.send(
	new PutObjectCommand({
		Bucket: "your-bucket",
		Key: "docs/document.pdf",
		Body: fileContent,
		Metadata: {
			category: "documentation",
			version: "2.5",
			is_public: "true",
		},
	}),
);

wrangler r2 object put your-bucket/docs/document.pdf \
  --file=./document.pdf \
  --header="x-amz-meta-category:documentation" \
  --header="x-amz-meta-version:2.5" \
  --header="x-amz-meta-is_public:true"

インデックス時に R2 からファイルを取得すると、次の処理が行われます。

1. オブジェクトからすべての x-amz-meta-* ヘッダーを読み取ります。
2. x-amz-meta- プレフィックスを取り除きます（例: x-amz-meta-category は category になります）。
3. フィールド名をスキーマと照合します（大文字小文字は区別しません）。
4. 値を設定済みのデータ型にキャストします。
5. 無効な値（例: number 型に対する非数値文字列）は、エラーにせず無視します。

メタデータ値は、MIME-Word エンコーディング（RFC 2047）で Unicode 文字に対応しています。ほとんどの S3 互換ツールは、このエンコーディングを自動で処理します。