skills/microcms-guide/references/getting-started.md

# microCMS はじめ方・基本概念

最終確認: 2026-09-08

仕様の根拠は末尾の公式情報を参照する。設計上の推奨・コード例は本Skillの提案であり、唯一の公式推奨構成を意味しない。

## 目次

- [このリファレンスの役割](#このリファレンスの役割)
- [基本構造](#基本構造)
- [APIの形式を選ぶ](#apiの形式を選ぶ)
- [コンテンツAPIを利用する](#コンテンツapiを利用する)
- [APIキーを安全に扱う](#apiキーを安全に扱う)
- [コンテンツAPIとマネジメントAPIを使い分ける](#コンテンツapiとマネジメントapiを使い分ける)
- [最初の設計で確認すること](#最初の設計で確認すること)
- [回答・実装時の判断ルール](#回答実装時の判断ルール)
- [公式情報](#公式情報)

## このリファレンスの役割

microCMSを初めて扱うユーザーや、プロジェクトの基本構成を整理したいユーザーに対して、フレームワークに依存しない前提知識と判断基準を提供する。

microCMSの機能を網羅的に説明することを目的にしない。ユーザーが実現したいサイト・アプリケーションに必要な概念だけを提示し、詳細は対応するリファレンスへ委ねる。

## 基本構造

microCMSでは、基本的に次の単位で考える。

- **サービス**: プロジェクト全体をまとめる単位。サービスドメインはコンテンツAPIのURLに利用する。
- **API**: 記事、カテゴリ、著者、サイト設定など、管理したいコンテンツのまとまり。
- **APIスキーマ**: APIにどのフィールドを持たせるかを定義したもの。
- **コンテンツ**: 定義したAPIスキーマに従って入稿されるデータ。
- **コンテンツAPI**: 公開コンテンツの取得や、権限を付与したAPIキーによるコンテンツ操作に利用するAPI。
- **マネジメントAPI**: コンテンツのメタ情報など、管理用途の情報取得・操作に利用するAPI。

ユーザーが「microCMSに何を作ればよいか」と聞いている場合、画面単位でAPIを増やす前に、まず管理したい情報の単位を整理する。

例:

- ブログ記事が複数存在する → `articles` のリスト形式API
- 記事からカテゴリを参照したい → `categories` のリスト形式API
- サイト共通の会社情報を1件だけ管理したい → `settings` などのオブジェクト形式API

詳細なモデリング判断は `content-modeling.md` を読む。

## APIの形式を選ぶ

microCMSではAPI作成時に「リスト形式」と「オブジェクト形式」を選択する。

### リスト形式

同じ構造のコンテンツを複数管理する場合に使用する。

代表例:

- 記事
- お知らせ
- 商品
- 導入事例
- 著者
- カテゴリ
- タグ

「一覧」「詳細」という概念があるコンテンツは、まずリスト形式を検討する。

### オブジェクト形式

同じ構造のコンテンツを1件だけ管理する場合に使用する。

代表例:

- サイト設定
- トップページ専用データ
- 会社情報
- 共通バナー設定
- 固定プロフィール

単一データで十分なのに、リスト形式で1件だけ作成して運用する設計は避ける。逆に、将来的に複数件になる可能性が明確ならリスト形式を検討する。

## コンテンツAPIを利用する

コンテンツAPIの基本URLは次の形式になる。

```text
https://{SERVICE_DOMAIN}.microcms.io/api/v1/{ENDPOINT}
```

GETリクエストでは通常、`X-MICROCMS-API-KEY` ヘッダーへAPIキーを指定する。

```bash
curl "https://example.microcms.io/api/v1/articles" \
  -H "X-MICROCMS-API-KEY: $MICROCMS_API_KEY"
```

リスト形式の一覧取得では、必要に応じて `limit`、`offset`、`orders`、`fields`、`filters`、`q`、`depth` などのクエリパラメータを利用する。

クエリを多用する実装では、フロントエンドで全件取得してから加工するのではなく、可能ならコンテンツAPI側で必要なデータへ絞り込む。

JavaScript / TypeScriptから利用する場合は、`microcms-js-sdk` を使うとAPI呼び出しを簡潔に書ける。詳細は `js-sdk.md` を読む。

## APIキーを安全に扱う

APIキーは「存在するか」だけではなく、**付与されている権限と利用場所をセットで判断する**。

### 基本方針

- サーバーサイドで利用できる場合は、原則としてAPIキーをサーバー側に置く。
- GitリポジトリへAPIキーを直接コミットしない。
- 書き込み権限を持つAPIキーをクライアントへ露出させない。
- 全下書き取得や非公開コンテンツ取得など、公開してはいけない情報へアクセスできるAPIキーをクライアントへ露出させない。
- Draft Keyを恒久的な公開値として扱わない。
- APIキーには用途に必要な最小限の権限を与える。

### CSRでAPIキーを利用する場合

CSRではブラウザからAPIリクエストを行うため、APIキーはユーザーから確認可能になる。

そのため、CSRを採用する場合は少なくとも次を満たしているか確認する。

- 対象APIのコンテンツを一般公開して問題ない。
- APIキーは対象APIへのGET専用とし、下書き全取得などの追加権限を持たない。
- 下書き・非公開コンテンツ・書き込み操作へアクセスできない。

「APIキーが見えるから必ず脆弱」という単純な説明はしない。一方で、隠せる構成ならサーバー側に置く方を優先する。

GET専用でも、画面で使っていないフィールドや表示件数を超えたコンテンツまで取得されうる。`fields`・`limit`・`filters` はアクセス制御ではない。APIキーのデフォルト権限とAPIごとの個別権限を確認し、同じキーで別APIも読めないか確認する。[公式ヘルプ：APIキーの公開範囲](https://help.microcms.io/ja/knowledge/hide-api-key)

## コンテンツAPIとマネジメントAPIを使い分ける

通常のサイト表示に必要なコンテンツ取得は、まずコンテンツAPIを使用する。

マネジメントAPIは、コンテンツの管理情報やメタ情報など、通常の配信データとは異なる管理用途が必要な場合に検討する。

次のような依頼では、用途を明確にしてからAPIを選ぶ。

- 「サイトに記事を表示したい」 → コンテンツAPI
- 「コンテンツをAPI経由で登録・更新したい」 → 必要な権限を付与したコンテンツAPIのWrite APIを検討
- 「管理上のメタ情報を取得したい」 → マネジメントAPIを検討

「管理画面に関係するからマネジメントAPI」という名前だけの判断はしない。実現したい操作がどのAPIで提供されているかを確認する。

## 最初の設計で確認すること

新しいmicroCMSプロジェクトの相談では、必要なものだけを順に確認する。

1. **何を管理したいか**
   - 記事、商品、事例、ページ、設定など。
2. **同じ種類のデータが複数存在するか**
   - リスト形式 / オブジェクト形式の判断材料になる。
3. **他のコンテンツから再利用する情報があるか**
   - カテゴリ、著者、タグなどは参照API候補になる。
4. **公開前プレビューが必要か**
   - 必要なら `preview.md` を読む。
5. **コンテンツ更新を外部へ通知する必要があるか**
   - 必要なら `webhooks.md` を読む。
6. **画像や大量データを扱うか**
   - 必要なら `image-api.md` と `performance.md` を読む。
7. **どのフレームワークから利用するか**
   - Next.js固有の実装は `microcms-nextjs` へ委ねる。

## 回答・実装時の判断ルール

- まずユーザーの目的を確認し、microCMSの概念説明は必要な範囲に限定する。
- APIを新設する前に、既存APIの責務と再利用可能性を確認する。
- フロントエンドの都合だけで編集者に不自然な入力構造を強制しない。
- 公開サイト表示ではコンテンツAPIを第一候補とする。
- APIキーの扱いでは、公開可否・権限・実行場所の3点を確認する。
- SDK固有の実装は `js-sdk.md`、画像は `image-api.md`、パフォーマンスは `performance.md` に委ねる。
- Next.js固有の環境変数、Server Components、キャッシュ、Draft Modeなどは `microcms-nextjs` に委ねる。

## 公式情報

- [APIの作成・管理](https://document.microcms.io/manual/create-api)
- [コンテンツAPI](https://document.microcms.io/content-api/get-list-contents)
- [APIキーと権限](https://document.microcms.io/content-api/x-microcms-api-key)