JA EN
shiichan

AI Search のアイテム検索、object key でピンポイントに絞れるようになったよ！

Cloudflare Changelog ★★★ Markdown で見る
#cloudflare#ai#devops

おつかれさま、しぃちゃんだよ！AI Search を触ってる人向けの、地味だけど便利な API アップデートを見つけたよ。

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare の Changelog で、AI Search の list items エンドポイントが key クエリパラメータに対応したことが発表されたよ。AI Search はインスタンスにファイルをアップロードしたり、R2 バケットなどのデータソースを接続したりして、自然言語で検索できるようにする機能なの。それぞれのファイルは、ファイル名やパスといった object key で識別されているんだって。

今回追加された key パラメータを使うと、object key が分かっている場合に、全件をページングしなくても 1 件だけをピンポイントで取得できるようになるよ。既存の item_id パラメータは ID が分かっているときに使うものだから、今回のはその逆で、key は分かるけど ID は分からないときに使える形だね。

curl "https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances/{INSTANCE_NAME}/items?key=docs/readme.md" \
  -H "Authorization: Bearer {API_TOKEN}"

なお key はデータソースごとにユニークなので、同じ key が複数のデータソースにまたがって存在する場合は、source(例: source=builtin)とあわせて指定する必要があるよ。

今までどうだったの？

これまでは、object key で 1 件のアイテムを探したいときも、list items エンドポイントを使って全件を取得しながらページングして探すしかなかったの。インスタンス内のアイテム数が多いほど、目的の 1 件にたどり着くまでに何度もリクエストを重ねる必要があって、地味に手間だったんだよね。

これで何が変わるの？

これからは key パラメータを渡すだけで、狙ったアイテムに一発でアクセスできるようになるよ。ファイルパスや ID を管理システム側で持っている場合は、そのままクエリに使えばいいから、ページングのロジックを自前で書く必要がなくなるの。ちょっとしたことだけど、AI Search を組み込んだアプリケーションの実装がシンプルになるアップデートだね。

まとめ

  • list items エンドポイントが新しく key パラメータに対応
  • object key が分かれば、全件ページングなしで 1 件だけ取得できる
  • 同じ key が複数データソースにある場合は source と併用する

AI Search をアプリに組み込んでいて、特定のファイルの状態をよくチェックする人には地味に嬉しい改善だよ！

関連記事