关于 kuroco-api-content
此技能提供 Kuroco HeadlessCMS API 集成与内容管理的实现指南,面向开发 Kuroco 集成的人员。内容涵盖端点操作、身份验证、安全设置、缓存、请求限制和内容工作流。
主要功能
- 01设计 API 端点与操作
- 02配置身份验证和访问控制
- 03规划缓存与请求限制处理
- 04查询和管理 Topics 内容
- 05管理成员、表单及相关数据
- 06通过 Admin MCP 执行管理任务
适用场景
- 01构建基于 Kuroco 的 Web 或移动应用
- 02配置安全 API 访问与缓存
- 03实现内容列表、筛选和更新
- 04通过 Admin MCP 管理 Kuroco 设置
MCP 相关
该技能介绍通过 Admin MCP 修改 API 安全设置并执行内容管理操作。连接和身份验证细节请参阅 `/kuroco-admin-mcp`。
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ diverta/ kuroco-skills --skill kuroco-api-content安装后在 Claude Code 中输入/kuroco-api-content确认已加载。
包含的文件
除 SKILL.md 外,安装时一起下载的参考资料和脚本。
agents/openai.yamlreferences/file-operations.mdfilter-query.mdsecurity-settings.md详细介绍
Kuroco API 集成与内容管理
关于 Kuroco HeadlessCMS API 设计、实现和内容管理的最佳实践。
文档参考:使用 /kuroco-docs 技能搜索和参考 Kuroco 官方文档。
目录
Part 1:API 集成模式
Part 2:内容管理模式
- 内容结构
- 扩展字段(自定义字段)
- Topics API 操作
- 内容 CRUD 操作
- 筛选查询 → 详情请参阅 references/filter-query.md
- 文件与 CSV 操作 → 详情请参阅 references/file-operations.md
- 通过 Admin MCP 执行管理操作(内容)
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
端点设置的主要项目
| 项目 | 说明 | 示例 |
|---|---|---|
| 路径 | 端点 URL | news, member/list |
| 模型 | 操作对象 | Topics, Member, InquiryForm |
| 操作 | 操作类型 | list, details, insert, update, delete |
| 缓存 | 响应缓存时长 | 86400(1 天) |
| 流量限制 | 请求次数限制 | 100 次/分钟 |
| 需要认证 | 是否需要登录 | true/false |
主要类别与模型
认证(Authentication)
| 操作 | 说明 | 方法 |
|---|---|---|
login_challenge | 登录 | POST |
token | 获取访问令牌 | POST |
logout | 登出 | POST |
profile | 获取登录用户信息 | GET |
reminder | 密码提醒 | POST |
内容(Topics)
| 操作 | 说明 | 方法 |
|---|---|---|
list | 获取列表 | GET |
details | 获取详情 | GET |
insert | 新增 | POST |
update | 更新 | POST |
delete | 删除 | POST |
bulk_upsert | 批量更新 | POST |
成员(Member)
| 操作 | 说明 | 方法 |
|---|---|---|
list | 成员列表 | GET |
details | 成员详情 | GET |
insert | 注册成员 | POST |
update | 更新成员 | POST |
表单(InquiryMessage/InquiryForm)
| 操作 | 说明 | 方法 |
|---|---|---|
send | 提交表单 | POST |
list | 答复列表 | GET |
details | 答复详情 | GET |
EC 积分(ECPoint)
| 操作 | 说明 | 方法 |
|---|---|---|
update | 发放或消费积分 | POST |
history | 获取积分历史记录和当前余额 | GET |
安全设置
详细参考:安全设置的详情请参阅 references/security-settings.md。
官方文档:详细的官方信息请参阅
../kuroco-docs/docs/management-api.md(api-security)等。
认证方式
管理界面:在 [API] → [セキュリティ] 中从 4 种方式中选择。
| 认证方式 | 用途 | 请求头 |
|---|---|---|
| 无 | 仅用于公开数据的 API(与缓存配合使用)。不要用于非公开数据或写入操作 | 不需要 |
| 静态访问令牌 | 服务器间通信、公开 API | X-RCMS-API-ACCESS-TOKEN: {固定令牌} |
| 动态访问令牌 | 需要登录的网站(JWT) | X-RCMS-API-ACCESS-TOKEN: {动态令牌} |
| Cookie | 需要登录的网站 | credentials: 'include'(前端) |
令牌有效期预先通知:静态访问令牌、带特权的静态令牌以及 KurocoFront 令牌将在到期前 30 天、7 天和 1 天,向账户设置中的邮箱发送通知邮件。
注意:更改 API 安全设置会使已签发的令牌失效(更改时会显示确认警告)。如果有正在运行的客户端,请提前规划令牌的重新签发和替换。
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: '[email protected]',
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 的认证。在请求头中附加令牌。
获取流程分为两步:首先向 login(Login::login_challenge)POST email/password,获取 grant_token;然后将 grant_token POST 到 token(Login::token)端点,换取 access_token / refresh_token。不能直接向 token 端点发送 email/password(它只接受以下请求体:首次签发时为 { "grant_token": "..." },重新签发时为 { "refresh_token": "..." })。
// 1. ログインして grant_token を取得
const loginResponse = await fetch('https://example.g.kuroco.app/rcms-api/1/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: '[email protected]',
password: 'password123'
})
})
const { grant_token } = await loginResponse.json()
// 2. grant_token をアクセストークンに交換
const tokenResponse = await fetch('https://example.g.kuroco.app/rcms-api/1/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ grant_token })
})
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 | 192.0.2.1 | 単一IPアドレス |
| CIDR | 192.0.2.0/24 | サブネット単位 |
| 範囲指定 | 192.0.2.1-192.0.2.2 | ハイフンによるIP範囲 |
IPアドレスグループ: 定数機能で IPSETS_* を定義し、[[IPSETS_*]] で参照可能(../kuroco-docs/docs/faq-domain.md(is-it-possible-to-set-multiple-ip-addresses-at-once) 参照)。
CORS設定
管理画面: [API] → [セキュリティ] → [CORS]
| 項目 | 対応ヘッダー | 説明 |
|---|---|---|
| CORS_ALLOW_ORIGINS | Access-Control-Allow-Origin | 許可オリジン(ワイルドカード*は非推奨) |
| CORS_ALLOW_METHODS | Access-Control-Allow-Methods | 許可HTTPメソッド |
| CORS_ALLOW_HEADERS | Access-Control-Allow-Headers | 許可リクエストヘッダー |
| CORS_MAX_AGE | Access-Control-Max-Age | プリフライトキャッシュ秒数 |
| CORS_ALLOW_CREDENTIALS | Access-Control-Allow-Credentials | Cookie送信の許可 |
CSRF対策: CORS + Content-Type: application/json でモダンブラウザでのCSRF攻撃を防御。ワイルドカードを使うと防御効果がなくなるため、必ず特定ドメインを指定すること。
変更反映の遅延: CORS設定変更後は CORS_MAX_AGE 分だけブラウザにキャッシュされる。即時反映にはブラウザキャッシュクリアまたは CORS_MAX_AGE を 0 に設定。
APIリクエスト制限
| 制限タイプ | 説明 |
|---|---|
| None | 制限なし |
| GroupAuth | ログインユーザーのグループ権限をチェックし、合致した場合のみ許可 |
| MemberCustomSearchAuth | ログインユーザーがカスタムメンバーフィルターの条件に合致する場合のみ許可 |
閲覧制限の優先順序
コンテンツ返却時の制限は以下の順序で評価されます(上位優先):
- API → IPアドレス制限(API全体)
- エンドポイント → APIリクエスト制限(エンドポイント単位)
- コンテンツ定義 → APIリクエスト制限
- コンテンツカテゴリ → APIリクエスト制限
- 個別コンテンツ → APIリクエスト制限
後処理によるレスポンス制限
管理画面: [API] → エンドポイント → [後処理]
APIレスポンスから不要なフィールドを除外し、公開情報を制御:
| 処理タイプ | 説明 |
|---|---|
| 出力許可リスト | 指定フィールドのみ返す(ホワイトリスト)。例: list.subject, pageInfo |
| 出力変換リスト | フィールドの削除・名称変更・変換関数の適用 |
| カスタム処理 | Smartyテンプレートでの独自ロジック |
パフォーマンスTip: 出力許可リストは他の処理の前に配置するとSQLレベルで効果あり。
プラットフォームセキュリティ
Kurocoプラットフォームが提供するインフラレベルのセキュリティ:
- 通信: HTTPS完全暗号化、TLS証明書自動管理
- 防御: WAF、CDN、DDoS対策(オプションでFastly DDoS Protection)
- 認証連携: SAML/OAuth外部ログイン、クライアント証明書(オプション)
- 監査: アクセスログ、アプリケーションログ
- 認定: ISMS (ISO 27001)、ISMSクラウド (ISO 27017)、プライバシーマーク
- 診断: 毎日のコンテナ脆弱性スキャン、VADDY連携自動診断
Admin MCPによる設定変更
APIのセキュリティ設定は管理画面だけでなく、Admin MCP経由でも操作可能です。接続・認証は /kuroco-admin-mcp スキルを参照してください。
キャッシュ戦略
推奨設定
| ユースケース | キャッシュ期間 | 設定値 |
|---|---|---|
| 静的コンテンツ(ニュース等) | 1日 | 86400 |
| 更新頻度低いコンテンツ | 1週間 | 604800 |
| リアルタイム性が必要 | キャッシュなし | 0 |
| 認証が必要なAPI | キャッシュなし | 0 |
重要: コンテンツ・メンバー等のデータ更新時、キャッシュは自動クリアされます。クリアされる範囲はデータの種類ごとに決まっているため、下記を把握しておくとキャッシュ期間を長めに設定しても安全かどうかを判断しやすい。
Topicsのキャッシュクリア範囲
| 操作 | クリアされる範囲 |
|---|---|
Topics(insert / update / delete / accept / bulk_upsert / increment) | 同じコンテンツ定義グループ(TopicsGroup)に紐づく全エンドポイント。Topics::detailsのみ、更新されたコンテンツIDのキャッシュだけがクリアされる |
| コンテンツカテゴリ(新規作成・更新・削除) | 同じコンテンツ定義グループに紐づく全エンドポイント。Topics::detailsは対象外(カテゴリの変更ではdetails側はクリアされない) |
フォーム(InquiryForm の insert/update/delete、回答CSVアップロード) | 同じフォームIDに紐づく全エンドポイント |
コメント(Comment の insert/update/delete) | モデルカテゴリ「アクティビティ」に紐づく全エンドポイント+紐づけ先のコンテンツ定義グループに紐づくエンドポイント |
お気に入り(Favorite の insert/delete) | 対象モデルカテゴリの全エンドポイント+対象コンテンツのコンテンツ定義に紐づくTopics::listエンドポイント |
メンバー(Member の insert/update) | モデルカテゴリ「メンバー」「認証」に紐づく全エンドポイント |
| マスタ(update/delete) | 同じマスタIDに紐づく全エンドポイント |
上記以外の操作では自動クリアされない。 プロキシ経由・取り込み用のカスタムSmarty処理など、標準のTopics API以外の経路でデータを更新する場合は自動クリアの対象外なので、Smartyプラグイン purge_cdn_cache でクリア範囲・タイミングを明示的に指定する(例: Favorite::insertの後処理でTopics::detailsのキャッシュを削除)。急ぎクリアしたい場合はエンドポイント一覧の「キャッシュクリアする」ボタンで手動クリアもできる。
出典: ../kuroco-docs/docs/reference-api-1.md(cache-clear-operation)
キャッシュヘッダー
レスポンスヘッダーで確認可能:
Cache-Control: max-age=86400
流量制限
無料利用ユーザーの制限
決済情報未登録のユーザーには以下の制限があります。クレジットカード登録済み、または請求書払いのユーザーは対象外です。
| 対象 | 制限 |
|---|---|
| API送信 | 1時間あたり約1,000件 |
| バッチ処理 | 1時間あたり約100件 |
レスポンスヘッダー
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_query: 'ymd=DESC'
})
// カテゴリでの絞り込みは contents_type を使う(category_id というフィールドは無い)
// 例: filter: 'contents_type = 1'
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
}
多言語サイトでの公開状態の一括取得
Topics::list / Topics::details のエンドポイントで langs_open_flg パラメータを有効にすると、各コンテンツに全設定言語の公開状態を示す langs_open_flg オブジェクトが含まれます。言語ごとに個別のAPIリクエストを行わずに言語切替UIの表示制御が可能です。
// レスポンス例
// {
// "details": {
// "topics_id": 1,
// "langs_open_flg": { "en": 1, "ja": 0 },
// ...
// }
// }
お気に入り日時の取得・並べ替え
Topics::list のエンドポイントで get_last_favorite_ymdhi パラメータを有効にすると、各コンテンツが最後にお気に入りされた日時(last_favorite_ymdhi)を取得できます。last_favorite_ymdhi での並べ替えにも対応しており、「人気順(最近お気に入りされた順)」の一覧表示が可能です。
コンテンツ作成
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,
open_flg: 1 // 1: 公開, 0: 非公開(topics_flg は「一覧に載せる/載せない」の別フラグ)
})
}
)
return response.json()
}
エラーハンドリング
主要エラーコード
| コード | 説明 | 対応 |
|---|---|---|
| 400 | リクエストエラー | リクエストパラメータを確認 |
| 401 | 認証エラー | ログイン状態・トークンを確認 |
| 403 | 権限エラー | APIの権限設定を確認 |
| 404 | リソース未存在 | パス・IDを確認 |
| 429 | 流量制限超過 | リトライまで待機 |
| 500 | サーバーエラー | Kurocoサポートに連絡 |
エラーレスポンス例
{
"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)
コンテンツ定義の設定
管理画面: [コンテンツ定義] → [新規作成]
| 項目 | 説明 |
|---|---|
| グループ名 | コンテンツ定義の名前 |
| 識別子 | ユニークなID(英数字) |
| 本文の入力方法 | WYSIWYG、マークダウン、HTML |
| 閲覧制限 | 全員/グループ制限/カスタム検索 |
| 編集制限 | 全員/グループ制限/カスタム検索 |
| 拡張項目 | カスタムフィールド。上限はwhoamiのsite.limits.topics_max_extension({current, max})で確認する。maxはJSONB形式サイトで999、レガシー形式サイトで99。currentがmax未満ならadmin_setting-updateで引き上げ可能(詳細: /kuroco-admin-mcp) |
拡張項目(カスタムフィールド)
キー名を推測しない。 拡張項目のキー名はサイト単位で
ext_1形式とext_col_01形式に分かれます。 Admin MCP に接続できる場合はwhoamiのsite.topics_ext_key_formatでそのサイトの命名を確認し、 どの番号がどの項目かはtopics-describe(グループ単位の正)で確定させてください(→/kuroco-admin-mcp)。ext_slugを設定した項目はスラッグがキーになるため、この分岐の影響を受けません。設定を推奨します。 以下の表はext_col_01形式のサイトでの例です。
| タイプ | 説明 | 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",
"open_flg": 1,
"contents_type": 1,
"contents_type_nm": "カテゴリ名",
"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',
open_flg: 1, // 1: 公開, 0: 非公開
contents_type: 1, // カテゴリID(category_idというフィールドは無い)
open_type: 'sitei', // 予約公開を使う場合は 'sitei' を明示(既定 'open' のままだと日時が保存されない)
open_sta_date: '2024-12-01 00:00:00', // 公開開始日時
open_end_date: '2024-12-31 23:59:59', // 公開終了日時
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=contents_type = 1 |
>, >=, <, <= | filter=ymd >= "2024-01-01" |
contains, ncontains | filter=subject contains "キーワード" |
in, nin | filter=contents_type in [1, 2, 3] |
文字列の値は二重引用符で囲む。 シングルクォートは引用符ごと値の一部として扱われ、 エラーにならず0件になる(値に空白を含む場合は構文エラー)。
カテゴリのフィールド名は contents_type(category_id というフィールドは存在しない)。
複合条件: filter=(contents_type = 1 or contents_type = 2) and topics_flg = 1
ソート: order_query=ymd=DESC({フィールド}={ASC|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 を参照
Admin MCPによる管理操作(コンテンツ)
AIエージェント(Claude Desktop / claude.ai / Claude Code 等のMCPクライアント)から管理画面と同等のコンテンツ操作を行うには Admin MCP(/kuroco-admin-mcp スキル) を使用します。フロントエンドAPI(rcms-api)との違いに注意してください。
フロントエンドAPI vs 管理操作(Admin MCP)
| 項目 | フロントエンドAPI(rcms-api) | 管理操作(Admin MCP) |
|---|---|---|
| 対象 | エンドユーザー | 管理者・運用者 |
| 認証 | StaticToken / DynamicToken / Cookie | OAuth(Admin MCP) |
| エンドポイント | /rcms-api/{api_id}/{path} | Admin MCP ツール経由 |
| 利用場面 | フロントエンド実装 | データ一括操作、構造確認、設定変更 |
活用シーン
- サイト構造の把握: コンテンツ定義一覧・拡張項目の確認
- データの一括確認・修正: 管理画面GUIを経由せず効率的にデータ操作
- スキーマ確認: Admin MCP のスキーマ取得ツールでフィールド定義を取得
注意: insert/update/deleteは必ずユーザーに確認してから実行すること。接続設定・ツールの詳細は
/kuroco-admin-mcpスキル参照。
ベストプラクティス
- キャッシュ活用: エンドポイント設定で
キャッシュ: 86400(1日)を設定。更新時は自動クリア - ページネーション:
pageIDとcntパラメータで分割取得
関連スキル
/kuroco-frontend-integration- Vite/Nuxt.js/Next.jsでのAPI呼び出しパターン、KurocoFrontデプロイ/kuroco-server-processing- Smartyプラグイン・構文リファレンス、Webhook・バッチ処理/kuroco-admin-mcp- Admin MCP経由の管理操作
関連ドキュメント
スキル内リファレンス
- references/security-settings.md - セキュリティ設定の詳細リファレンス
- references/filter-query.md - フィルタークエリ詳細
- references/file-operations.md - ファイル・CSV操作詳細
Kuroco公式ドキュメント
../kuroco-docs/docs/management-api.md(api-security) - APIセキュリティ設定(認証方式、IP制限)../kuroco-docs/docs/management-api.md(api-list) - API一覧・CORS設定../kuroco-docs/docs/management-api.md(api-postprocessing) - API後処理の設定../kuroco-docs/docs/reference-api-2.md(endpoint-settings) - エンドポイント設定項目一覧../kuroco-docs/docs/reference-smarty-trigger-1.md(post-processing) - 後処理の詳細リファレンス../kuroco-docs/docs/tutorials-api-custom-1.md(configure-endpoint) - エンドポイント設定方法../kuroco-docs/docs/tutorials-auth-member-3.md(login) - ログイン実装../kuroco-docs/docs/tutorials-api-custom-1.md(restricting-api-access-with-statictoken) - StaticToken認証../kuroco-docs/docs/reference-api-1.md(api-cache) - APIキャッシュ../kuroco-docs/docs/reference-api-1.md(cache-clear-operation) - APIキャッシュクリアのタイミングと範囲../kuroco-docs/docs/reference-api-3.md(filter-query) - フィルタークエリ../kuroco-docs/docs/about.md(security) - プラットフォームセキュリティ概要../kuroco-docs/docs/faq-member.md(in-what-order-are-viewing-restrictions-applied) - 閲覧制限の優先順序- https://kuroco.app/ja/docs/faq/cors-and-content-type-prevent-csrf-attacks/ - CSRF対策
../kuroco-docs/docs/faq-api-error.md(the-api-returns-403-forbidden-even-though-no-restrictions-are-applied) - 403エラーの解決../kuroco-docs/docs/tutorials-content-1.md(adding-a-topics) - コンテンツ定義作成../kuroco-docs/docs/tutorials-content-1.md(bulk-upload-in-csv) - CSVアップロード../kuroco-docs/docs/management-content.md(content-structure-topics) - コンテンツ構造