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-api-integration

• API設計・認証パターン

• /kuroco-mng-api-browser

• 管理APIによるコンテンツ操作（ブラウザ経由）

• /kuroco-smarty-plugins

• Smartyテンプレートでのコンテンツ操作（assign_topics_list 等）

• /kuroco-webhook-processing

• バッチ処理でのコンテンツ自動処理

関連ドキュメント

• docs/tutorials/adding-a-topics.md

• コンテンツ定義作成

• docs/tutorials/bulk-upload-in-csv.md

• CSVアップロード

• docs/management/content-structure-topics.md

• コンテンツ構造

• docs/reference/filter-query.md

• フィルタークエリ詳細