a-blog cms の API 機能を扱いやすくする acms-js-sdk を開発しました

公開日: 2024/04/21

Next.js での利用

今回の記事では、Next.js での利用を想定した利用手順を紹介していきます。

a-blog cms で API 機能を有効にしたモジュールIDを作成する

最初に a-blog cms 上で API 機能を有効にしたモジュールIDを作成します。基本的な操作や作成方法はドキュメントを参照してください。

API | ドキュメント | a-blog cms developer

a-blog cmsのドキュメントページ。a-blog cmsの基本のカスタマイズ方法を掲載しています。

a-blog cms developer

今回利用するAPI用のモジュールIDを作成します。モジュールは Entry_Summary を利用します。

API機能を有効化する必要があることに注意してください。

API 機能を有効にしたモジュールIDの作成

acms-js-sdk のインストール

次に、Next.js のプロジェクトを作成後、acms-js-sdk のインストールを行います。

$ npx create-next-app@latest my-acms-app

my-acms-app ディレクトリの作成が完了したら、ディレクトリに移動して acms-js-sdk をインストールします。

$ cd my-acms-app
$ npm i @uidev1116/acms-js-sdk

インストールが完了したら、lib/acms/index.js といった適当なファイルを作成します。

createClient という関数をインポートして引数で a-blog cms を設置している URL とコンフィグ > API設定から発行したAPIキーを設定します。

// lib/acms/index.js
import { createClient } from "@uidev1116/acms-js-sdk";

const acmsClient = createClient({
  baseUrl: 'YOUR_BASE_URL',
  apiKey: 'YOUR_API_KEY',
});

export default acmsClient;

一覧ページの作成

それでは実際に a-blog cms からデータを取得して、Next.js で一覧ページを実装してみます。

app/page.js を以下のように編集してください。

import Link from "next/link";
import acmsClient from "@/lib/acms";

export default async function Home() {
  const { data } = await acmsClient.get({
    blog: 'blog',
    api: 'summary_index_api'
  })

  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <div className="flex flex-col items-center">
        <ul>
          {data['entry:loop'].map((entry) => (
            <li key={entry.eid}>
              <Link href={`/blog/${entry.ecd}`}>
                {entry.title}
              </Link>
            </li>
          ))}
        </ul>
      </div>
    </main>
  );
}

createClient 関数で作成したオブジェクトを acmsClient という名前でインポートします。

createClient 関数で作成したオブジェクトは get というメソッドを実行できます。この get メソッドを利用することで a-blog cms からデータを取得することができます。

上記の例ではブログコードが blog で登録されているブログのエントリー一覧のデータを取得しています。

ライブラリを利用することで以下のようなシンプルな記述でAPI機能を利用することができるようになりました。

 const { data } = await acmsClient.get({
    blog: 'blog',
    api: 'summary_index_api'
  })

また、この例では get メソッドの第一引数をオブジェクト形式で指定していますが、相対パスを文字列形式で指定できます。

// 相対パスを文字列形式で指定
 const { data } = await acmsClient.get('blog/api/summary_index_api/');

詳細解説

次は先程紹介できなかった機能を詳しく紹介していきたいと思います。

戻り値

get メソッドの返り値について説明します。

Next.js の例では data という値を利用しました。この data には API 機能で取得したデータがそのまま格納されます。

他にも、 get メソッドの返り値として以下の値を利用することができます。

プロパティ	型	概要
data	T	HTTPリクエストで取得したデータ
status	number	HTTP ステータスコード
statusText	string	HTTP ステータスコードに対応するステータスメッセージ
headers	Headers	HTTP レスポンスヘッダー

オプション

get メソッドの第2引数でオプションを指定することで、SDK の動作をカスタマイズできます。以下設定可能なオプションです。

オプション名	概要	型	デフォルト値
requestInit	リクエストに適用したいカスタム設定を含むオブジェクトです。詳しい内容は MDN をご確認ください。	RequestInit	undefined
responseType	HTTPレスポンスとして返却されるデータのタイプを設定します。	'arrayBuffer'\| 'blob'\| 'formData'\| 'json'\| 'text';	'json'

また、オプションは createClient 関数の引数でも設定可能です。

この方法で設定したオプションは createClient 関数で作成したクライアントが行うすべてのHTTPリクエストで適用されます。

const acmsClient = createClient({
  baseUrl: 'YOUR_BASE_URL',
  apiKey: 'Your_API_KEY',
  requestInit: {
    headers: {
      'Content-Type': 'application/json',
    },
  },
  responseType: 'json',
});

Next.js App Router

Next.js App Router で、次のように revalidate オプションを設定することができます。

Functions: fetch | Next.js

API reference for the extended fetch function.

nextjs

const response = await acmsClient.get(
  { api: 'MODULE_ID' },
  {
    requestInit: {
      next: {
        revalidate: 60,
      },
    }
  },
);

AbortController: abort() method

AbortController を活用して任意の条件・タイミングでHTTPリクエストを中断することができます。

AbortController - Web API | MDN

AbortController インターフェイスは 1 つ以上のウェブリクエストをいつでも中断することを可能にするコントローラーオブジェクトを表します。

MDN Web Docs

const controller = new AbortController();
const response = await acmsClient.get(
  { api: 'MODULE_ID' },
  {
    requestInit: {
      signal: controller.signal,
    }
  },
);

setTimeout(() => {
  controller.abort();
}, 1000);

発展的な使い方

URLコンテキストを指定する

a-blog cms の API機能はURLコンテキストを利用して、取得するデータをコントロールすることができます。acms-js-sdk ではURLコンテキストを指定することが簡単にできるようになっています。

例えば、例えば、 summary_index のモジュールIDを設定したモジュールの情報のうち、ブログコードを「blog」、カテゴリーコードを「category」、カスタムフィールド「price」の値を「60000」で登録しているかつ2ページ目の情報だけを取得したい場合は以下のように記述できます。

 const { data } = await acmsClient.get({
    blog: 'blog',
    category: 'category',
    field: 'price/60000',
    page: 2,
    api: 'summary_index'
  })

URLコンテキストの指定方法をより詳細に知りたい方は acmsPath についての説明をご確認ください。

エラーハンドリング

acms-js-sdk を使ってエラーハンドリングする方法を紹介します。

acms-js-sdk によって発生したエラーは AcmsFetchError というオブジェクトとして catch でき、isAcmsFetchError というメソッドを使って、発生したエラーが acms-js-sdk によって発生したエラーかどうかを判定できます。

acmsClient
  .get({
    api: 'MODULE_ID',
  })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    if (acmsClient.isAcmsFetchError(error)) {
      console.error(error.response.data);
      return;
    }
    console.error(error);
  });

TypeScript

ジェネリクスを使って data プロパティを型付けすることができます。

acmsClient
  .get<ResponseType>({
    api: 'MODULE_ID',
  })
  .then((response) => {
    console.log(response.data); // response.data is ResponseType
  })

ユーティリティ関数

acms-js-sdk はSDKクライアント以外にも、a-blog cms のAPI機能を利用する場合に便利なユーティリティ関数を提供しています。

acmsPath

acmsPath 関数を利用することでURLコンテキストを指定したURLのパスを簡単に作成することができます。

acmsPath 関数は以下のように利用できます。

import { acmsPath } from '@uidev1116/acms-js-sdk';

const path = acmsPath({
  blog: 'BLOG_CODE',
  category: 'CATEGORY_CODE',
  entry: 'ENTRY_CODE',
  // user: 1,
  // tag: ['tag1', 'tag2'],
  // field: 'color/eq/red',
  // span: { start: '2021-01-01', end: '2021-12-31' },
  // date: { year: 2021, month: 1, day: 1 },
  // page: 1,
  // order: 'id-asc',
  // limit: 10,
  // keyword: 'KEYWORD',
  // tpl: 'include/sample.json'
  api: 'MODULE_ID',
});

また、指定可能なパラメーターは以下になります。

パラメーター	型	概要
blog	string \| number	ブログID または、ブログコードを指定します。
category	string \| string[] \| number	カテゴリーID または、カテゴリーコードを指定します。カテゴリーの階層は配列で表現できます。
entry	string \| number	エントリーID または、エントリーコードを指定します。
user	number	ユーザーID を指定します。
tag	string[]	タグを指定します。
field	string	フィールドを指定します。
span	{ start?: string \| Date; end?: string \| Date }	日時を範囲で指定します。
date	{ year?: number; month?: number; day?: number }	日付を指定します。
page	number	ページを指定します。
order	string	表示順を指定します。
limit	number	最大表示件数を指定します。
keyword	string	キーワードを指定します。
tpl	string	tpl を指定します。
api	string	API 機能を利用するモジュールIDを指定します。
searchParams	string \| string[][] \| Record<string, string> \| URLSearchParams	クエリ文字列を指定します。

isAcmsFetchError

isAcmsFetchError 関数を利用することで、発生したエラーが、acms-js-sdk で発生したエラー（ AcmsFetchError ）かどうかを判定することができます。

import { isAcmsFetchError } from '@uidev1116/acms-js-sdk';

acmsClient
  .get({
    api: 'MODULE_ID',
  })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    if (isAcmsFetchError(error)) {
      console.error(error.response.data);
      return;
    }
    console.error(error);
  });

まとめ

今回はacms-js-sdk の概要と、Next.js での利用例を紹介させていただきました。

acms-js-sdk を利用することで、a-blog cms の API機能を利用したデータ取得を簡単かつ簡潔に実装することができますのでぜひご利用ください。

a-blog cms の API 機能を扱いやすくする acms-js-sdk を開発しました

目次

GitHub - uidev1116/acms-js-sdk: a-blog cms JavaScript SDK

Next.js での利用

a-blog cms で API 機能を有効にしたモジュールIDを作成する

API | ドキュメント | a-blog cms developer

acms-js-sdk のインストール

一覧ページの作成

詳細解説

戻り値

オプション

Next.js App Router

Functions: fetch | Next.js

AbortController: abort() method

AbortController - Web API | MDN

発展的な使い方

URLコンテキストを指定する

エラーハンドリング

TypeScript

ユーティリティ関数

acmsPath

isAcmsFetchError

まとめ

a-blog cms × Next.js で sitemap.xml を実装する

a-blog cms × Next.js で RSS Feed を実装する

a-blog cms をヘッドレスCMSとして Next.js でサイト制作するときのポイント

Next.js でサーバー・クライアント間で Date オブジェクトを扱うときの注意点

Vue3 × TypeScript でミニマルなモーダルを公開した話とライブラリ公開でハマったこと

ShoppingCart 拡張アプリの推しポイントを紹介する記事

Xserver に nodenv をインストールする

Vite でライブラリを作る