microCMSとは｜使い方・料金・APIとNext.js連携を実例で解説

microCMS は「記事をためて JSON で返す」ところだけを受け持ちます。HTML を作って表示するのは、Next.js・Astro・Nuxt などで作った自分のサイトです。記事を公開すると Webhook でサイトの再ビルドを始められます。

flowchart TD
    A[編集者が管理画面で<br>記事を書いて公開] --> B[(microCMS<br>記事を保存)]
    B -->|コンテンツAPI<br>JSON| C[Next.js・Astro・Nuxt<br>SDK で取得]
    C --> D[HTML を作る<br>ビルドまたはSSR]
    D --> E[読者のブラウザ]
    B -.->|Webhook<br>公開を知らせる| C

急いでいる人向けに、よく調べられることの答えを先にまとめます。

知りたいこと	答え	詳しい節
microCMSとは	日本製のヘッドレスCMS（API で記事を配る）	microCMSとは
無料で使える？	Hobby は0円。API 5個・転送量20GB/月まで	料金
有料の最安	Team 4,900円〜/月（税抜）	料金
記事の取り方	GET /api/v1/{エンドポイント} にAPIキーのヘッダー	コンテンツAPI
JavaScript では	microcms-js-sdk の getList・getListDetail	SDK
公開を反映するには	Webhook で再ビルド（Vercel・Netlify など）	Webhook
下書きを見るには	画面プレビュー＋draftKey	画面プレビュー
WordPress との違い	表示の部分を持たない。画面は自分で作る	違い

確認環境：Ubuntu 24.04.4 LTS・Node.js 22.22.2・microcms-js-sdk 3.6.0（npm の最新）・Next.js 16.4.2（React 19.3.1）・Astro 7.4.1・Python 3.11.15。microCMS のサービスには接続せず、公式ドキュメントのコンテンツ API の仕様（URL・クエリ・応答の形・エラーの文）どおりに応答する擬似 API を Node.js で自作し、SDK の通信先をその擬似 API に向け直して、SDK が組み立てた URL・ヘッダー・本文、エラーの出方、再試行、全件取得の動きを記録しました。Next.js（静的書き出しと SSR のプレビュー）と Astro で同じ擬似 API からサイトをビルドし、出力のファイルを確かめています。Webhook は、ドキュメントにあるカスタム通知の形の JSON と HMAC-SHA256 の署名を自分で作って受け口に送りました。料金・上限・フィールド・Webhook・画面プレビュー・画像 API・APIキーの権限は document.microcms.io・microcms.io の料金ページ・microCMS ヘルプセンター、比較の数値は Contentful・Strapi・WordPress の公式ページで確かめました（確認日 2026年10月22日）。

microCMSとは（読み方・ヘッドレスCMSの仕組み）

この節では、microCMS が何をするサービスで、WordPress のような CMS と何が違うのかが分かります。

microCMS（読み方：マイクロシーエムエス）は、株式会社microCMS が提供する日本製のヘッドレス CMS です。 管理画面で記事やお知らせを入力すると、その内容を API（JSON）で取り出せます。管理画面・ドキュメント・サポートが日本語で、2026年5月20日の同社の発表では利用企業数が15,000社を超えています。

CMS（Content Management System）は、記事などのコンテンツを管理する仕組みです。WordPress のような従来の CMS は、記事をためる部分と、HTML を作って表示する部分（テーマ）が1つになっています。ヘッドレス CMS は、表示の部分（head）を持たず、記事をためて API で返す部分だけを提供します。 表示は、Next.js・Astro・Nuxt などで作った別のアプリが受け持ちます。

ヘッドレスにすると、次のことが変わります。

観点	従来の CMS	ヘッドレス CMS
画面を作る技術	CMS のテーマ（WordPress なら PHP）	好きなフレームワーク（React・Vue・Astro など）
記事の出し先	その CMS が作る Web サイト	Web・アプリ・サイネージなど API を呼べる所すべて
公開するもの	CMS のサーバーそのもの	ビルドした HTML か、自分のアプリのサーバー
記事を変えたとき	すぐ表示に反映	静的サイトなら再ビルドが要る（Webhook で自動化）
プレビュー	標準で付いている	下書きを取る仕組みを自分で作る

最後の2行が、ヘッドレス CMS を初めて使うときにつまずきやすい点です。この記事の Webhook とプレビューの節で、実際に動かした形を載せます。

microCMSでできること（機能の早見表）

この節では、microCMS の主な機能と、それぞれを何に使うかが一覧で分かります。

機能	できること	使えるプラン（2026年10月22日時点）
リッチエディタ	書式つきの本文を HTML で返す	全プラン
API スキーマ	記事の項目（フィールド）を自分で決める	全プラン
マネジメント API	メディアのアップロードなど管理画面の操作を API で行う	全プラン（ベータ）
予約投稿	決めた日時に公開・公開終了する	全プラン
レビュー（承認）	公開の前に別の人の確認を通す	全プラン
ビュー	管理画面の一覧を条件で保存する	Team 以上
権限管理（ロール）	メンバーごとに見られる・編集できる API を分ける	Business 以上
過去バージョンの復元	以前の版の記事に戻す	Business 以上
複数環境管理	本番と開発でサービスを分けて管理する	Business 以上
監査ログ・SSO	操作の記録・シングルサインオン	Enterprise
MCP サーバー	Claude などの AI ツールから記事の取得・作成を行う	ベータ（APIキーの権限の範囲）

MCP サーバーは microCMS が運営するもので、MCP に対応した AI ツールに URL と APIキーを登録して使います。ドキュメントでは、AI 用に必要な権限だけを付けた APIキーを別に作ることを勧めています。

microCMSの料金（2026年10月22日時点）と無料プラン

この節では、4つのプランの値段と上限、無料の Hobby でどこまで使えるかが分かります。

microCMS の料金は、Hobby（0円）・Team（4,900円〜/月）・Business（75,000円〜/月）・Enterprise（見積もり）の4つです。 金額は税抜で、2025年6月10日に改定された料金です（料金ページで2026年10月22日に確認）。プランは1サービスごとに1つ選びます。

項目	Hobby	Team	Business	Enterprise
月額（税抜）	0円	4,900円〜	75,000円〜	見積もり
API 数	5個	10個（+2,000円/個）	30個（+2,000円/個）	50個（+2,000円/個）
メンバー数	3人	3人（+1,200円/人）	20人（+1,200円/人）	50人〜（+1,200円/人）
データ転送量	20GB/月（超えると API 停止）	200GB/月（+20円/GB）	1TB/月（+18円/GB）	1TB〜/月（+16円/GB）
コンテンツ数	10,000件	20,000件	50,000件	100,000件
APIキー数	1個	3個	10個	20個
1メディアの上限	40MB	100MB	300MB	500MB
API リクエスト数	無制限	無制限	無制限	無制限
権限管理・IP 制限	なし	なし	あり	あり
無料トライアル	―	14日間	14日間	―

Hobby プランは、法人の Web サイトでも使えます（microCMS ヘルプセンターの回答）。ただし、データ転送量が月20GB を超えると、その場で API が使えなくなり、翌月1日にリセットされるまで止まります。有料プランは止まらず、超えた分が GB 単位で加算されます。

データ転送量の数え方と月額の試算

データ転送量は、コンテンツ API で JSON を取得したときと、ブラウザが画像を表示したりファイルをダウンロードしたりしたときに数えられます（ヘルプセンター「データ転送量とは何ですか？」）。ヘルプセンターの試算の式は「月間 PV × 1ページあたりの画像の容量」です。同じ前提（250KB の画像が1ページに5枚＝1.25MB）で、料金ページの単価から月額を計算しました。

# microCMS のデータ転送量と月額の目安（料金は 2026年10月22日時点の公式の料金ページ、税抜）
PLANS = {  # 名前: (月額, 含まれる転送量GB, 超過 円/GB)
    'Team': (4900, 200, 20),
    'Business': (75000, 1000, 18),
}
MB_PER_PAGE = 0.25 * 5  # 1枚250KBの画像が5枚（ヘルプの試算例と同じ前提）
print(f"{'月間PV':>10} | {'転送量GB':>8} | {'Hobby':>12} | {'Team':>8} | {'Business':>8}")
for pv in [10_000, 50_000, 100_000, 300_000, 500_000, 1_000_000]:
    gb = pv * MB_PER_PAGE / 1000
    hobby = '0円' if gb <= 20 else 'API停止'
    cost = {n: m + max(0, gb - inc) * over for n, (m, inc, over) in PLANS.items()}
    print(f"{pv:>10,} | {gb:>8,.1f} | {hobby:>12} | {cost['Team']:>8,.0f} | {cost['Business']:>8,.0f}")

      月間PV |    転送量GB |        Hobby |     Team | Business
    10,000 |     12.5 |           0円 |    4,900 |   75,000
    50,000 |     62.5 |        API停止 |    4,900 |   75,000
   100,000 |    125.0 |        API停止 |    4,900 |   75,000
   300,000 |    375.0 |        API停止 |    8,400 |   75,000
   500,000 |    625.0 |        API停止 |   13,400 |   75,000
 1,000,000 |  1,250.0 |        API停止 |   25,900 |   79,500

転送量のほとんどは画像です。 静的サイト（SSG）にすると、記事の JSON を取るのはビルドのときだけになりますが、画像を microCMS の URL（images.microcms-assets.io）から表示している限り、画像の転送量は読まれるたびに数えられます。1万 PV でも Hobby の20GB に近づくので、公開するサイトでは Team 以上を前提に試算しておくと、API が止まる事態を避けられます。Business は転送量だけでなく、権限管理・IP 制限・過去バージョンの復元・技術サポートが付くプランなので、必要な機能から選びます。

プランの選び方

状況	合うプラン	理由
個人の学習・試作	Hobby	0円。API 5個・メンバー3人
アクセスの少ない小さなサイト	Hobby（転送量を毎月見る）	20GB を超えると API が止まる
公開する企業サイト・ブログ	Team	転送量を超えても止まらない
編集者が多い・権限を分けたい	Business	ロール・IP 制限・バージョン復元
SSO・監査ログ・SLA が要る	Enterprise	見積もり。請求書払いも可

microCMSの使い方：始め方とAPIの作り方（リスト形式・オブジェクト形式）

この節では、アカウントを作ってから、記事を API で取り出せるようになるまでの手順が分かります。

エンドポイントの名前は、3〜32文字の半角英小文字・数字で、記号はハイフン（-）とアンダースコア（_）だけが使えます。既にある名前とは重ねられません。

リスト形式とオブジェクト形式の違い

型	向いているもの	API の応答
リスト形式	ブログ・お知らせ・商品など、同じ形が複数あるもの	contents の配列と totalCount
オブジェクト形式	サイト名・フッターの文言など、1つだけのもの	オブジェクトが1つ

擬似 API で、2つの型の応答の形を並べます（リスト形式は2件に絞りました）。

// リスト形式：GET /api/v1/blogs?limit=2&fields=id,title
{"contents":[{"id":"nextjs-ssg","title":"Next.jsで静的サイトを作る"},{"id":"astro-intro","title":"Astroの始め方"}],"totalCount":5,"offset":0,"limit":2}

// オブジェクト形式：GET /api/v1/settings
{"createdAt":"2026-10-20T01:00:00.000Z","updatedAt":"2026-10-20T01:00:00.000Z","publishedAt":"2026-10-20T01:00:00.000Z","revisedAt":"2026-10-20T01:00:00.000Z","siteName":"RJC Tech Notes","description":"microCMS の検証用サイト"}

リスト形式の各記事には、id・createdAt・updatedAt・publishedAt・revisedAt の5つのシステムフィールドが自動で付きます。日時はすべて UTC（末尾が Z）なので、日本時間で表示するときは変換します。

フィールドの種類とAPIで返る値

この節では、API スキーマに使えるフィールドの種類と、それぞれが JSON でどう返るかが分かります。

フィールドの種類によって、JSON の型が変わります。 特に、セレクトフィールドは1つしか選ばない設定でも配列で返ること、画像はオブジェクトで返ることに注意します（ドキュメント「GET API のフィールドのレスポンス」の例）。

フィールド	使いどころ	JSON の値の例
テキストフィールド	タイトル・短い文字	"some text"
テキストエリア	改行のある文章（HTML ではない）	"some\ntext"
リッチエディタ	本文（見出し・表・画像）	"<p>some text</p>"（HTML）
画像	アイキャッチ	{ "url": "…", "height": 630, "width": 1200, "alt": "…" }
複数画像	ギャラリー	画像のオブジェクトの配列
日時	イベントの日	"2023-01-01T00:00:00.000Z"（UTC）
真偽値	「おすすめに出す」など	true
セレクトフィールド	決まった選択肢	["Apple", "ORANGE"]（常に配列）
コンテンツ参照	カテゴリ・著者	参照先の記事のオブジェクト
複数コンテンツ参照	関連記事・タグ	参照先のオブジェクトの配列
数字	価格・並び順	42
ファイル	PDF などの配布物	{ "url": "…", "fileSize": 10000 }
カスタムフィールド	複数の項目の組（例：リンクの文字と URL）	{ "fieldId": "…", … }
繰り返しフィールド	カスタムフィールドを並べる（本文のブロック）	カスタムフィールドの配列
拡張フィールド	外部のデータを iframe で選ぶ	{ "id": "123" } など

カテゴリは「カテゴリ」用のリスト形式の API を別に作り、ブログの API からコンテンツ参照で指すのが基本の形です。参照先をどこまで展開するかはクエリの depth（既定 1、最大 3）で決まります。

コンテンツAPIの使い方（GET・クエリ・filters）

この節では、コンテンツ API の URL・ヘッダー・クエリの書き方と、絞り込み（filters）の演算子が分かります。

記事の取得は GET https://サービスID.microcms.io/api/v1/エンドポイント に、X-MICROCMS-API-KEY ヘッダーを付けて送ります。 1件だけ取るときは、URL の末尾にコンテンツ ID を付けます。curl でカテゴリが news の記事を新しい順に取った例です（送り先は擬似 API の URL に置き換えて実行しました）。

curl -G 'https://rjc-demo.microcms.io/api/v1/blogs' \
  -H 'X-MICROCMS-API-KEY: あなたのAPIキー' \
  --data-urlencode 'filters=category[equals]news' \
  --data-urlencode 'fields=id,title,publishedAt' \
  --data-urlencode 'orders=-publishedAt'

{"contents":[{"id":"holiday","title":"年末年始の休業のお知らせ","publishedAt":"2026-10-18T00:00:00.000Z"},{"id":"release-2026","title":"新機能のお知らせ","publishedAt":"2026-10-12T00:00:00.000Z"}],"totalCount":2,"offset":0,"limit":10}

-G と --data-urlencode を使うと、[ ] , が URL 用に変換されて送られます（filters=category%5bequals%5dnews）。limit を書かないと既定の10件になっていることも、応答の "limit":10 で分かります。

クエリの早見表

クエリ	意味	既定値・上限
limit	取得する件数	既定 10・最大 100
offset	何件目から取るか	既定 0
orders	並び順。- を付けると降順。カンマで複数	管理画面の並び順
q	キーワードで全文検索	並び順を書かなければ合致度順
fields	返す項目をカンマで指定。category.name も可	すべての項目
ids	コンテンツ ID をカンマで指定	―
filters	条件で絞り込む（次の表）	―
depth	参照先をどの深さまで展開するか	既定 1・0〜3
draftKey	下書きを取る（プレビュー用）	―

filtersの演算子

演算子	意味	例
[equals]	等しい	category[equals]tech
[not_equals]	等しくない	category[not_equals]news
[contains]	含む	title[contains]Next
[not_contains]	含まない	title[not_contains]お知らせ
[less_than]	より小さい（前）	publishedAt[less_than]2026-10-01
[greater_than]	より大きい（後）	views[greater_than]100
[exists]	値がある	eyecatch[exists]
[not_exists]	値が無い	eyecatch[not_exists]
[begins_with]	前方一致	title[begins_with]Web

条件は [and] と [or] でつなぎ、括弧も使えます。日時の比較は UTC で書き、タイムゾーンは付けられません。コンテンツ参照は [equals]、複数コンテンツ参照は [contains] に、参照先のコンテンツ ID を書きます。

APIの上限（レート制限・大きさ）

ほかに、POST・PUT の本文は約300KB、PATCH は約90KB、1コンテンツのデータは約200KB、応答までの時間は約29秒が上限です（ドキュメント「制限事項」）。limit=100 で取ると5MB に届くような大きな記事では、fields で本文を外して一覧を取ります。

microcms-js-sdkの使い方（送られるリクエストの実物）

この節では、公式の JavaScript SDK の書き方と、各メソッドが実際にどんな URL・ヘッダー・本文を送るかが分かります。

npm install microcms-js-sdk

createClient にサービス ID と APIキーを渡し、リスト形式は getList・getListDetail、オブジェクト形式は getObject で取ります。 以前の get は非推奨になりました。

import { createClient } from 'microcms-js-sdk';

const client = createClient({
  serviceDomain: 'rjc-demo',          // https://rjc-demo.microcms.io の rjc-demo
  apiKey: process.env.MICROCMS_API_KEY,
});

// 1) リスト形式：一覧（新しい順に2件、必要な項目だけ）
const list = await client.getList({
  endpoint: 'blogs',
  queries: { limit: 2, orders: '-publishedAt', fields: 'id,title,category.name' },
});
console.log('getList →', JSON.stringify(list));

// 2) リスト形式：1件
const one = await client.getListDetail({ endpoint: 'blogs', contentId: 'astro-intro', queries: { fields: 'id,title,publishedAt' } });
console.log('getListDetail →', JSON.stringify(one));

// 3) 絞り込み（カテゴリが tech かつ views が 100 より大きい）
const f = await client.getList({
  endpoint: 'blogs',
  queries: { filters: 'category[equals]tech[and]views[greater_than]100', fields: 'id,views' },
});
console.log('filters →', JSON.stringify(f));

// 4) オブジェクト形式
const s = await client.getObject({ endpoint: 'settings' });
console.log('getObject →', JSON.stringify(s));

// 5) 下書きを draftKey で取る（プレビュー）
const d = await client.getListDetail({ endpoint: 'blogs', contentId: 'webhook-guide', queries: { draftKey: 'dk_abc123', fields: 'id,title' } });
console.log('draftKey →', JSON.stringify(d));

SDK のコードは変えずに、Node.js の fetch を差し替えて通信先を擬似 API に向け、SDK が組み立てたリクエスト（[SDK→] の行）と、受け取った結果を記録しました。

[SDK→] GET https://rjc-demo.microcms.io/api/v1/blogs?limit=2&orders=-publishedAt&fields=id%2Ctitle%2Ccategory.name
        x-microcms-api-key: test-api-key-0001
getList → {"contents":[{"id":"holiday","title":"年末年始の休業のお知らせ","category":{"name":"お知らせ"}},{"id":"webhook-guide","title":"Webhookで自動デプロイ","category":{"name":"技術"}}],"totalCount":5,"offset":0,"limit":2}
[SDK→] GET https://rjc-demo.microcms.io/api/v1/blogs/astro-intro?fields=id%2Ctitle%2CpublishedAt
        x-microcms-api-key: test-api-key-0001
getListDetail → {"id":"astro-intro","title":"Astroの始め方","publishedAt":"2026-10-10T00:00:00.000Z"}
[SDK→] GET https://rjc-demo.microcms.io/api/v1/blogs?filters=category%5Bequals%5Dtech%5Band%5Dviews%5Bgreater_than%5D100&fields=id%2Cviews
        x-microcms-api-key: test-api-key-0001
filters → {"contents":[{"id":"nextjs-ssg","views":320},{"id":"astro-intro","views":150},{"id":"webhook-guide","views":410}],"totalCount":3,"offset":0,"limit":10}
[SDK→] GET https://rjc-demo.microcms.io/api/v1/settings
        x-microcms-api-key: test-api-key-0001
getObject → {"createdAt":"2026-10-20T01:00:00.000Z","updatedAt":"2026-10-20T01:00:00.000Z","publishedAt":"2026-10-20T01:00:00.000Z","revisedAt":"2026-10-20T01:00:00.000Z","siteName":"RJC Tech Notes","description":"microCMS の検証用サイト"}
[SDK→] GET https://rjc-demo.microcms.io/api/v1/blogs/webhook-guide?draftKey=dk_abc123&fields=id%2Ctitle
        x-microcms-api-key: test-api-key-0001
draftKey → {"id":"webhook-guide","title":"Webhookで自動デプロイ（下書き：改訂版）"}

読み取れることは次の3つです。

• URL は https://{serviceDomain}.microcms.io/api/v1/{endpoint} に固定で、SDK の中に書かれています（SDK のソースで確認）。queries は URLSearchParams で URL に変換され、, は %2C、[ ] は %5B %5D になりました。
• 付くヘッダーは X-MICROCMS-API-KEY だけでした。擬似 API の側では、Node.js の fetch が付ける user-agent: node・accept: */* なども届いています。
• filters は文字列のまま渡します。SDK は中身を確かめないので、書き間違いは API の 400 で分かります。

書き込み（create・update・delete）

console.log('create →', JSON.stringify(await client.create({ endpoint: 'blogs', content: { title: '新しい記事', category: 'tech' } })));
console.log('create(contentId) →', JSON.stringify(await client.create({ endpoint: 'blogs', contentId: 'my-post', content: { title: 'ID を決めた記事' }, isDraft: true })));
console.log('update →', JSON.stringify(await client.update({ endpoint: 'blogs', contentId: 'my-post', content: { title: '直した記事' } })));
console.log('delete →', JSON.stringify(await client.delete({ endpoint: 'blogs', contentId: 'my-post' })));

[SDK→] POST https://rjc-demo.microcms.io/api/v1/blogs
        content-type: application/json
        x-microcms-api-key: test-api-key-0001
        body: {"title":"新しい記事","category":"tech"}
create → {"id":"gen36gk7knjrk"}
[SDK→] PUT https://rjc-demo.microcms.io/api/v1/blogs/my-post?status=draft
        content-type: application/json
        x-microcms-api-key: test-api-key-0001
        body: {"title":"ID を決めた記事"}
create(contentId) → {"id":"my-post"}
[SDK→] PATCH https://rjc-demo.microcms.io/api/v1/blogs/my-post
        content-type: application/json
        x-microcms-api-key: test-api-key-0001
        body: {"title":"直した記事"}
update → {"id":"my-post"}
[SDK→] DELETE https://rjc-demo.microcms.io/api/v1/blogs/my-post
        x-microcms-api-key: test-api-key-0001
delete → undefined

SDK のメソッド	送られる HTTP	ポイント
create（ID なし）	POST /api/v1/blogs	ID は microCMS が付ける
create（contentId あり）	PUT /api/v1/blogs/{id}	自分で ID を決める
isDraft: true	URL に ?status=draft	下書きとして保存
update	PATCH /api/v1/blogs/{id}	送った項目だけ変わる
delete	DELETE /api/v1/blogs/{id}	戻り値は undefined

コンテンツ参照（ここでは category）は、作成のときは参照先のコンテンツ ID を文字列で送ります。書き込みには、APIキーに POST・PUT・PATCH・DELETE の権限が要ります。

全件取得（getAllContents・getAllContentIds）

limit の上限は100なので、それより多い記事を取るときは getAllContents を使います。250件ある API で動かしました。

const t0 = Date.now();
const all = await client.getAllContents({ endpoint: 'news' });
console.log('getAllContents →', all.length, '件', ((Date.now() - t0) / 1000).toFixed(1), '秒');
const ids = await client.getAllContentIds({ endpoint: 'news' });
console.log('getAllContentIds →', ids.length, '件', ids.slice(0, 3).join(','), '…');

[SDK→] GET https://rjc-demo.microcms.io/api/v1/news?limit=0
[SDK→] GET https://rjc-demo.microcms.io/api/v1/news?limit=100&offset=0
[SDK→] GET https://rjc-demo.microcms.io/api/v1/news?limit=100&offset=100
[SDK→] GET https://rjc-demo.microcms.io/api/v1/news?limit=100&offset=200
getAllContents → 250 件 2.0 秒
[SDK→] GET https://rjc-demo.microcms.io/api/v1/news?limit=0&fields=id&depth=0
[SDK→] GET https://rjc-demo.microcms.io/api/v1/news?limit=100&fields=id&depth=0&offset=0
[SDK→] GET https://rjc-demo.microcms.io/api/v1/news?limit=100&fields=id&depth=0&offset=100
[SDK→] GET https://rjc-demo.microcms.io/api/v1/news?limit=100&fields=id&depth=0&offset=200
getAllContentIds → 250 件 n001,n002,n003 …

getAllContents は、まず limit=0 で総件数だけを取り、100件ずつ offset をずらして取りました。 リクエストの間に1秒ずつ待つので、250件で約2秒かかっています（SDK のソースにも1000ミリ秒の待ちがあります）。getAllContentIds は fields=id&depth=0 を付けて ID だけを取るので、静的サイトのページの一覧を作るときに転送量を抑えられます。

microCMSのエラーと再試行（SDKの出方）

この節では、SDK で失敗したときに投げられるエラーの文と、retry: true の動きが分かります。

SDK のエラーは Error で、isMicroCMSRequestError() で見分けると status と url が取れます。 擬似 API は、ドキュメント「コンテンツ API のエラーレスポンス」の文をそのまま返すようにしました。

import { createClient, isMicroCMSRequestError } from 'microcms-js-sdk';
const show = (label, e) => console.log(`${label}\n  message: ${JSON.stringify(e.message)}\n  isMicroCMSRequestError: ${isMicroCMSRequestError(e)} | status: ${e.status} | url: ${e.url}`);

const bad = createClient({ serviceDomain: 'rjc-demo', apiKey: 'wrong-key' });
try { await bad.getList({ endpoint: 'blogs' }); } catch (e) { show('① APIキーが違う', e); }
// ②〜⑦も同じ形で試した

① APIキーが違う
  message: "fetch API response status: 401\n  message is `X-MICROCMS-API-KEY header is invalid.`"
  isMicroCMSRequestError: true | status: 401 | url: https://rjc-demo.microcms.io/api/v1/blogs
② 無いコンテンツID
  message: "fetch API response status: 404"
  isMicroCMSRequestError: true | status: 404 | url: https://rjc-demo.microcms.io/api/v1/blogs/no-such-id
③ limit が 100 を超える
  message: "fetch API response status: 400\n  message is `Invalid 'limit' value.`"
  isMicroCMSRequestError: true | status: 400 | url: https://rjc-demo.microcms.io/api/v1/blogs?limit=101
④ draftKey が違う
  message: "fetch API response status: 404"
  isMicroCMSRequestError: true | status: 404 | url: https://rjc-demo.microcms.io/api/v1/blogs/webhook-guide?draftKey=***
⑤ 無いフィールド名で POST
  message: "fetch API response status: 400\n  message is `'titel' is unexpected key.`"
  isMicroCMSRequestError: true | status: 400 | url: https://rjc-demo.microcms.io/api/v1/blogs
⑥ endpoint が空
  message: "endpoint is required"
⑦ apiKey が undefined
  message: "parameter is required (check serviceDomain and apiKey)"

• エラーの文は fetch API response status: 番号 の後に、API が返した message が続く形でした。404 は API が本文を返さないので、番号だけです。
• ④のように、url の中の draftKey の値は *** に伏せられました。 ログに残しても下書きのキーが漏れないようにする SDK の動きです。
• ⑥⑦は通信の前に SDK が投げるエラーで、isMicroCMSRequestError の対象ではありません。⑦は、環境変数の名前の打ち間違いや .env の読み込み忘れで起きます。

429（上限）とretryの動き

擬似 API を「1秒に GET 60回まで、それを超えたら 429」にして、同時に70回送りました。続けて、503 を2回返してから成功する状態にし、retry: true を付けたクライアントで送りました。

const rs = await Promise.allSettled(Array.from({ length: 70 }, () => client.getList({ endpoint: 'blogs', queries: { limit: 1, fields: 'id' } })));
console.log(`retry なし：同時に70回 GET → 成功 ${rs.filter((r) => r.status === 'fulfilled').length} 件・429 ${rs.filter((r) => r.status === 'rejected').length} 件`);

const rc = createClient({ serviceDomain: 'rjc-demo', apiKey: key, retry: true });
const r = await rc.getList({ endpoint: 'blogs', queries: { limit: 1, fields: 'id' } });

retry なし：同時に70回 GET → 成功 60 件・429 10 件
Error: fetch API response status: 503
Waiting for retry (1/2)
Error: fetch API response status: 503
Waiting for retry (2/2)
retry: true → [{"id":"nextjs-ssg"}] 21.0 秒
retry: true の 404 → 404 0.0 秒

再試行の間、SDK は console.log にエラーと Waiting for retry (1/2) を出しました。ビルドの中で使うと、待ちの分だけビルドが長くなります。たくさんのページを一度に作る静的サイトで 429 が出るときは、getAllContents で1回にまとめて取り、ページごとに API を呼ばない形にします（次の節）。

Next.jsでmicroCMSを使う（静的書き出しとプレビュー）

この節では、Next.js（App Router）で microCMS の記事を読み、静的な HTML に書き出すまでと、下書きのプレビューを作る方法が分かります。

APIキーは .env.local に置き、サーバー側（Server Component）でだけ SDK を呼びます。 ブラウザで動くコードに APIキーを入れると、誰でもキーを見られます。

# .env.local
MICROCMS_SERVICE_DOMAIN=rjc-demo
MICROCMS_API_KEY=あなたのAPIキー

// libs/microcms.ts
import { createClient } from 'microcms-js-sdk';
import type { MicroCMSListContent } from 'microcms-js-sdk';

if (!process.env.MICROCMS_SERVICE_DOMAIN || !process.env.MICROCMS_API_KEY) {
  throw new Error('MICROCMS_SERVICE_DOMAIN または MICROCMS_API_KEY が設定されていません。');
}

export const client = createClient({
  serviceDomain: process.env.MICROCMS_SERVICE_DOMAIN,
  apiKey: process.env.MICROCMS_API_KEY,
});

export type Blog = { title: string; content: string } & MicroCMSListContent;

// app/page.tsx（一覧）
import Link from 'next/link';
import { client, type Blog } from '@/libs/microcms';

export default async function Home() {
  const { contents } = await client.getList<Blog>({
    endpoint: 'blogs',
    queries: { orders: '-publishedAt', fields: 'id,title' },
  });
  return (
    <ul>
      {contents.map((b) => (
        <li key={b.id}>
          <Link href={`/blogs/${b.id}`}>{b.title}</Link>
        </li>
      ))}
    </ul>
  );
}

// app/blogs/[id]/page.tsx（記事）
import { client, type Blog } from '@/libs/microcms';

export async function generateStaticParams() {
  const ids = await client.getAllContentIds({ endpoint: 'blogs' });
  return ids.map((id) => ({ id }));
}

export default async function BlogPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const blog = await client.getListDetail<Blog>({ endpoint: 'blogs', contentId: id });
  return (
    <article>
      <h1>{blog.title}</h1>
      <section dangerouslySetInnerHTML={{ __html: blog.content }} />
    </article>
  );
}

// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // out/ に静的な HTML を書き出す
  images: { unoptimized: true },
};
export default nextConfig;

next build の出力と、書き出されたファイル、擬似 API が受けたリクエストです。

Route (app)
┌ ○ /
├ ○ /_not-found
└   /blogs/[id]
  ├ ● /blogs/nextjs-ssg
  ├ ● /blogs/astro-intro
  ├ ● /blogs/release-2026
  └ ● [+2 more paths]

○  (Static)  prerendered as static content
●  (SSG)     prerendered as static HTML (uses generateStaticParams)

out/404.html
out/_not-found.html
out/blogs/astro-intro.html
out/blogs/holiday.html
out/blogs/nextjs-ssg.html
out/blogs/release-2026.html
out/blogs/webhook-guide.html
out/index.html

GET /api/v1/blogs?limit=0&fields=id&depth=0
GET /api/v1/blogs?limit=100&fields=id&depth=0&offset=0
GET /api/v1/blogs/nextjs-ssg
GET /api/v1/blogs/astro-intro
GET /api/v1/blogs/release-2026
GET /api/v1/blogs/webhook-guide
GET /api/v1/blogs?orders=-publishedAt&fields=id%2Ctitle
GET /api/v1/blogs/holiday

generateStaticParams で ID の一覧を取り、記事のページごとに getListDetail が1回ずつ呼ばれました。 記事が5件ならリクエストは8回、記事が千件なら千回を超えます。数が多いサイトでは、上限（GET 60回/秒）と転送量の両方に関わるので、ビルドの時間とリクエストの数を見ておきます。out/ の中身（780KB、HTML は8ファイル）は、そのまま Netlify・Vercel・S3 などに置けます。

記事の数が多い・更新が多いサイトでは、静的書き出しの代わりに ISR（一定の時間ごとに作り直す）も選べます。SDK の各メソッドは customRequestInit で Next.js の fetch のオプションを渡せます。

// 60秒ごとに作り直す（output: 'export' を外したとき）
const { contents } = await client.getList<Blog>({
  endpoint: 'blogs',
  customRequestInit: { next: { revalidate: 60 } },
});

Next.js の App Router の基本は、関連記事「Next.js App Router 入門｜v16対応・実際のビルド結果つき」で扱っています。

下書きのプレビュー（画面プレビューとdraftKey）

microCMS の画面プレビューは、管理画面のボタンから、記事の ID と draftKey を入れた自分のサイトの URL を開く仕組みです。 下書きを取って表示するページは、自分で作ります。設定は、API の「API設定」→「画面プレビュー」の「遷移先URL」に、次のように書きます。

https://example.com/preview?id={CONTENT_ID}&draftKey={DRAFT_KEY}

{CONTENT_ID} と {DRAFT_KEY} は、それぞれ URL の中で1回だけ置き換えられます（2回目以降は置き換えられません）。Next.js で、このプレビュー用のページを作りました。静的書き出しではリクエストのたびに下書きを取れないので、プレビューはサーバーで動かす（output: 'export' を外す）形にします。

// app/preview/page.tsx
import { notFound } from 'next/navigation';
import { isMicroCMSRequestError } from 'microcms-js-sdk';
import { client, type Blog } from '@/libs/microcms';

// 画面プレビューの遷移先URL：https://example.com/preview?id={CONTENT_ID}&draftKey={DRAFT_KEY}
export default async function Preview({
  searchParams,
}: {
  searchParams: Promise<{ id?: string; draftKey?: string }>;
}) {
  const { id, draftKey } = await searchParams;
  if (!id || !draftKey) return <p>id と draftKey が要ります</p>;
  let blog: Blog;
  try {
    blog = await client.getListDetail<Blog>({
      endpoint: 'blogs',
      contentId: id,
      queries: { draftKey },
      customRequestInit: { cache: 'no-store' },
    });
  } catch (e) {
    // draftKey が違う・ID が無いときは 404 が返る
    if (isMicroCMSRequestError(e) && e.status === 404) notFound();
    throw e;
  }
  return (
    <article>
      <p>プレビュー（下書き）</p>
      <h1>{blog.title}</h1>
    </article>
  );
}

next build で /preview は ƒ (Dynamic) server-rendered on demand になり、next start で動かしてアクセスした結果です。

== /preview?id=webhook-guide&draftKey=dk_abc123
HTTP 200
<h1>Webhookで自動デプロイ（下書き：改訂版）</h1>
== /blogs/webhook-guide
HTTP 200
<h1>Webhookで自動デプロイ</h1>
== /preview?id=webhook-guide&draftKey=wrong
HTTP 404

公開中の記事のページは公開版のタイトル、プレビューは下書きのタイトルになりました。最初は try〜catch を書かずに動かし、draftKey が違う URL で HTTP 500 になりました（サーバーのログは Error: fetch API response status: 404）。SDK は 404 を例外で投げるので、notFound() に変えて 404 を返すようにしています。

Astro・Nuxtでの使い方

この節では、Astro で静的サイトを作った実物と、Nuxt で使う公式モジュールの書き方が分かります。

Astroで静的サイトを作る

Astro は公式のチュートリアルと同じく、.env に MICROCMS_SERVICE_DOMAIN・MICROCMS_API_KEY を置き、src/lib/microcms.ts でクライアントを作ります。

// src/lib/microcms.ts
import { createClient } from 'microcms-js-sdk';
import type { MicroCMSListContent, MicroCMSImage, MicroCMSObjectContent } from 'microcms-js-sdk';

const serviceDomain = import.meta.env.MICROCMS_SERVICE_DOMAIN;
const apiKey = import.meta.env.MICROCMS_API_KEY;
if (!serviceDomain || !apiKey) {
  throw new Error('MICROCMS_SERVICE_DOMAIN または MICROCMS_API_KEY が設定されていません。');
}

export const client = createClient({ serviceDomain, apiKey });

export type Category = { name: string } & MicroCMSListContent;
export type Blog = {
  title: string;
  content: string;
  eyecatch?: MicroCMSImage;
  category?: Category;
} & MicroCMSListContent;
export type Settings = { siteName: string; description: string } & MicroCMSObjectContent;

---
// src/pages/blogs/[id].astro
import { client, type Blog } from '../../lib/microcms';

export async function getStaticPaths() {
  const blogs = await client.getAllContents<Blog>({ endpoint: 'blogs' });
  return blogs.map((blog) => ({ params: { id: blog.id }, props: { blog } }));
}
const { blog } = Astro.props as { blog: Blog };
---
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <title>{blog.title}</title>
  </head>
  <body>
    <h1>{blog.title}</h1>
    {blog.eyecatch && (
      <img src={`${blog.eyecatch.url}?w=600&fm=webp`} width="600" alt="" />
    )}
    <article set:html={blog.content} />
  </body>
</html>

トップページ（src/pages/index.astro）は、getObject でサイトの設定を、getList で記事の一覧を取って並べました。astro build の出力と、擬似 API が受けたリクエストです。

 generating static routes 
  ├─ /blogs/nextjs-ssg/index.html (+28ms) 
  ├─ /blogs/astro-intro/index.html (+6ms) 
  ├─ /blogs/release-2026/index.html (+2ms) 
  ├─ /blogs/webhook-guide/index.html (+7ms) 
  ├─ /blogs/holiday/index.html (+5ms) 
  ├─ /index.html (+27ms) 
[build] 6 page(s) built in 705ms

GET /api/v1/blogs?limit=0
GET /api/v1/blogs?limit=100&offset=0
GET /api/v1/settings
GET /api/v1/blogs?orders=-publishedAt&fields=id%2Ctitle%2CpublishedAt%2Ccategory.name

書き出された記事のページ（dist/blogs/astro-intro/index.html）の中身です。

<!DOCTYPE html><html lang="ja"><head><meta charset="UTF-8"><title>Astroの始め方</title></head><body><h1>Astroの始め方</h1><img src="https://images.microcms-assets.io/assets/abc/def/astro-intro.png?w=600&amp;fm=webp" width="600" alt=""><article><h2 id="h1">Astroの始め方</h2><p>Astroの始め方の本文です。</p></article></body></html>

getStaticPaths で getAllContents を1回呼び、記事の中身を props で各ページに渡すと、記事が5件でもリクエストは4回で済みました。 Next.js の例（ページごとに1回、計8回）との違いです。dist/ は24KB で、JavaScript を含まない HTML だけになりました。.env を外してビルドすると、MICROCMS_SERVICE_DOMAIN または MICROCMS_API_KEY が設定されていません。 でビルドが止まります。

リッチエディタの HTML は set:html（Next.js では dangerouslySetInnerHTML）で入れます。管理画面で入力した HTML がそのまま出るので、APIキーに書き込み権限を広く付けない、編集できる人を限る、という管理側の対策と組み合わせます。

Nuxtで使う（nuxt-microcms-module）

Nuxt では、公式のモジュール nuxt-microcms-module（npm の最新は 3.1.1）を使います。

npm install nuxt-microcms-module

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-microcms-module'],
  microCMS: {
    serviceDomain: 'service-domain',
    apiKey: 'api-key',
    // target: 'server'（既定）。'all' にすると APIキーがブラウザ側のコードに入る
  },
});

<script setup lang="ts">
type Blog = { id: string; title: string };
const { data: blogs } = await useMicroCMSGetList<Blog>({
  endpoint: 'blogs',
  queries: { fields: ['id', 'title'] },
});
</script>

<template>
  <ul>
    <li v-for="blog in blogs?.contents" :key="blog.id">{{ blog.title }}</li>
  </ul>
</template>

使える関数は useMicroCMSGetList・useMicroCMSGetListDetail・useMicroCMSGetObject の3つで、中で Nuxt の useFetch を使っています。モジュールの README は、ビルド時やサーバーでだけ microCMS を呼ぶなら target: 'server' を勧めています。Nuxt で静的に書き出す設定は、関連記事「Nuxt SSR・SSGの設定｜routeRules全オプションとヘッダー実測」で扱っています。

SSG・SSR・CSRの選び方

作り方	API を呼ぶとき	記事の更新の反映	APIキー
SSG（静的書き出し）	ビルドのときだけ	Webhook で再ビルド	ビルド環境だけ
ISR	一定の時間ごと	数十秒〜の遅れ	サーバーだけ
SSR	表示のたびに	すぐ	サーバーだけ
CSR（ブラウザから）	表示のたびに	すぐ	ブラウザに見える（GET のみのキーにする）

ドキュメント「APIキー」は、ブラウザから直接 API を呼ぶ形では外部の人がキーを知ることができるので、GET だけの権限にするか、サーバーから呼ぶ形を勧めています。

Webhookで公開・更新を反映する（署名の検証）

この節では、記事を公開したときにサイトを自動で作り直す仕組みと、自分のサーバーで Webhook を受けるときの署名の確かめ方が分かります。

静的サイトでは、microCMS で記事を公開しても、再ビルドするまで表示は変わりません。 Webhook を設定すると、公開・更新・削除のときに、ビルドのサービスへ知らせが送られます。

flowchart TD
    A[記事を公開・更新] --> B[microCMS が<br>Webhook を送る]
    B --> C[Vercel・Netlify の<br>ビルドフック]
    C --> D[再ビルド<br>SDK で最新を取得]
    D --> E[新しい HTML を公開]

設定は、API の「API設定」→「Webhook」→「＋ 追加」から行います。

送り先の種類	使いどころ
Vercel・Netlify・Cloudflare Pages・AWS Amplify	ビルドフックの URL を入れて再ビルド
GitHub Actions	ワークフローを動かす
Slack・Chatwork・メール通知	編集チームへの公開のお知らせ
カスタム通知	任意の URL に JSON を POST する

知らせるタイミングは、「コンテンツの公開時・更新時」「コンテンツの公開終了時」「コンテンツの下書き保存時」「公開中コンテンツの削除時」「公開終了コンテンツの削除時」「下書きコンテンツの削除時」「公開中かつ下書き中コンテンツの下書き破棄時」「APIの設定変更時」「APIの削除時」から選べます。再ビルドに使うなら、公開・更新・公開終了・削除を選び、下書き保存は外すと、不要なビルドが減ります。

カスタム通知を受けて署名を確かめる

カスタム通知では、シークレットを設定すると、本文の HMAC-SHA256 が X-MICROCMS-Signature ヘッダーに付きます。受け口では、同じシークレットで計算した値と比べて、microCMS から来たものかを確かめます。ドキュメントの Node.js の例と同じ考え方で書いた受け口です。

// webhook-receiver.mjs
import http from 'node:http';
import crypto from 'node:crypto';

const SECRET = process.env.MICROCMS_WEBHOOK_SECRET;

function verify(rawBody, signature) {
  if (typeof signature !== 'string') return false;
  const expected = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

http.createServer((req, res) => {
  let raw = '';
  req.on('data', (c) => (raw += c));
  req.on('end', () => {
    const ok = verify(raw, req.headers['x-microcms-signature']);
    if (!ok) { console.log('署名が合わない → 401'); res.writeHead(401); return res.end(); }
    const p = JSON.parse(raw);
    console.log(`受信 OK: api=${p.api} id=${p.id} type=${p.type} status=${p.contents?.new?.status?.join(',')}`);
    // ここでビルドの開始やキャッシュの削除を行う
    res.writeHead(200); res.end('ok');
  });
}).listen(34001, '127.0.0.1', () => console.log('webhook receiver :34001'));

ドキュメントの例と同じ形の JSON（type は new・edit・delete、status は配列）を作り、正しい署名・本文を1文字変えたもの・署名なしの3通りで送りました。

{"service":"rjc-demo","api":"blogs","id":"webhook-guide","type":"edit","contents":{"old":{"id":"webhook-guide","status":["PUBLISH"],"draftKey":null,"publishValue":{"id":"webhook-guide","title":"Webhookで自動デプロイ"},"draftValue":null},"new":{"id":"webhook-guide","status":["PUBLISH"],"draftKey":null,"publishValue":{"id":"webhook-guide","title":"Webhookで自動デプロイ（改訂）"},"draftValue":null}}}

正しい署名 → HTTP 200
本文を1文字変えた → HTTP 401
署名なし → HTTP 401
signature: 8c1be2d36b9eb0e24a7fec6df24eac6721a29b79246ae4c3bbecf26ac07672ed

webhook receiver :34001
受信 OK: api=blogs id=webhook-guide type=edit status=PUBLISH
署名が合わない → 401
署名が合わない → 401

署名は「受け取ったままの本文」で計算します。 JSON.parse してから JSON.stringify し直した文字列では、空白や順番が変わって一致しなくなることがあります。ドキュメントには、送信に失敗しても再送しないこと（ネットワークのエラー・4xx・5xx のどれも）、順番は保証されないこと、送信元の IP は公開されていないことも書かれています。取りこぼしても困らないように、ビルドの側では「最新を全部取り直す」形にしておきます。署名の検証・冪等性の考え方は、関連記事「Webhookとは？実装までわかる｜署名検証・リトライ・冪等性を実行ログで解説」で、Netlify のビルドフックとデプロイは新規記事「Netlifyとは｜使い方・料金・デプロイ方法とエラー対処を実例で」で扱っています。

画像APIで画像を変換する

この節では、microCMS にアップロードした画像を、URL のパラメータだけで縮小・変換する方法が分かります。

画像の URL の末尾に ?w=600 のようなパラメータを付けると、変換した画像が返ります。 画像は images.microcms-assets.io から配信され、処理には imgix の Rendering API が使われています。

やりたいこと	パラメータの例
幅を600px にする	?w=600
高さも決める	?w=600&h=400
WebP にする	?fm=webp
AVIF にする	?fm=avif
縮小して WebP	?w=600&fm=webp
画像の情報を JSON で見る	?fm=json

ドキュメントには、?auto=format には対応していないこと、SVG には画像 API が使えないこと、Amazon S3 連携を有効にすると画像 API が使えないことが書かれています。リッチエディタの中の画像は、エディタの中で設定できるのは w と h だけなので、それ以外を付けるときは HTML から画像の URL を取り出して付け直します。

APIキーと権限の設定

この節では、APIキーにどの権限を付けるかと、キーを漏らさないための置き場所が分かります。

APIキーには、サービス全体に効く「デフォルト権限」と、API ごとに上書きする「個別権限」があります。権限は GET・下書き全取得・公開終了全取得・POST・PUT・PATCH・DELETE から選びます。キーを作れるのは管理者の権限を持つ人だけです。

• 1表示に使うキーは GET だけにしたかブラウザに見えても、記事を書き換えられない
• 2書き込み用のキーを別に分けたかPOST・PATCH・DELETE は下書きの公開もできる
• 3キーを .env に置き、Git に入れていないか.gitignore に .env と .env.local
• 4ビルドのサービスにも同じ環境変数を入れたかVercel・Netlify の画面で設定する
• 5Webhook のカスタム通知にシークレットを設定したか署名で送り元を確かめる
• 6Hobby なら転送量を毎月見ているか20GB を超えると API が止まる

.env の置き方と Git に入れない設定は、関連記事「.envの使い方と注意点｜APIキーを安全に管理する方法」で扱っています。

microCMSのよくあるエラーと直し方

この節では、エラーの文から、原因と直し方を引けます。API の文はドキュメント「コンテンツ API のエラーレスポンス」、SDK の文は実際に出たものです。

エラーの文・症状	原因	直し方
401 X-MICROCMS-API-KEY header is invalid.	APIキーが違う・ヘッダーが無い	キーをコピーし直す。環境変数の名前を確かめる
parameter is required (check serviceDomain and apiKey)	環境変数が読めていない	.env・.env.local の場所、ビルド環境の設定
400 GET is forbidden.	キーに GET の権限が無い	APIキーの権限（デフォルト・個別）を確かめる
404（本文なし）	エンドポイント・ID が違う、未公開	管理画面の API プレビューで URL を確かめる
プレビューで 404	draftKey が違う・別の記事のもの	管理画面のプレビューボタンから開き直す
400 Invalid 'limit' value.	limit が 0〜100 の外	100件を超えるなら getAllContents
400 Response body size is too long.	応答が約5MB を超えた	fields で本文を外す・limit を下げる
400 'titel' is unexpected key.	スキーマに無いフィールド ID	フィールド ID の綴りを確かめる
429 Too many requests, please try again later.	GET 60回/秒・書き込み5回/秒を超えた	まとめて取る・retry: true・間隔をあける
400 API is stopped for xxxxxxxx service.	プランの上限で API が止まっている（Hobby の転送量など）	翌月1日まで待つかプランを上げる
記事を変えたのにサイトが変わらない	静的サイトを再ビルドしていない	Webhook でビルドフックを呼ぶ
日付が9時間ずれる	API の日時は UTC	表示のときに日本時間に変換する

エラーの本文は { "message": "…" } の形です。ドキュメントは、メッセージの文は予告なく変わることがあるので、文で処理を分けないこととしています。処理を分けるときは、SDK のエラーの status（数値）を見ます。

WordPress・Contentful・Strapiとの違い

この節では、よく比べられる CMS との違いが、公式に書かれている事実で分かります（2026年10月22日時点）。

比べる点	microCMS	WordPress	Contentful	Strapi
形	ヘッドレス（SaaS）	表示まで含む CMS（REST API も標準）	ヘッドレス（SaaS）	ヘッドレス（自分で動かす・Cloud）
動かす場所	microCMS のサーバー	自分のサーバー・レンタル	Contentful のサーバー	自分のサーバーか Strapi Cloud
無料の範囲	Hobby：API 5個・20GB/月	ソフトは無料（GPL）。サーバー代は別	Free：10ユーザー・API 10万回/月	Community 版：無料（MIT）
有料の始まり	Team 4,900円〜/月	―	Lite 300ドル/月	Growth 45ドル/月（自分で動かす版）
API	REST（コンテンツ API）	REST	REST・GraphQL	REST（GraphQL はプラグイン）

microCMSが向いているサイト・向いていないサイト

状況	向き	理由
Next.js・Astro などで作る企業サイト・ブログ	向いている	記事だけを API で受け取り、画面は自由に作れる
編集者は日本語の画面で書きたい	向いている	管理画面・ヘルプが日本語
同じ記事を Web とアプリに出す	向いている	API で JSON を返すだけなので出し先を選ばない
CMS のサーバーを持ちたくない	向いている	SaaS で運用は microCMS 側
フロントエンドを作る人がいない	向いていない	表示の部分は自分で開発する
プラグインで機能を足していきたい	向いていない	WordPress のようなプラグインの仕組みは無い
記事が数万件で頻繁に更新する静的サイト	設計が要る	再ビルドの時間と API の上限を見積もる

よくある質問

Q. microCMSとは簡単に言うと何ですか？ A. 管理画面で書いた記事を API（JSON）で取り出せる、日本製のヘッドレス CMS です。表示する Web サイトは Next.js などで自分で作ります（「microCMSとは」の節の図）。

Q. microCMSの読み方は？ A. 「マイクロシーエムエス」です。提供しているのは株式会社microCMS です。

Q. microCMSは無料で使えますか？商用利用はできますか？ A. Hobby プランは0円で、API 5個・メンバー3人・転送量20GB/月まで使えます。ヘルプセンターでは、法人の Web サイトでも Hobby を使えると回答しています。転送量が20GB を超えると翌月1日まで API が止まります。

Q. microCMSの料金はいくらですか？ A. 2026年10月22日時点で、Hobby 0円、Team 4,900円〜/月、Business 75,000円〜/月、Enterprise は見積もりです（税抜）。転送量・API 数・メンバーを超えた分は加算されます。

Q. リスト形式とオブジェクト形式の違いは？ A. 記事のように複数あるものはリスト形式（contents の配列が返る）、サイトの設定のように1つだけのものはオブジェクト形式（オブジェクトが1つ返る）です。

Q. microCMSのAPIで100件より多く取るには？ A. limit の上限は100なので、offset をずらして複数回取ります。SDK の getAllContents がこれを自動で行い、250件で4回のリクエストになりました。

Q. Next.jsでmicroCMSを使うには？ A. microcms-js-sdk を入れ、APIキーを .env.local に置き、Server Component で getList・getListDetail を呼びます。静的に書き出すなら generateStaticParams で記事の ID を渡します（Next.js の節）。

Q. 記事を公開したのにサイトに反映されません。 A. 静的サイトは再ビルドするまで変わりません。Webhook で Vercel・Netlify などのビルドフックを呼ぶと、公開のたびに自動で作り直せます。

Q. 下書きをプレビューするには？ A. 「API設定」→「画面プレビュー」に {CONTENT_ID} と {DRAFT_KEY} を入れた URL を設定し、そのページで draftKey を付けて記事を取ります。draftKey が違うと 404 が返ります。

Q. APIキーをフロントエンドに書いても問題ありませんか？ A. ブラウザで動くコードに入れたキーは誰でも見られます。ドキュメントは、GET だけの権限のキーにするか、サーバーから API を呼ぶ形を勧めています。

Q. microCMSとWordPressの違いは？ A. WordPress は記事の保存と表示が1つになった CMS で、自分のサーバーで動かします。microCMS は表示の部分を持たず、記事を API で返すだけの SaaS です（違いの表）。

Q. microCMSはAIやMCPに対応していますか？ A. microCMS が運営する MCP サーバー（ベータ）があり、MCP に対応した AI ツールから記事の取得・作成・公開状態の変更などができます。できる操作は APIキーの権限で決まります。

まとめ

• microCMS は、記事を API（JSON）で配る日本製のヘッドレス CMS。表示は Next.js・Astro・Nuxt などで自分で作る。
• 料金は Hobby 0円・Team 4,900円〜・Business 75,000円〜・Enterprise 見積もり（2026年10月22日時点・税抜）。Hobby は転送量20GB/月を超えると API が止まる。転送量のほとんどは画像。
• API はリスト形式とオブジェクト形式。GET /api/v1/{endpoint} に X-MICROCMS-API-KEY を付け、limit（最大100）・orders・fields・filters・depth で絞る。
• microcms-js-sdk は getList・getListDetail・getObject・getAllContents。エラーは isMicroCMSRequestError で status を見る。retry: true は 429 と 500 番台だけを最大2回再試行する。
• 静的サイトは Webhook で再ビルドし、カスタム通知は受け取ったままの本文で署名を確かめる。下書きは画面プレビューと draftKey で表示する。
• 表示用の APIキーは GET だけにし、サーバー側で呼ぶ。

参考・出典

確認日はいずれも 2026年10月22日です。

• microCMS「料金プラン」：https://microcms.io/pricing
• microCMS ドキュメント「はじめに」：https://document.microcms.io/manual/getting-started
• microCMS ドキュメント「APIの作成」：https://document.microcms.io/manual/create-api
• microCMS ドキュメント「GET /api/v1/{endpoint}」：https://document.microcms.io/content-api/get-list-contents
• microCMS ドキュメント「GET APIのフィールドのレスポンス」：https://document.microcms.io/content-api/get-api-field-responses
• microCMS ドキュメント「コンテンツAPIのエラーレスポンス」：https://document.microcms.io/content-api/api-error-response
• microCMS ドキュメント「X-MICROCMS-API-KEY」：https://document.microcms.io/content-api/x-microcms-api-key
• microCMS ドキュメント「制限事項」：https://document.microcms.io/manual/limitations
• microCMS ドキュメント「コンテンツのWebhookを設定」：https://document.microcms.io/manual/webhook-setting
• microCMS ドキュメント「画面プレビュー」：https://document.microcms.io/manual/screen-preview
• microCMS ドキュメント「画像API」：https://document.microcms.io/image-api/introduction
• microCMS ドキュメント「画像API フォーマット」：https://document.microcms.io/image-api/format
• microCMS ドキュメント「セレクトフィールド」：https://document.microcms.io/manual/select-field
• microCMS ドキュメント「Next.js（App Router）チュートリアル」：https://document.microcms.io/tutorial/next/next-app-router-getting-started
• microCMS ドキュメント「Astro チュートリアル」：https://document.microcms.io/tutorial/astro/astro-getting-started
• microCMS ドキュメント「Nuxt チュートリアル」：https://document.microcms.io/tutorial/nuxt/nuxt-getting-started
• microCMS ドキュメント「microCMS MCP」：https://document.microcms.io/en/mcp-server/microcms-mcp
• microCMS ヘルプセンター「Hobbyプランを法人のウェブサイトで使うことは可能ですか？」：https://help.microcms.io/ja/knowledge/free-plan-for-corporation
• microCMS ヘルプセンター「データ転送量とは何ですか？」：https://help.microcms.io/ja/knowledge/what-is-data-amount
• microCMS ヘルプセンター「データ転送量の試算をしたいです。」：https://help.microcms.io/ja/knowledge/estimate-data-amount
• 株式会社microCMS：https://microcms.co.jp/
• microcms-js-sdk（GitHub）：https://github.com/microcmsio/microcms-js-sdk
• nuxt-microcms-module（GitHub）：https://github.com/microcmsio/nuxt-microcms-module
• Contentful「Pricing」：https://www.contentful.com/pricing/
• Contentful「GraphQL Content API」：https://www.contentful.com/developers/docs/references/graphql/
• Strapi「Self-hosted pricing」：https://strapi.io/pricing-self-hosted
• Strapi Docs「GraphQL plugin」：https://docs.strapi.io/cms/plugins/graphql
• WordPress Developer Resources「REST API Handbook」：https://developer.wordpress.org/rest-api/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。