記事一覧と1件の詳細をREST APIで読む
2件ずつ記事を取り出し、そのうち1件のタイトルと要約を読みます。一覧が空のときと、指定した記事が見つからないときの違いも確認できます。
目次
練習サイト「週末ノート」の公開記事を、管理画面の代わりに小さなプログラムで読んでみましょう。公開記事の一覧を取得するURLは /_emdash/api/content/posts です。posts は記事をまとめた入れ物(コレクション)の名前です。1件だけ詳しく読みたいときは、一覧で受け取った記事の id をこのURLの末尾に付けます。
週末ノートで、読むための鍵を用意する
- 初めてなら、練習用サイトの準備で、教材のZIPを展開して管理画面を開くところまで進めます。「週末ノート」の管理画面が見えたら、このページに戻ります。写真の登録は後回しで大丈夫です。サイトを起動した画面は開いたままにしてください。
- 初回の歓迎画面が重なっていたら Get Started で閉じます。左の Settings(設定)から API Tokens を開きます。ここでは、プログラムが記事を読むための鍵(トークン)を作ります。
- Create Token を押し、Token Name に「記事を読む練習」と入力します。Scopes(許可する操作)は Content Read だけを選び、Expiry(有効期限)は 7 days にします。最後にフォームの Create Token を押し、表示されたトークンをコピーしてください。値をコピーできるのはこの画面だけです。
- 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、週末の記録 092回目は 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の条件と結果の読み方を参照してください。