検索APIの条件と結果の読み方

検索語、対象のコレクション、取得件数を指定して、公開記事のタイトルや次のページを読み取ります。

目次

公開記事を言葉で探すときは、GET /_emdash/api/search を使います。検索語を q で送ると、一致した記事が data.items に入ります。結果が0件のときも検索は成功です。

指定できる検索条件

名前指定例使いどころ
q週末の記録検索語。必須です
collectionsposts対象のコレクション(記事の入れ物)。複数なら posts,pages のようにカンマで区切ります
scopetitle検索対象に設定されたタイトル欄だけを調べます。省略すると、検索対象のすべての欄を調べます
localeen記事に設定された言語で絞ります。本文が日本語でも、保存時の言語が英語なら en です
limit21回で返す件数。1〜100の整数で、省略時は最大20件です
cursor前の結果の data.nextCursor同じ条件で続きを読むための値。受け取った文字列をそのまま渡します

週末ノートで2件だけ読んでみる

教材の初期状態では記事の検索が無効です。次の例を試すときは、練習サイトの準備を参考に、ZIPを新しいフォルダーに展開してください。初めて練習データを入れる前に、weekend-note/seed/seed.json の posts の定義を次の2か所だけ変えます。

  1. supports の配列に "search" を追加します。これで、このコレクションの検索を有効にします。
  2. 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でした。送った条件を確認します

既存のサイトで結果が出ないときは、まず記事が公開済みか、探している言葉が検索対象の欄に入っているかを確かめてください。検索欄自体をテーマに追加したいときは、サイト内検索を作る手順へ進めます。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。