記事一覧と1件の詳細をREST APIで読む

2件ずつ記事を取り出し、そのうち1件のタイトルと要約を読みます。一覧が空のときと、指定した記事が見つからないときの違いも確認できます。

目次

練習サイト「週末ノート」の公開記事を、管理画面の代わりに小さなプログラムで読んでみましょう。公開記事の一覧を取得するURLは /_emdash/api/content/posts です。posts は記事をまとめた入れ物(コレクション)の名前です。1件だけ詳しく読みたいときは、一覧で受け取った記事の id をこのURLの末尾に付けます。

週末ノートで、読むための鍵を用意する

  1. 初めてなら、練習用サイトの準備で、教材のZIPを展開して管理画面を開くところまで進めます。「週末ノート」の管理画面が見えたら、このページに戻ります。写真の登録は後回しで大丈夫です。サイトを起動した画面は開いたままにしてください。
  2. 初回の歓迎画面が重なっていたら Get Started で閉じます。左の Settings(設定)から API Tokens を開きます。ここでは、プログラムが記事を読むための鍵(トークン)を作ります。
  3. Create Token を押し、Token Name に「記事を読む練習」と入力します。Scopes(許可する操作)は Content Read だけを選び、Expiry(有効期限)は 7 days にします。最後にフォームの Create Token を押し、表示されたトークンをコピーしてください。値をコピーできるのはこの画面だけです。
  4. VS Codeのファイル一覧で weekend-note を右クリックし、「新しいファイル」で .env.rest-demo を作ります。weekend-note/package.json の隣です。次の2行を入れ、2行目の右側を自分のトークンに置き換えて保存します。起動時のURLが違うときは、1行目をそのURLに合わせます。
EMDASH_URL=http://127.0.0.1:4350
EMDASH_TOKEN=ここに練習用トークンを貼り付ける

このファイルは手元の練習専用です。この教材では、名前が .env で始まるファイルはGitの記録対象から外れます。公開フォルダーへ移したり、トークンを誰かに送ったりしないでください。

2件ずつ取り出し、最初の記事の要約を読む

次のコードを weekend-note/scripts/read-rest-posts.mjs として保存します。limit=2 は「一度に2件」、status=published は「公開済みの記事を選ぶ」という指定です。

const base = new URL('/_emdash/api/content/posts', process.env.EMDASH_URL);
const token = process.env.EMDASH_TOKEN;
if (!token) throw new Error('.env.rest-demo の EMDASH_TOKEN を確認してください。');

async function read(url) {
  const response = await fetch(url, {
    headers: { Authorization: 'Bearer ' + token },
  });
  const body = await response.json();
  if (!response.ok) {
    throw new Error('HTTP ' + response.status + ' ' + body.error?.code);
  }
  return body.data;
}

const listUrl = new URL(base);
listUrl.searchParams.set('status', 'published');
listUrl.searchParams.set('limit', '2');
if (process.argv[2]) listUrl.searchParams.set('q', process.argv[2]);

const first = await read(listUrl);
console.log('該当:', first.total, '件');
if (first.items.length > 0) {
  console.log('最初の一覧:', first.items.map(item => item.data.title).join('、'));
  const id = first.items[0].id;
  const detail = await read(new URL(base.pathname + '/' + encodeURIComponent(id), base));
  console.log('1件目の要約:', detail.item.data.excerpt);
}
if (first.nextCursor) {
  listUrl.searchParams.set('cursor', first.nextCursor);
  const next = await read(listUrl);
  console.log('次の一覧:', next.items.map(item => item.data.title).join('、'));
}

VS Codeのファイル一覧で weekend-note フォルダーを右クリックし、「統合ターミナルで開く」を選びます。開いた入力画面で、次の2行を1行ずつ実行してください。MacとWindowsで入力する内容は同じです。

node --env-file=.env.rest-demo scripts/read-rest-posts.mjs
node --env-file=.env.rest-demo scripts/read-rest-posts.mjs no-match-998877

初期データのままなら、1回目は次の4行が出ます。1行目の「12」は条件に合う記事の総数です。そこから2件ずつ読めていることを、2行目と4行目のタイトルで確かめてください。

該当: 12 件
最初の一覧: 週末の記録 12、週末の記録 11
1件目の要約: 12回目の散歩です。
次の一覧: 週末の記録 10、週末の記録 09

2回目は q に検索語を指定しています。教材に一致する記事がないので「該当: 0 件」だけが出れば成功です。

0件と「その記事が見つからない」の違いを試す

今度は、1件読むときに教材にない記事のIDを指定してみます。read-rest-posts.mjs の const id = first.items[0].id; を次の1行に変えて保存します。

const id = 'no-such-rest-post-998877';

最初のコマンド node --env-file=.env.rest-demo scripts/read-rest-posts.mjs を、末尾に検索語を付けずに実行します。一覧は取得できますが、続く1件の取得で HTTP 404 NOT_FOUND と出ます。一覧で「該当: 0 件」と返ったときは検索に成功していて、こちらは指定した記事を取得できなかったという違いがあります。

確認したら元の const id = first.items[0].id; に戻して保存し、同じコマンドで要約が再び出ることを確かめます。

一覧と詳細で、どこを読めばいい?

欲しいもの返ってきたJSONで見る場所
今回取得した記事一覧の data.items。記事が0件なら空の配列 []
条件に合う記事の総数一覧の data.total。一度に表示する件数とは別です
次を読むための目印一覧の data.nextCursor。値があるとき、同じ条件のまま cursor に渡します
指定した1件詳細の data.item。記事のIDや公開状態、入力した内容が入っています
タイトルと要約詳細の data.item.data.title と data.item.data.excerpt。内側の data に、このサイトで決めた入力項目が入ります

プログラムの read() は、一番外側の data を取り出して返します。そのため、表の data.items はコードでは first.items、詳細の data.item は detail.item と書いています。

エラーのときは何を確かめる?

表示確かめること
.env.rest-demo が見つからないweekend-note/package.json の隣に保存したか、コマンド入力画面を weekend-note で開いたかを確認します
fetch failedサイトの起動画面を確認し、そこに出たURLを EMDASH_URL に設定します
HTTP 401トークンを発行したサイトのURLと、コピーした値を確認します。期限が切れたり取り消されたりしたトークンでも起きます
HTTP 403トークンの権限に content:read があるか、発行した人が記事を読めるかを確認します
詳細の HTTP 404 NOT_FOUNDそのコレクションに記事があるかを確認します。一覧が0件のときと違い、指定した1件を取得できなかったという返答です

練習が終わったら Settings → API Tokens を開きます。「記事を読む練習」の行の取り消しボタン(Revoke token)を押し、Confirm で確定します。その後、手元の .env.rest-demo を削除してください。この例は管理者が手元でデータを読むためのコードです。公開ページの検索窓を作りたいときは、検索APIの条件と結果の読み方を参照してください。

公式の参照元

関連ガイド

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

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