検索APIの条件と結果の読み方
検索語、対象のコレクション、取得件数を指定して、公開記事のタイトルや次のページを読み取ります。
目次
公開記事を言葉で探すときは、GET /_emdash/api/search を使います。検索語を q で送ると、一致した記事が data.items に入ります。結果が0件のときも検索は成功です。
指定できる検索条件
| 名前 | 指定例 | 使いどころ |
|---|---|---|
q | 週末の記録 | 検索語。必須です |
collections | posts | 対象のコレクション(記事の入れ物)。複数なら posts,pages のようにカンマで区切ります |
scope | title | 検索対象に設定されたタイトル欄だけを調べます。省略すると、検索対象のすべての欄を調べます |
locale | en | 記事に設定された言語で絞ります。本文が日本語でも、保存時の言語が英語なら en です |
limit | 2 | 1回で返す件数。1〜100の整数で、省略時は最大20件です |
cursor | 前の結果の data.nextCursor | 同じ条件で続きを読むための値。受け取った文字列をそのまま渡します |
週末ノートで2件だけ読んでみる
教材の初期状態では記事の検索が無効です。次の例を試すときは、練習サイトの準備を参考に、ZIPを新しいフォルダーに展開してください。初めて練習データを入れる前に、weekend-note/seed/seed.json の posts の定義を次の2か所だけ変えます。
supportsの配列に"search"を追加します。これで、このコレクションの検索を有効にします。fieldsの中で"slug": "title"と書かれた入力欄に"searchable": trueを追加します。これで、タイトルが検索の索引に入ります。
準備ガイドの手順で練習データを入れたら、weekend-note のコマンド入力画面で次を実行します。教材の本番用ビルドをローカルで動かし、http://127.0.0.1:4351 が表示されたら、その画面を開いておきます。
npm run build
npm start次のコードを weekend-note/scripts/read-search.mjs として保存します。URLSearchParams が、日本語の検索語をURLに入れられる形に変換します。
const url = new URL('http://127.0.0.1:4351/_emdash/api/search');
url.search = new URLSearchParams({
q: '週末の記録',
collections: 'posts',
limit: '2',
}).toString();
const response = await fetch(url);
if (!response.ok) throw new Error('検索に失敗しました。HTTP ' + response.status);
const { data } = await response.json();
for (const item of data.items) {
console.log(item.title, item.slug);
}
console.log('続きあり:', Boolean(data.nextCursor));別のコマンド入力画面で weekend-note を開き、次を実行してください。
node scripts/read-search.mjs今回の教材では「週末の記録 01」「週末の記録 02」のタイトルとスラッグが表示され、最後の行は 続きあり: true でした。タイトルが同じ条件に一致しても、データを変更すれば返る順序は変わり得ます。
次の2件と、0件のときの見分け方
| 調べたいこと | 見る場所 |
|---|---|
| 記事を一覧に出したい | data.items の各項目から title を読みます。教材の詳細ページのURLを組み立てるときには slug を使います |
| 次の2件を読みたい | 最初のリクエストと同じ検索条件に cursor を追加します。検証では続きに note-03 と note-04 が返りました。最後のページには nextCursor が付きません |
| 該当する記事がなかった | HTTP 200で data.items が空配列になります。練習用の下書きのタイトルを未ログインで検索した場合も0件でした |
| 入力を修正したい | q を省いた場合と limit=101 の場合はHTTP 400でした。送った条件を確認します |
既存のサイトで結果が出ないときは、まず記事が公開済みか、探している言葉が検索対象の欄に入っているかを確かめてください。検索欄自体をテーマに追加したいときは、サイト内検索を作る手順へ進めます。