FeaturesConsumer SDKコンテンツの取得

コンテンツの取得

Consumer SDKを使用したコンテンツ取得の方法を説明します。このドキュメントでは以下の内容を解説します。

IDによる検索

指定したIDでコンテンツを1件取得します。

const data = await client.tables.blog.get(id);

関連テーブルの取得

関連テーブルのデータを同時に取得する場合は、include オプションを使用します。
取得したいテーブルを true に設定してください。

const data = await client.tables.blog.get(id, {
  include: { category: true },
});

複数の関連テーブルを取得することも可能です。

const data = await client.tables.blog.get(id, {
  include: {
    category: true,
    publisher: true,
  },
});

関連テーブルのネストも可能です。
relatedArticle テーブルの article フィールドを取得する場合は以下のように記述します。

const data = await client.tables.blog.get(id, {
  include: {
    relatedArticle: {
      article: true,
    },
  },
});

公開コンテンツのみの取得

下書きコンテンツを含めるかは draft オプションで制御します。
デフォルトは false で、公開されているコンテンツのみ取得します。

下書きコンテンツを取得するには、draft オプションを true に設定します。

⚠️

下書きコンテンツ取得の権限を持った Consumer API Key を使用する必要があります。 Consumer API Key は、開発者コンソールで生成できます。詳細は APIキーの生成 を参照してください。

const data = await client.tables.blog.get(id, {
  draft: true,
});

fetchのオプション設定

パラメータで RequestInit を指定できます。

例えば、Next.js App Router で revalidateTag() を使用するために fetch リクエストにタグを付けたい場合は以下のように設定できます。

const data = await client.tables.blog.get(
  id,
  {
    include: { category: true },
  },
  {
    next: { tags: ["blog", `blog-${id}`] },
  },
);

ユニークキーによる検索

ユニークキーを使用してデータを1件取得します。

const data = await client.tables.blog.getByUnique({
  slug: "my-first-blog-post",
});

関連テーブルの取得

関連テーブルのデータを同時に取得する場合は、include オプションを使用します。

const data = await client.tables.blog.getByUnique(
  {
    slug: "my-first-blog-post",
  },
  {
    include: { category: true },
  },
);

詳細は 関連テーブルの取得 を参照してください。

公開コンテンツのみの取得

下書きコンテンツを含めるかは draft オプションで制御します。
デフォルトは false で、公開されているコンテンツのみ取得します。

下書きコンテンツを取得するには、draft オプションを true に設定します。

⚠️

下書きコンテンツ取得の権限を持った Consumer API Key を使用する必要があります。 Consumer API Key は、開発者コンソールで生成できます。詳細は APIキーの生成 を参照してください。

const data = await client.tables.blog.getByUnique(
  {
    slug: "my-first-blog-post",
  },
  {
    draft: false,
  },
);

fetchのオプション設定

パラメータで RequestInit を指定できます。

例えば、Next.js App Router で revalidateTag() を使用するために fetch リクエストにタグを付けたい場合は以下のように設定できます。

const data = await client.tables.blog.getByUnique(
  {
    slug: "my-first-blog-post",
  },
  {
    include: { category: true },
  },
  {
    next: { tags: ["blog", `blog-slug-my-first-blog-post`] },
  },
);

複数件の検索

複数のコンテンツを取得します。

const data = await client.tables.blog.list({});

フィルタ

filter パラメータを使用して、特定の条件に一致するコンテンツを取得します。

slug が my-first-blog-post のブログ記事を取得する例を以下に示します。

const data = await client.tables.blog.list({
  filter: {
    slug: "my-first-blog-post",
  },
});

一致

slug が my-first-blog-post と一致するデータを取得します。

{
  slug: "my-first-blog-post",
}

= 演算子を使用して、一致を明示的に指定することも可能です。

{
  slug: { "=": "my-first-blog-post" },
}

不一致

!= 演算子を使用して、特定の値と一致しないデータを取得します。
slug が my-first-blog-post ではないデータを取得する例を以下に示します。

{
  slug: { "!=": "my-first-blog-post" },
}

大小比較

以下の演算子を使用して、数値や文字列の大小比較を実行できます。

  • <: より小さい
  • >: より大きい
  • <=: 以下
  • >=: 以上

price の値を比較して条件を満たすデータを取得する例を以下に示します。

// より小さい
{ price: { "<": 1000 } }
 
// より大きい
{ price: { ">": 1000 } }
 
// 以下
{ price: { "<=": 1000 } }
 
// 以上
{ price: { ">=": 1000 } }

IN, NOT IN

$in 演算子を使用して、特定の値のリストに一致するデータを取得します。
slug が my-first-blog-post または my-second-blog-post のデータを取得する例を以下に示します。

{
  slug: { "$in": ["my-first-blog-post", "my-second-blog-post"] },
}

$notIn 演算子を使用して、特定の値のリストに一致しないデータを取得することも可能です。
slug が my-first-blog-post または my-second-blog-post ではないデータを取得する例を以下に示します。

{
  slug: { "$notIn": ["my-first-blog-post", "my-second-blog-post"] },
}

文字列の部分一致

文字列の部分一致検索には $contains を使用します。
slug に my- を含むデータを取得する例を以下に示します。

{
  slug: { "$contains": "my-" },
}

$notContains を使用すると、文字列が含まれないデータを取得できます。
slug に my- を含まないデータを取得する例を以下に示します。

{
  slug: { "$notContains": "my-" },
}

AND, OR

オブジェクトに複数のプロパティを指定することで、AND条件でデータを取得できます。
category が book で、price が1000以下のデータを取得する例を以下に示します。

{
  category: "book",
  price: { "<=": 1000 },
}

明示的に $and 演算子を使用することも可能です。

{
  $and: [
    { category: "book" },
    { price: { "<=": 1000 } },
  ],
}

$or 演算子を使用して、複数の条件をORで結合することも可能です。
以下は、category が book で price が1000以下のデータ、または category が movie のデータを取得する例です。

{
  $or: [
    { category: "book", price: { "<=": 1000 } },
    { category: "movie" },
  ],
}

ANDやORをネストすることも可能です。
以下は、category が book で price が1000以下のデータ、または category が movie のデータを取得する例です。

{
  $or: [
    { $and: [{ category: "book" }, { price: { "<=": 1000 } }] },
    { category: "movie" },
  ],
}

関連テーブルのフィルタ

関連テーブルのフィルタリングも可能です。 relatedArticle テーブルの article フィールドが my-first-blog-post のデータを取得する場合は以下のように記述します。

{
  relatedArticle: {
    article: { slug: "my-first-blog-post" },
  },
}

ページネーション

取得件数とオフセットを指定してデータを分割取得します。

const data = await client.tables.blog.list({
  limit: 10,
  offset: 0,
});

limit パラメータを指定しない場合、デフォルトで100件まで取得されます。

ソート

指定したカラムでデータを並び替えます。

const data = await client.tables.blog.list({
  order: { createdAt: "desc" },
});

複数のカラムでソートすることも可能です。

const data = await client.tables.blog.list({
  order: { status: "asc", createdAt: "desc" },
});

複数のカラムを指定した場合、先に指定したカラムから順番にソートされます。 上記の例では、status で昇順ソートした後に createdAt で降順ソートします。

関連テーブルの取得

関連テーブルのデータを同時に取得する場合は include オプションを使用します。

const data = await client.tables.blog.list({
  include: { category: true },
});

詳細は 関連テーブルの取得 を参照してください。

公開データのみの取得

下書きコンテンツを含めるかは draft オプションで制御します。
デフォルトは false で、公開されているコンテンツのみ取得します。

下書きコンテンツを取得するには、draft オプションを true に設定します。

⚠️

下書きコンテンツ取得の権限を持った Consumer API Key を使用する必要があります。 Consumer API Key は、開発者コンソールで生成できます。詳細は APIキーの生成 を参照してください。

const data = await client.tables.blog.list({
  draft: false,
});

fetchのオプション設定

パラメータで RequestInit を指定できます。

例えば、Next.js App Router で revalidateTag() を使用するために fetch リクエストにタグを付けたい場合は以下のように設定できます。

const data = await client.tables.blog.list(
  {
    filter: { category: "book" },
  },
  {
    next: { tags: ["blog"] },
  },
);

全文検索

テーブルの全文検索機能が有効な場合のみ利用可能です。詳細は 全文検索 を参照してください。

query パラメータにキーワードを指定して全文検索を実行します。

const data = await client.tables.blog.search({
  query: "JavaScript",
});

フィルタ

search() メソッドは list() メソッドと比較して、filter オプションで使用できるパラメータに制約があります。

filter パラメータでは group のみ使用可能です。
以下のようなフィルタは search() では使用できません。

// ❌ searchメソッドでは使用不可
const data = await client.tables.blog.search({
  query: "JavaScript",
  filter: {
    status: "published",
    createdAt: { ">=": "2024-01-01" },
  },
});
 
// ✅ listメソッドでは使用可能
const data = await client.tables.blog.list({
  filter: {
    status: "published",
    createdAt: { ">=": "2024-01-01" },
  },
});

グループによる絞り込みのみ使用できます。

const data = await client.tables.blog.search({
  query: "JavaScript",
  filter: {
    group: "tech-articles",
  },
});

ソート

order パラメータは使用できません。検索結果は関連度順で固定されます。

fetchのオプション設定

パラメータで RequestInit を指定できます。

例えば、Next.js App Router で revalidateTag() を使用するために fetch リクエストにタグを付けたい場合は以下のように設定できます。

const data = await client.tables.blog.search(
  {
    query: "JavaScript",
  },
  {
    next: { tags: ["blog"] },
  },
);
CLICLI