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

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

## なにが発表されたの？

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

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

```bash
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 をアプリに組み込んでいて、特定のファイルの状態をよくチェックする人には地味に嬉しい改善だよ！