Kuroco API連携 & コンテンツ管理

Kuroco HeadlessCMSのAPI設計・実装およびコンテンツ管理に関するベストプラクティス。

ドキュメント参照: /kuroco-docs スキルを使用してKuroco公式ドキュメントを検索・参照できます。

目次

Part 1: API連携パターン

• エンドポイント設計
• セキュリティ設定
• キャッシュ戦略
• 流量制限
• API呼び出しパターン
• エラーハンドリング

Part 2: コンテンツ管理パターン

• コンテンツ構造
• 拡張項目（カスタムフィールド）
• Topics API オペレーション
• コンテンツCRUD操作
• フィルタークエリ → 詳細は references/filter-query.md
• ファイル・CSV操作 → 詳細は references/file-operations.md
• 管理API（admin_api）によるコンテンツ操作

Part 1: API連携パターン

エンドポイント設計

基本構造

KurocoのAPIパスは以下の形式：

https://{サイトキー}.g.kuroco.app/rcms-api/{api_id}/{endpoint_path}

例：

https://example.g.kuroco.app/rcms-api/1/news
https://example.g.kuroco.app/rcms-api/1/member/login

エンドポイント設定の主要項目

主要カテゴリとモデル

認証（Authentication）

コンテンツ（Topics）

メンバー（Member）

フォーム（InquiryMessage/InquiryForm）

セキュリティ設定

詳細リファレンス: セキュリティ設定の詳細は references/security-settings.md を参照してください。

公式ドキュメント: 詳細な公式情報は ../kuroco-docs/docs/management/api-security.md 等を参照してください。

認証方式

管理画面: [API] → [セキュリティ] で4種類から選択。

1. Cookie認証（Webアプリ推奨）

セッションベースの認証。credentials: 'include' が必須。

// ログイン
const response = await fetch('https://example.g.kuroco.app/rcms-api/1/login', {
  method: 'POST',
  credentials: 'include',  // 必須
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
})

// レスポンス例
// {
//   "grant_token": "xxxxx",
//   "status": 0,
//   "member_id": 123
// }

注意点:

• サードパーティCookie問題（Safari等でブロックされる）
• APIドメインとフロントエンドを**同一ドメイン（サブドメイン違い）**に設定が必要（ファーストパーティCookie化）
  • 例: api.example.com と www.example.com
• Cookie認証APIが複数ある場合、各API間で認証状態が共有される

2. トークン認証（モバイルアプリ推奨）

JWTベースの認証。ヘッダーにトークンを付与。

// トークン取得
const tokenResponse = await fetch('https://example.g.kuroco.app/rcms-api/1/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
})

const { access_token, refresh_token } = await tokenResponse.json()

// レスポンス例
// {
//   "access_token": {
//     "value": "eyJhbGciOiJS...",
//     "expiresAt": "2024-01-01T12:00:00+09:00"
//   },
//   "refresh_token": {
//     "value": "xxxxxx",
//     "expiresAt": "2024-01-08T12:00:00+09:00"
//   }
// }

// API呼び出し時
const response = await fetch('https://example.g.kuroco.app/rcms-api/1/news', {
  headers: {
    'X-RCMS-API-ACCESS-TOKEN': access_token.value
  }
})

前提条件: ユーザー1人以上、login_challenge + token エンドポイント必須。トークン認証APIが複数ある場合、各API間で認証状態は共有されない。

3. StaticToken認証（サーバー間通信）

固定トークンによるAPIアクセス制限。

const response = await fetch('https://example.g.kuroco.app/rcms-api/1/internal-api', {
  headers: {
    'X-RCMS-API-ACCESS-TOKEN': 'your-static-token-here'
  }
})

設定場所: 管理画面 → API → セキュリティ → StaticToken

注意: 静的トークンはフロントエンドに組み込まれるとユーザーに見える。流出時のトークン更新を想定した運用が必要。

IPアドレス制限

管理画面: [API] → [セキュリティ] → [IPアドレス制限]

指定されたIPアドレスからのアクセスのみ許可します。

IPアドレスグループ: 定数機能で IPSETS_* を定義し、[[IPSETS_*]] で参照可能（../kuroco-docs/docs/faq/is-it-possible-to-set-multiple-ip-addresses-at-once.mdx 参照）。

CORS設定

管理画面: [API] → [セキュリティ] → [CORS]

CSRF対策: CORS + Content-Type: application/json でモダンブラウザでのCSRF攻撃を防御。ワイルドカードを使うと防御効果がなくなるため、必ず特定ドメインを指定すること。

変更反映の遅延: CORS設定変更後は CORS_MAX_AGE 分だけブラウザにキャッシュされる。即時反映にはブラウザキャッシュクリアまたは CORS_MAX_AGE を 0 に設定。

APIリクエスト制限

閲覧制限の優先順序

コンテンツ返却時の制限は以下の順序で評価されます（上位優先）:

1. API → IPアドレス制限（API全体）
2. エンドポイント → APIリクエスト制限（エンドポイント単位）
3. コンテンツ定義 → APIリクエスト制限
4. コンテンツカテゴリ → APIリクエスト制限
5. 個別コンテンツ → APIリクエスト制限

後処理によるレスポンス制限

管理画面: [API] → エンドポイント → [後処理]

APIレスポンスから不要なフィールドを除外し、公開情報を制御:

パフォーマンスTip: 出力許可リストは他の処理の前に配置するとSQLレベルで効果あり。

プラットフォームセキュリティ

Kurocoプラットフォームが提供するインフラレベルのセキュリティ:

• 通信: HTTPS完全暗号化、TLS証明書自動管理
• 防御: WAF、CDN、DDoS対策（オプションでFastly DDoS Protection）
• 認証連携: SAML/OAuth外部ログイン、クライアント証明書（オプション）
• 監査: アクセスログ、アプリケーションログ
• 認定: ISMS (ISO 27001)、ISMSクラウド (ISO 27017)、プライバシーマーク
• 診断: 毎日のコンテナ脆弱性スキャン、VADDY連携自動診断

管理API（admin_api）による設定変更

APIのセキュリティ設定は管理画面だけでなく、管理API経由でも操作可能です。/kuroco-admin-api スキルを使用してCLI経由で管理APIを実行できます。

キャッシュ戦略

推奨設定

重要: コンテンツ・メンバー等のデータ更新時、キャッシュは自動クリアされます。

キャッシュヘッダー

レスポンスヘッダーで確認可能：

Cache-Control: max-age=86400

流量制限

レスポンスヘッダー

x-rcms-ratelimit-limit: 100      # 制限数
x-rcms-ratelimit-remaining: 95   # 残りリクエスト数
x-rcms-ratelimit-reset: 60       # リセットまでの秒数

429エラー時の対応

const response = await fetch(url)

if (response.status === 429) {
  const resetTime = response.headers.get('x-rcms-ratelimit-reset')
  throw new Error(`流量制限超過。${resetTime}秒後に再試行してください`)
}

API呼び出しパターン

一覧取得（ページネーション付き）

async function fetchNewsList(page = 1, perPage = 10) {
  const params = new URLSearchParams({
    pageID: page,
    cnt: perPage
  })

  const response = await fetch(
    `https://example.g.kuroco.app/rcms-api/1/news?${params}`,
    { credentials: 'include' }
  )

  const data = await response.json()

  // レスポンス構造
  // {
  //   "list": [...],
  //   "pageInfo": {
  //     "totalCnt": 100,
  //     "perPage": 10,
  //     "totalPageCnt": 10,
  //     "pageNo": 1
  //   }
  // }

  return data
}

フィルター検索

// filter パラメータで検索
const params = new URLSearchParams({
  filter: 'subject contains "重要"',
  order_by: 'ymd desc'
})

const response = await fetch(
  `https://example.g.kuroco.app/rcms-api/1/news?${params}`,
  { credentials: 'include' }
)

詳細取得

async function fetchNewsDetail(topicsId) {
  const response = await fetch(
    `https://example.g.kuroco.app/rcms-api/1/newsdetail/${topicsId}`,
    { credentials: 'include' }
  )

  const data = await response.json()

  // レスポンス構造
  // {
  //   "details": {
  //     "topics_id": 1,
  //     "subject": "タイトル",
  //     "contents": "<p>本文</p>",
  //     ...
  //   }
  // }

  return data.details
}

コンテンツ作成

async function createNews(newsData) {
  const response = await fetch(
    'https://example.g.kuroco.app/rcms-api/1/news/insert',
    {
      method: 'POST',
      credentials: 'include',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        subject: newsData.title,
        contents: newsData.body,
        ymd: newsData.date,
        topics_flg: 1  // 1: 公開, 0: 非公開
      })
    }
  )

  return response.json()
}

エラーハンドリング

主要エラーコード

エラーレスポンス例

{
  "errors": [
    {
      "code": "authentication_error",
      "message": "ログインが必要です"
    }
  ]
}

エラーハンドリング実装

async function apiRequest(url, options = {}) {
  const response = await fetch(url, {
    credentials: 'include',
    ...options
  })

  if (!response.ok) {
    const errorData = await response.json()

    switch (response.status) {
      case 401:
        throw new Error('認証が必要です')
      case 403:
        throw new Error('アクセス権限がありません')
      case 429:
        throw new Error('リクエスト制限を超えました')
      default:
        throw new Error(errorData.errors?.[0]?.message || 'APIエラー')
    }
  }

  return response.json()
}

Part 2: コンテンツ管理パターン

コンテンツ構造

階層構造

コンテンツ定義（TopicsGroup）
├── カテゴリ（TopicsCategory）
│   └── コンテンツ（Topics）
└── 拡張項目（ext_col_01〜ext_col_XX）

コンテンツ定義の設定

管理画面: [コンテンツ定義] → [新規作成]

拡張項目（カスタムフィールド）

Topics API オペレーション

コンテンツCRUD操作

一覧取得レスポンス

{
  "list": [
    {
      "topics_id": 1,
      "subject": "タイトル",
      "contents": "本文（HTML）",
      "ymd": "2024-01-01",
      "topics_flg": 1,
      "category_id": 1,
      "ext_col_01": "拡張項目値",
      "tag": ["タグ1", "タグ2"]
    }
  ],
  "pageInfo": {
    "totalCnt": 100,
    "perPage": 10,
    "totalPageCnt": 10,
    "pageNo": 1
  }
}

コンテンツ作成

const response = await fetch('/rcms-api/1/news/insert', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    subject: 'タイトル',
    contents: '<p>本文</p>',
    ymd: '2024-01-01',
    topics_flg: 1,           // 1: 公開, 0: 非公開
    category_id: 1,
    open_ymd: '2024-12-01',  // 予約公開開始日
    close_ymd: '2024-12-31', // 公開終了日
    tag: ['タグ1', 'タグ2'],
    ext_col_01: 'カスタム値'
  })
})

コンテンツ更新

const response = await fetch(`/rcms-api/1/news/update/${topicsId}`, {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    subject: '更新タイトル',
    contents: '更新本文'
    // 更新したいフィールドのみ送信可能
  })
})

コンテンツ削除

await fetch(`/rcms-api/1/news/delete/${topicsId}`, {
  method: 'POST',
  credentials: 'include'
})

フィルタークエリ

基本構文: filter={field} {operator} {value}

複合条件: filter=(category_id = 1 or category_id = 2) and topics_flg = 1

ソート: order_by=ymd desc

詳細な使い方: references/filter-query.md を参照

ファイル・CSV操作

ファイルアップロード

// 1. ファイルアップロード
const formData = new FormData()
formData.append('file', file)
const result = await fetch('/rcms-api/1/files/upload', {
  method: 'POST',
  credentials: 'include',
  body: formData
})
const { file_id } = await result.json()

// 2. コンテンツに紐付け
await fetch('/rcms-api/1/news/insert', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    subject: 'タイトル',
    ext_col_02: { file_id, desc: '説明' }
  })
})

詳細（一括更新、カテゴリ、タグ、閲覧制限）: references/file-operations.md を参照

管理API（admin_api）によるコンテンツ操作

/kuroco-admin-api スキルを使うと、管理画面と同等のコンテンツ操作をCLI経由で実行できます。フロントエンドAPI（rcms-api）との違いに注意してください。

フロントエンドAPI vs 管理API

コンテンツ定義一覧の取得

# admin_api: コンテンツ定義（TopicsGroup）一覧（columnsで必要カラムのみ取得）
kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json

コンテンツ一覧の取得

# admin_api: 特定コンテンツ定義のコンテンツ一覧（columnsで必要カラムのみ取得）
kuroco-admin exec topics/topics_list --param "topics_group_id[]=1" --param cnt=10 --columns topics_id,subject,ymd --json

コンテンツの作成

# admin_api: コンテンツ作成（※実行前にユーザー確認必須）
kuroco-admin exec topics/topics_edit --MODE INSERT --data '{"subject":"タイトル","contents":"本文","topics_group_id":1,"topics_flg":1}' --json

活用シーン

• サイト構造の把握: コンテンツ定義一覧・拡張項目の確認
• データの一括確認・修正: 管理画面GUIを経由せず効率的にデータ操作
• スキーマ確認: kuroco-admin help topics/topics_edit --json でフィールド定義を取得

注意: insert/update/deleteは必ずユーザーに確認してから実行すること。詳細は /kuroco-admin-api スキル参照。

ベストプラクティス

• キャッシュ活用: エンドポイント設定で キャッシュ: 86400（1日）を設定。更新時は自動クリア
• ページネーション: pageID と cnt パラメータで分割取得

関連スキル

• /kuroco-frontend-integration - Nuxt.js/Next.jsでのAPI呼び出しパターン、AI自動デプロイ
• /kuroco-server-processing - Smartyプラグイン・構文リファレンス、Webhook・バッチ処理
• /kuroco-admin-api - 管理API（admin_api）の操作

関連ドキュメント

スキル内リファレンス

• references/security-settings.md - セキュリティ設定の詳細リファレンス
• references/filter-query.md - フィルタークエリ詳細
• references/file-operations.md - ファイル・CSV操作詳細

Kuroco公式ドキュメント

• ../kuroco-docs/docs/management/api-security.md - APIセキュリティ設定（認証方式、IP制限）
• ../kuroco-docs/docs/management/api-list.md - API一覧・CORS設定
• ../kuroco-docs/docs/management/api-postprocessing.md - API後処理の設定
• ../kuroco-docs/docs/reference/endpoint-settings.md - エンドポイント設定項目一覧
• ../kuroco-docs/docs/reference/post-processing.md - 後処理の詳細リファレンス
• ../kuroco-docs/docs/tutorials/configure-endpoint.md - エンドポイント設定方法
• ../kuroco-docs/docs/tutorials/login.md - ログイン実装
• ../kuroco-docs/docs/tutorials/restricting-api-access-with-statictoken.md - StaticToken認証
• ../kuroco-docs/docs/reference/api-cache.md - APIキャッシュ
• ../kuroco-docs/docs/reference/filter-query.md - フィルタークエリ
• ../kuroco-docs/docs/about/security.md - プラットフォームセキュリティ概要
• ../kuroco-docs/docs/faq/in-what-order-are-viewing-restrictions-applied.mdx - 閲覧制限の優先順序
• ../kuroco-docs/docs/faq/cors-and-content-type-prevent-csrf-attacks.mdx - CSRF対策
• ../kuroco-docs/docs/faq/the-api-returns-403-forbidden-even-though-no-restrictions-are-applied.mdx - 403エラーの解決
• ../kuroco-docs/docs/tutorials/adding-a-topics.md - コンテンツ定義作成
• ../kuroco-docs/docs/tutorials/bulk-upload-in-csv.md - CSVアップロード
• ../kuroco-docs/docs/management/content-structure-topics.md - コンテンツ構造