Kuroco コンテンツ管理パターン

Kuroco HeadlessCMSでのコンテンツ管理（作成・取得・更新・削除）に関するベストプラクティス。

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

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

コンテンツ構造

階層構造

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

コンテンツ定義の設定

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

項目	説明
グループ名	コンテンツ定義の名前
識別子	ユニークなID（英数字）
本文の入力方法	WYSIWYG、マークダウン、HTML
閲覧制限	全員/グループ制限/カスタム検索
編集制限	全員/グループ制限/カスタム検索
拡張項目	カスタムフィールド（最大99個）

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

タイプ	説明	APIレスポンス例
テキスト	1行テキスト	`"ext_col_01": "値"`
テキストエリア	複数行テキスト	`"ext_col_02": "複数行\nテキスト"`
WYSIWYG	リッチテキスト	`"ext_col_03": "<p>HTML</p>"`
数値	整数・小数	`"ext_col_04": 100`
日付	日付選択	`"ext_col_05": "2024-01-01"`
選択（単一）	ラジオボタン	`"ext_col_06": "選択肢1"`
選択（複数）	チェックボックス	`"ext_col_07": ["選択肢1", "選択肢2"]`
ファイル/画像	アップロード	`"ext_col_08": { "id": "xxx", "url": "https://...", "desc": "" }`
リンク	URLリンク	`"ext_col_10": { "url": "https://...", "title": "リンク名" }`
関連コンテンツ	他コンテンツ参照	`"ext_col_11": { "topics_id": 123, "subject": "タイトル" }`

Topics API オペレーション

オペレーション	説明	メソッド	パス例
list	一覧取得	GET	`/news`
details	詳細取得	GET	`/newsdetail/{topics_id}`
insert	新規追加	POST	`/news/insert`
update	更新	POST	`/news/update/{topics_id}`
delete	削除	POST	`/news/delete/{topics_id}`
bulk_upsert	一括更新	POST	`/news/bulk`

コンテンツ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`
`>`, `>=`, `<`, `<=`	`filter=ymd >= '2024-01-01'`
`contains`	`filter=subject contains 'キーワード'`
`in`, `not_in`	`filter=category_id in [1, 2, 3]`

複合条件: 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（mng_api）によるコンテンツ操作

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

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

項目	フロントエンドAPI（rcms-api）	管理API（mng_api）
対象	エンドユーザー	管理者・運用者
認証	StaticToken / DynamicToken / Cookie	管理画面セッションCookie
エンドポイント	`/rcms-api/{api_id}/{path}`	`/direct/rcms_api/mng_api/`
利用場面	フロントエンド実装	データ一括操作、構造確認、設定変更

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

// mng_api: コンテンツ定義（TopicsGroup）一覧（columnsで必要カラムのみ取得）
const r = await fetch('/direct/rcms_api/mng_api/?mt=topics&ct=topics_group_list&columns=topics_group_id,group_nm', {credentials:'include'});
const data = await r.json();
JSON.stringify(data.topics_group_list?.map(g => ({id: g.topics_group_id, name: g.group_nm})));

コンテンツ一覧の取得

// mng_api: 特定コンテンツ定義のコンテンツ一覧（columnsで必要カラムのみ取得）
const r = await fetch('/direct/rcms_api/mng_api/?mt=topics&ct=topics_list&topics_group_id[]=1&cnt=10&columns=topics_id,subject,ymd', {credentials:'include'});
const data = await r.json();
JSON.stringify(data.topics_list?.map(t => ({id: t.topics_id, subject: t.subject, ymd: t.ymd})));

コンテンツの作成

// mng_api: コンテンツ作成（※実行前にユーザー確認必須）
const r = await fetch('/direct/rcms_api/mng_api/?mt=topics&ct=topics_edit', {
  method: 'POST',
  credentials: 'include',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    subject: 'タイトル',
    contents: '本文',
    topics_group_id: 1,
    topics_flg: 1
  })
});
const data = await r.json();
JSON.stringify({id: data.topics_id});

活用シーン

サイト構造の把握: コンテンツ定義一覧・拡張項目の確認
データの一括確認・修正: 管理画面GUIを経由せず効率的にデータ操作
スキーマ確認: MODE=schema&mt=topics&ct=topics_list でフィールド定義を取得

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

ベストプラクティス

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

kuroco-content-management