Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Workers バインディング

最終更新 Markdown で表示Agent セットアップ

Workers は、新しいアプリケーションの作成や既存アプリケーションの拡張ができるサーバーレス実行環境です。Workers バインディング を使い、Cloudflare Worker から AI Search インスタンス内のドキュメントをアップロード、一覧表示、管理します。Items API には、インスタンスハンドルの items プロパティからアクセスします。

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

AI Search を Workers で使うには、AI Search バインディングを作成する必要があります。バインディングは Wrangler 設定 を更新して作成します。AI Search には次の 2 種類のバインディングがあります。

  • 名前空間バインディング: ai_search_namespaces
  • インスタンスバインディング: ai_search

名前空間バインディング

名前空間 内のすべてのインスタンスにアクセスします。実行時にインスタンスの取得、作成、一覧、削除ができます。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "my-namespace"
    }
  ]
}
compatibility_date = "2026-03-27"

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "my-namespace"
フィールド 型 必須 説明
binding string はい env で使える変数名です。たとえば "AI_SEARCH" とすると、env.AI_SEARCH でアクセスできます。
namespace string はい バインド先の 名前空間 です。アカウントごとに default 名前空間が自動作成されます。名前空間が存在しない場合、Wrangler はデプロイ時に作成します。
remote boolean いいえ ローカル開発で wrangler dev を使う場合は true にします。

インスタンスバインディング

default 名前空間内の 1 つのインスタンスへ直接バインドします。デプロイ時に使うインスタンスが決まっている場合に使います。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search": [
    {
      "binding": "MY_SEARCH",
      "instance_name": "my-instance"
    }
  ]
}
compatibility_date = "2026-03-27"

[[ai_search]]
binding = "MY_SEARCH"
instance_name = "my-instance"
フィールド 型 必須 説明
binding string はい env で使える変数名です。たとえば "MY_SEARCH" とすると、env.MY_SEARCH でアクセスできます。
instance_name string はい AI Search インスタンスの名前です。デプロイ時にデフォルト名前空間に存在する必要があります。
remote boolean いいえ ローカル開発で wrangler dev を使う場合は true にします。

メソッド

Items API のメソッドは、ai_search_namespaces バインディングと ai_search バインディングの両方で使えます。namespace バインディングでは、get() が返すハンドルでメソッドを呼び出します。インスタンスバインディングでは、バインディング上で直接呼び出します（例: env.MY_SEARCH.items.upload()）。

次の例は namespace バインディングを使います。

const instance = env.AI_SEARCH.get("my-instance");

items.upload()

インデックス用にドキュメントをアップロードします。すぐに戻ります。ドキュメントは処理待ちキューに入ります。

// Upload from a string
await instance.items.upload(
	"faq.md",
	"# FAQ\n\nQ: How do I reset my password?\nA: Go to Settings > Security...",
);

// Upload from an ArrayBuffer
const pdfResponse = await fetch("https://example.com/guide.pdf");
const pdfBuffer = await pdfResponse.arrayBuffer();
await instance.items.upload("guide.pdf", pdfBuffer);

// Upload from a ReadableStream
await instance.items.upload("doc.txt", request.body);

メタデータ付きでアップロードする

検索クエリでのフィルタ用に、ドキュメントへ カスタムメタデータ を付けます。カスタムメタデータフィールドは、先に update() メソッドか作成時にインスタンスへ定義する必要があります。

await instance.items.upload("guide.pdf", pdfBuffer, {
	metadata: {
		category: "onboarding",
		language: "en",
		version: "2.0",
	},
});

パラメーター

パラメーター 型 必須 説明
name string はい アップロードするドキュメントのファイル名。アイテムキーとして使います。
content ReadableStream、ArrayBuffer、または string はい ドキュメントの内容。最大ファイルサイズは 4 MB です。プレーンテキストまたは Markdown は string、バイナリファイルは ArrayBuffer、ストリーミングアップロードは ReadableStream を渡します。
options.metadata Record<string, string> いいえ アイテムに付けるカスタムメタデータのキーと値のペア。検索クエリでのフィルタに使います。インスタンスあたり最大 5 フィールドです。

レスポンス

フィールド 型 説明
id string 一意のアイテム識別子です。
key string アイテムのファイル名またはキーです。

items.uploadAndPoll()

ドキュメントをアップロードし、処理完了またはタイムアウトまでポーリングします。アップロード直後にそのドキュメントを検索する必要があるときに使います。

// Wait for a specific document to finish indexing before searching
const item = await instance.items.uploadAndPoll(
	"handbook.txt",
	handbookContent,
);
console.log(`handbook.txt status: ${item.status}`); // "completed"

// Now search across all uploaded documents
const results = await instance.search({
	messages: [{ role: "user", content: "password reset policy" }],
});

パラメーター

items.upload() と同じで、次のポーリングオプションが追加されます。

パラメーター 型 必須 説明
options.pollIntervalMs number いいえ アイテムのステータスを確認する間隔（ミリ秒）。デフォルトは 1000 です。
options.timeoutMs number いいえ 処理完了を待つ最大時間（ミリ秒）。デフォルトは 30000 です。

レスポンス

ポーリング完了後、アイテムオブジェクト全体を返します。

フィールド 型 説明
id string 一意のアイテム識別子です。
key string アイテムのファイル名またはキーです。
status string 処理ステータス: queued、running、completed、error、skipped、outdated。
chunks_count number ドキュメントから作成されたチャンク数です。
file_size number アップロードしたファイルのサイズ（バイト）です。
metadata object filename、folder、timestamp を含むアイテムメタデータです。
source_id string ソース識別子です（アップロードファイルでは builtin など）。
created_at string アイテム作成時のタイムスタンプです。
last_seen_at string インデックス中にアイテムを最後に確認したタイムスタンプです。

items.list()

インスタンス内のアイテムを、ページ分割した一覧で返します。

const { result, result_info } = await instance.items.list();

for (const item of result) {
	console.log(`${item.key} (${item.status})`);
}
// result_info.total_count contains the total number of items

パラメーター

パラメーター 型 必須 説明
page number いいえ 返すページ番号です。デフォルトは 1 です。
per_page number いいえ 1 ページあたりのアイテム数です。デフォルトは 20、最大は 50 です。
status string いいえ 処理ステータスでフィルタします: queued、running、completed、error、skipped、outdated。
sort_by string いいえ アイテムの並び順です: status（デフォルト）または modified_at。
search string いいえ テキスト内容でアイテムを検索します。
source string いいえ ソース識別子でフィルタします（アップロードファイルでは builtin など）。

レスポンス

フィールド 型 説明
result array アイテムオブジェクトの配列です。
result[].id string 一意のアイテム識別子です。
result[].key string アイテムのファイル名またはキーです。
result[].status string 処理ステータス: queued、running、completed、error、skipped、outdated。
result[].chunks_count number ドキュメントから作成されたチャンク数です。
result[].file_size number アップロードしたファイルのサイズ（バイト）です。
result[].metadata object filename、folder、timestamp を含むアイテムメタデータです。
result[].source_id string ソース識別子です（アップロードファイルでは builtin など）。
result[].created_at string アイテム作成時のタイムスタンプです。
result[].last_seen_at string インデックス中にアイテムを最後に確認したタイムスタンプです。
result_info object ページ分割のメタデータです。
result_info.count number 現在のページのアイテム数です。
result_info.total_count number インスタンス内のアイテム総数です。
result_info.page number 現在のページ番号です。
result_info.per_page number 1 ページあたりのアイテム数です。

items.delete()

アイテムと、インデックス済みチャンクを削除します。

await instance.items.delete("item-id-123");

パラメーター

パラメーター 型 必須 説明
itemId string はい 削除するアイテムの一意の識別子です。

レスポンス

void を返します。アイテムが存在しない場合はエラーをスローします。

items.get()

特定アイテムのステータス取得や元ファイルのダウンロード用のハンドルを返します。

items.get().info()

特定アイテムのステータスとメタデータを返します。

const itemInfo = await instance.items.get("item-id-123").info();
パラメーター
パラメーター 型 必須 説明
itemId string はい アイテムの一意の識別子です。
レスポンス
フィールド 型 説明
id string 一意のアイテム識別子です。
key string アイテムのファイル名またはキーです。
status string 処理ステータス: queued、running、completed、error、skipped、outdated。
chunks_count number ドキュメントから作成されたチャンク数です。
file_size number アップロードしたファイルのサイズ（バイト）です。
metadata object filename、folder、timestamp を含むアイテムメタデータです。
source_id string ソース識別子です（アップロードファイルでは builtin など）。
created_at string アイテム作成時のタイムスタンプです。
last_seen_at string インデックス中にアイテムを最後に確認したタイムスタンプです。

items.get().download()

アイテムの元のソースファイルをダウンロードします。

const file = await instance.items.get("item-id-123").download();
// file.body is a ReadableStream
パラメーター
パラメーター 型 必須 説明
itemId string はい アイテムの一意の識別子です。
レスポンス
フィールド 型 説明
filename string 元のファイル名です。
contentType string ファイルの MIME タイプです（例: application/pdf）。
size number ファイルサイズ（バイト）です。
body ReadableStream ファイル内容の読み取り可能なストリームです。

役に立ちましたか？