コンテンツ取得

一覧、詳細、オブジェクト、全件取得の使い分けと、404の扱い。

一覧や詳細をSDKの部品で表示する場合は、List・Viewを使ってください。このページは、独自のカルーセルへデータを渡す、メタデータやサイトマップを生成するなど、取得結果を自分で扱う場合のリファレンスです。

ここではクイックスタートで作成したblog（title・bodyを持つリスト形式）を使います。サンプルのgenkoは生成済みのクライアントです。

メソッドを選ぶ

用途	リスト形式	オブジェクト形式
一覧	`list(queries?)`	なし
1件を取得。404なら例外	`get(id, options?)`	`get(options?)`
1件を取得。404ならnull	`getOrNull(id, options?)`	`getOrNull(options?)`
自動ページングして全件	`getAll(queries?)`	なし

いずれも非同期のためawaitで結果を受け取ります。

一覧を表示する

app/blog/page.tsx

import Link from "next/link";
import { genko } from "@/lib/client";

export default async function BlogPage() {
  const { contents, totalCount } = await genko.apis.blog.list({
    limit: 10,
    offset: 0,
    orders: "-publishedAt",
  });

  return (
    <main>
      <h1>ブログ（{totalCount}件）</h1>
      <ul>
        {contents.map((post) => (
          <li key={post.id}>
            <Link href={`/blog/${post.id}`}>{post.title}</Link>
          </li>
        ))}
      </ul>
      {contents.length === 0 && <p>公開されている記事はありません。</p>}
    </main>
  );
}

totalCountは条件に合う全件数、contents.lengthは今回取得した件数です。2ページ目を取得する場合は、同じ条件でoffset: 10を指定します。

詳細ページを表示する

URLのIDから取得する場合は、記事が消えたり非公開になったりするケースを扱います。

app/blog/[id]/page.tsx

import { notFound } from "next/navigation";
import { genko } from "@/lib/client";

export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const post = await genko.apis.blog.getOrNull(id);
  if (!post) notFound();

  return <main><h1>{post.title}</h1></main>;
}

本文のHTMLを表示するにはReactコンポーネントを組み合わせます。HTML文字列を通常のJSXの波括弧に入れると、タグも文字として表示されます。

getとgetOrNullの違い

get()は取得できなかったときに例外を投げます。getOrNull()は404だけをnullに変えます。認証エラーやレート制限、サーバーエラーまで「記事なし」として隠すわけではありません。

const post = await genko.apis.blog.getOrNull("abcDEF123456");
if (post === null) {
  // 存在しない、または通常の配信条件を満たさない記事。
}

詳しい例外処理はエラーと制限を参照してください。

オブジェクト形式を取得する

管理画面でprofileをオブジェクト形式として作り、pullでスキーマとAPI一覧を同期した場合の例です。

const profile = await genko.apis.profile.getOrNull();
if (profile) {
  console.log(profile.name);
}

IDは不要です。未作成または非公開の場合はnullになります。プロフィールが必ずある前提の処理ならget()を使えます。

全件取得する

サイトマップ生成などで全件が必要な場合はgetAll()を使います。

const posts = await genko.apis.blog.getAll({ orders: "-publishedAt" });
const paths = posts.map((post) => `/blog/${post.id}`);

内部で100件ずつ取得します。limitとoffsetは指定できません。公開条件に合う記事だけが対象で、下書きや編集履歴を含むバックアップ機能ではありません。

大量のデータを一度にメモリへ保持することや、取得途中の更新で一覧の位置が変わることを考慮してください。通常の画面表示ではlist()によるページングを使います。

取得オプション

一覧では検索・絞り込み・並び替えを指定できます。単一／オブジェクトではdepth・fields・draftKeyを指定します。

プレビューキーを扱う実装は下書きプレビューにまとめています。