Cloudflare AI Searchの外部source同期をWranglerから操作できるようになった。jobs createで非同期syncを開始し、list、get、logsで状態を追い、必要ならcancelできる。deploy完了とindex更新を連動しやすい一方、job開始を「検索へ反映済み」と扱うと古いindexを公開する。起動頻度、同時job、失敗、cancel、検索切替を明確なstateとして管理する必要がある。

何が変わったか

wrangler ai-search jobs create|list|get|cancel|logsが追加された。各commandはnamespace指定とJSON出力に対応し、listとlogsはpaginationを持つ。cancelは通常confirmationを求め、-yまたは--forceで省略できる。jobはwebsite・R2 sourceのnew、modified、deleted fileを走査してindexへ反映する非同期処理である。

変更前後の差

従来もdashboardやAPIからsyncを扱えたが、Wrangler中心のCI/CDでは別のHTTP実装や手作業が必要だった。新commandによりinstance管理とjob管理を同じCLIへ統合できる。一方、built-in storageへuploadしたfileは個別に即時indexされ、sync jobの対象ではない。source種別を無視して一律にjobs createを呼ぶ設計は誤りである。

誰に影響するか

documentation deploy後にsearch indexを更新するteam、CMS publish webhook、R2 ingest pipeline、複数environment・namespaceを持つSREが対象である。AI agentがCLIを操作する場合、JSON出力は解析しやすいが、cancelの--forceを無制限に許すと本番jobを停止し得る。検索利用者には更新反映の遅延と新旧混在として影響する。

対応期限

強制移行期限はない。外部sourceは既定6時間ごとに自動syncされ、manual triggerは30秒に1回までである。deployごとに無条件起動する前に、既存schedule、source更新頻度、rate limitを確認する。現在のdashboard・API workflowを残したままshadow導入できる。

必要な対応

environmentごとにaccount、namespace、instance、sourceを固定し、CLI argumentをbuild artifactとして記録する。create後はjob IDを保存し、get・logsでterminal stateまで監視する。同一instanceにrunning jobがある場合のpolicyを決め、重複起動を避ける。検索trafficはjob成功だけでなく、期待documentの存在とindex freshnessを確認してから切り替える。

実装・移行手順

  1. Wrangler versionと認証token権限を固定する。
  2. stagingでjobs createを実行しjob IDを取得する。
  3. getをpollしtimeout・failure・cancelを処理する。
  4. logsをartifactへ保存し機密情報をmaskする。
  5. canary documentを検索して反映を確認する。
  6. productionはapproval後に起動する。

失敗しやすい点

create commandの終了code 0をsync成功と解釈すること、namespaceを省略してdefaultの別instanceを更新すること、複数deployが同時にjobを起動することが典型的である。cancel --forceをretry logicへ入れると正常jobを停止する。logs paginationを読まず末尾のerrorを見逃すこともある。

リスク

誤namespace・instanceへのsync、delete反映による検索欠落、無限retryによるrate limit、logへの機密path露出がある。source側が不完全な状態でjobを開始すると、その状態がindexへ反映される。検索回答が新旧contentを混在させると規約・価格・手順の誤案内につながるため、freshnessをSLOとして管理する。

評価方法

deployからjob開始、terminal state、canary検索反映までの時間を測る。変更・追加・削除fileを含むtest sourceで正しく反映されるか確認し、失敗率、平均sync時間、処理file数、retry、rate limit、検索freshnessを記録する。schedule syncのみの場合との運用費用と反映遅延も比較する。

ロールバック

CIからjobs createを無効化し、既定scheduleまたは従来dashboard・API運用へ戻す。job実行中のcancelは影響を確認してから行い、pipelineを止めるだけでは既に開始したjobは停止しない点に注意する。旧index snapshotまたはsourceの前versionを保持し、誤delete時に再syncできるようにする。

編集部の見解

Wrangler対応でAI Searchは一般的なdeploy pipelineへ組み込みやすくなった。成功条件を「command実行」ではなく「期待documentが検索できる」に置くことが重要である。agentに操作させる場合もcreateとreadは自動化し、cancelやproduction namespace変更は人の承認を残すのが妥当だ。

実務チェックリスト

  • Wrangler versionを固定した
  • namespaceとinstanceを明示した
  • job IDを保存して完了まで待つ
  • 同時起動policyを定めた
  • 30秒trigger制限を考慮した
  • logsをpaginationして保存する
  • canary検索で反映を確認する
  • cancelとproduction操作を承認制にした

一次情報