kuroco-server-processing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Kuroco サーバーサイド処理

Kuroco 服务端处理

KurocoのSmartyテンプレートプラグインリファレンスおよびWebhook・バッチ処理パターン。
ドキュメント参照:
/kuroco-docs
スキルを使用してKuroco公式ドキュメントを検索・参照できます。
Kuroco的Smarty模板插件参考以及Webhook、批量处理方案。
文档参考: 使用
/kuroco-docs
技能可搜索、查阅Kuroco官方文档。

目次

目录

Part 1: Smartyプラグインリファレンス

Part 1: Smarty插件参考

Part 2: Webhook・バッチ処理パターン

Part 2: Webhook・批量处理方案

Part 1: Smartyプラグインリファレンス

Part 1: Smarty插件参考

KurocoのSmartyテンプレートで使用可能な全プラグインの完全リファレンス。
Kuroco的Smarty模板可用的全插件完整参考。

よく使うプラグイン

常用插件

変数・データ操作

变量与数据操作

プラグイン説明
assign
変数代入
{assign var="name" value="値"}
append
配列追加
{append var="arr" value="値"}
json_decode
JSONパース
{$json|json_decode:true}
rcms_json_encode
JSONエンコード
{$arr|@rcms_json_encode}
插件说明示例
assign
变量赋值
{assign var="name" value="值"}
append
数组追加
{append var="arr" value="值"}
json_decode
JSON解析
{$json|json_decode:true}
rcms_json_encode
JSON编码
{$arr|@rcms_json_encode}

API・データ取得

API与数据获取

プラグイン説明
api_internal
内部API呼び出し
{api_internal endpoint='/rcms-api/1/news' var='result'}
assign_topics_list
記事一覧取得
{assign_topics_list var='list' topics_group_id=1}
assign_topics_detail
記事詳細取得
{assign_topics_detail var='detail' topics_id=$id}
assign_tag_list
タグ一覧取得
{assign_tag_list var='tags'}
→ 詳細: references/api-plugins.md
插件说明示例
api_internal
内部API调用
{api_internal endpoint='/rcms-api/1/news' var='result'}
assign_topics_list
获取文章列表
{assign_topics_list var='list' topics_group_id=1}
assign_topics_detail
获取文章详情
{assign_topics_detail var='detail' topics_id=$id}
assign_tag_list
获取标签列表
{assign_tag_list var='tags'}
→ 详情: references/api-plugins.md

文字列処理

字符串处理

プラグイン説明
escape
エスケープ
{$html|escape}
truncate
文字列切り詰め
{$text|truncate:100:"..."}
mb_truncate
マルチバイト対応
{$text|mb_truncate:50}
date_format
日付フォーマット
{$date|date_format:"%Y-%m-%d"}
translate
翻訳
{$key|translate}
nl2br
改行をBRに
{$text|nl2br}
replace
文字列置換
{$text|replace:"a":"b"}
→ 詳細: references/string-plugins.md
插件说明示例
escape
转义处理
{$html|escape}
truncate
字符串截断
{$text|truncate:100:"..."}
mb_truncate
多字节兼容截断
{$text|mb_truncate:50}
date_format
日期格式化
{$date|date_format:"%Y-%m-%d"}
translate
翻译处理
{$key|translate}
nl2br
换行转BR标签
{$text|nl2br}
replace
字符串替换
{$text|replace:"a":"b"}
→ 详情: references/string-plugins.md

フォーム・UI

表单与UI

プラグイン説明
fileupload
ファイルアップロード
{fileupload name="file" ...}
inquiry_input
フォーム入力
{inquiry_input col="name" ...}
pager
ページネーション
{pager ...}
editActionBox
編集ボタン
{editActionBox ...}
html_options
selectオプション
{html_options options=$opts}
→ 詳細: references/form-plugins.md
插件说明示例
fileupload
文件上传
{fileupload name="file" ...}
inquiry_input
表单输入
{inquiry_input col="name" ...}
pager
分页组件
{pager ...}
editActionBox
编辑按钮
{editActionBox ...}
html_options
下拉选项
{html_options options=$opts}
→ 详情: references/form-plugins.md

認証・権限

认证与权限

プラグイン説明
rcms_auth
権限制御ブロック
{rcms_auth target="read:news"}...{/rcms_auth}
login
ログイン処理
{login ...}
logout
ログアウト処理
{logout ...}
→ 詳細: references/auth-plugins.md
插件说明示例
rcms_auth
权限控制块
{rcms_auth target="read:news"}...{/rcms_auth}
login
登录处理
{login ...}
logout
登出处理
{logout ...}
→ 详情: references/auth-plugins.md

外部サービス連携

外部服务联动

プラグイン説明
sendmail
メール送信
{sendmail to=$email subject="件名" ...}
slack_post_message
Slack通知
{slack_post_message webhook_url=$url ...}
ai_completion
AI呼び出し
{ai_completion prompt=$prompt var='result'}
github_deploy
GitHubデプロイ
{github_deploy ...}
→ 詳細: references/integration-plugins.md
插件说明示例
sendmail
邮件发送
{sendmail to=$email subject="标题" ...}
slack_post_message
Slack通知
{slack_post_message webhook_url=$url ...}
ai_completion
AI调用
{ai_completion prompt=$prompt var='result'}
github_deploy
GitHub部署
{github_deploy ...}
→ 详情: references/integration-plugins.md

ファイル操作

文件操作

プラグイン説明
write_file
ファイル書き込み
{write_file var="path" value="内容"}
put_file
ストレージアップロード
{put_file path="/files/..." tmp_path=$tmp}
read_file
ファイル読み込み
{read_file path="/files/..." var='content'}
read_dir
ディレクトリ読み込み
{read_dir path="/files/..." file_var='file'}...{/read_dir}
→ 詳細: references/file-plugins.md
插件说明示例
write_file
文件写入
{write_file var="path" value="内容"}
put_file
存储上传
{put_file path="/files/..." tmp_path=$tmp}
read_file
文件读取
{read_file path="/files/..." var='content'}
read_dir
目录读取
{read_dir path="/files/..." file_var='file'}...{/read_dir}
→ 详情: references/file-plugins.md

Vue.js連携

Vue.js联动

プラグイン説明
rcms_vue_component
Vueコンポーネント
{rcms_vue_component config="rcms-mng" name="..."}
head_include
headに追加
{head_include file="..."}
bodyend
body終了前に追加
{bodyend}...{/bodyend}
→ 詳細: references/vue-plugins.md
插件说明示例
rcms_vue_component
Vue组件
{rcms_vue_component config="rcms-mng" name="..."}
head_include
头部追加
{head_include file="..."}
bodyend
页面底部追加
{bodyend}...{/bodyend}
→ 详情: references/vue-plugins.md

プラグイン種別

插件类型

関数プラグイン (Function)

函数插件 (Function)

出力を生成または処理を実行する関数。
smarty
{function_name param1="value1" param2="value2"}
生成输出或执行处理的函数。
smarty
{function_name param1="value1" param2="value2"}

修飾子プラグイン (Modifier)

修饰符插件 (Modifier)

変数の値を変換・加工する。パイプ(
|
)で連結可能。
smarty
{$variable|modifier1|modifier2:param}
转换、加工变量值,可通过竖线(
|
)链式调用。
smarty
{$variable|modifier1|modifier2:param}

ブロックプラグイン (Block)

块插件 (Block)

開始タグと終了タグで囲まれた範囲を処理。
smarty
{block_name param="value"}
  コンテンツ
{/block_name}
处理开始标签与结束标签包裹的内容范围。
smarty
{block_name param="value"}
  内容
{/block_name}

カテゴリ別リファレンス

分类参考

カテゴリファイル主なプラグイン
構文リファレンスsyntax.md基本構文、制御構造、組み込み変数、ベストプラクティス
API・データ取得api-plugins.mdapi_internal, assign_topics_list, assign_tag_list
文字列処理string-plugins.mdescape, truncate, date_format, translate
配列操作array-plugins.mdcount, in_array, implode, explode, sort系
フォーム・UIform-plugins.mdfileupload, inquiry_input, pager, html_*
認証・権限auth-plugins.mdrcms_auth, login, logout
外部連携integration-plugins.mdsendmail, slack_*, ai_completion
ファイル操作file-plugins.mdwrite_file, put_file, read_file, read_dir
Vue.js連携vue-plugins.mdrcms_vue_component, head_include
全プラグインall-plugins.md全206プラグイン一覧
分类文件主要插件
语法参考syntax.md基本语法、控制结构、内置变量、最佳实践
API与数据获取api-plugins.mdapi_internal, assign_topics_list, assign_tag_list
字符串处理string-plugins.mdescape, truncate, date_format, translate
数组操作array-plugins.mdcount, in_array, implode, explode, 排序类
表单与UIform-plugins.mdfileupload, inquiry_input, pager, html_*
认证与权限auth-plugins.mdrcms_auth, login, logout
外部联动integration-plugins.mdsendmail, slack_*, ai_completion
文件操作file-plugins.mdwrite_file, put_file, read_file, read_dir
Vue.js联动vue-plugins.mdrcms_vue_component, head_include
全插件all-plugins.md全部206个插件列表

使用例

使用示例

コンテンツ一覧をAPIで取得して表示

通过API获取内容列表并展示

smarty
{assign var="queries" value=$dataSet.emptyArray}
{append var="queries" index="cnt" value=10}
{append var="queries" index="filter" value="topics_flg = 1"}

{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  queries=$queries
  var='result'
}

{foreach from=$result.list item="news"}
  <h2>{$news.subject|escape}</h2>
  <p>{$news.contents|truncate:200}</p>
  <time>{$news.ymd|date_format:"%Y年%m月%d日"}</time>
{/foreach}

{pager data=$result.pageInfo}
smarty
{assign var="queries" value=$dataSet.emptyArray}
{append var="queries" index="cnt" value=10}
{append var="queries" index="filter" value="topics_flg = 1"}

{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  queries=$queries
  var='result'
}

{foreach from=$result.list item="news"}
  <h2>{$news.subject|escape}</h2>
  <p>{$news.contents|truncate:200}</p>
  <time>{$news.ymd|date_format:"%Y年%m月%d日"}</time>
{/foreach}

{pager data=$result.pageInfo}

フォーム送信後にSlack通知

表单提交后发送Slack通知

smarty
{sendmail
  var=mail_result
  to=$inquiry.email
  subject="お問い合わせありがとうございます"
  mail_template="inquiry_thanks"
}

{slack_post_message
  webhook_url=$smarty.const.SLACK_WEBHOOK_URL
  text="新規問い合わせ: {$inquiry.name}様 - {$inquiry.subject}"
}
smarty
{sendmail
  var=mail_result
  to=$inquiry.email
  subject="感谢您的咨询"
  mail_template="inquiry_thanks"
}

{slack_post_message
  webhook_url=$smarty.const.SLACK_WEBHOOK_URL
  text="新咨询: {$inquiry.name} 先生/女士 - {$inquiry.subject}"
}

権限に応じた表示制御

根据权限控制显示内容

smarty
{rcms_auth target="write:news"}
  <a href="/management/news/edit/">編集</a>
{/rcms_auth}

{rcms_auth target="delete:news"}
  <button class="delete-btn">削除</button>
{/rcms_auth}

smarty
{rcms_auth target="write:news"}
  <a href="/management/news/edit/">编辑</a>
{/rcms_auth}

{rcms_auth target="delete:news"}
  <button class="delete-btn">删除</button>
{/rcms_auth}

Part 2: Webhook・バッチ処理パターン

Part 2: Webhook・批量处理方案

Kuroco HeadlessCMSでのWebhook、バッチ処理、外部連携に関するベストプラクティス。
Smarty構文について: バッチ処理・トリガーはSmartyテンプレートで記述します。構文やプラグインの詳細は上記 Part 1 を参照してください。
Kuroco HeadlessCMS中Webhook、批量处理、外部联动的最佳实践。
关于Smarty语法: 批量处理、触发器使用Smarty模板编写。语法与插件详情请参考上述Part 1。

バッチ処理

批量处理

概要

概述

バッチ処理は一定時間ごとに自動実行される処理。
実行頻度の選択肢:
頻度用途
15分毎頻繁な同期が必要な場合
30分毎準リアルタイム処理
1時間毎定期的な集計・更新
毎日(指定時刻)日次レポート、バックアップ
批量处理是按固定时间间隔自动执行的任务。
执行频率选项:
频率用途
每15分钟需要频繁同步的场景
每30分钟准实时处理
每1小时定期统计与更新
每日(指定时间)日度报告、备份

ユースケース

使用场景

  • 外部システムへのCSV生成・連携
  • 外部システムからのデータ取り込み
  • ログ集計・統計データ算出
  • 定期的なメール配信
  • GitHub Actions連携(デプロイトリガー)
  • 生成CSV并同步至外部系统
  • 从外部系统导入数据
  • 日志统计与数据计算
  • 定期邮件发送
  • GitHub Actions联动(部署触发)

バッチ処理の作成

创建批量处理

管理画面: [オペレーション] → [バッチ処理] → [追加]
項目説明
タイトルバッチの名前CSV出力バッチ
識別子ユニークな識別子(英数字)csv_export
実行頻度実行間隔毎日 03:00
実行内容Smarty構文で記述下記参照
管理后台: [操作] → [批量处理] → [添加]
项目说明示例
标题批量任务名称CSV导出任务
标识符唯一标识符(英数字)csv_export
执行频率执行间隔每日 03:00
执行内容使用Smarty语法编写详见下文

内部API呼び出し

内部API调用

基本構文

基本语法

smarty
{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  queries=$queries
  var='response'
}
smarty
{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  queries=$queries
  var='response'
}

コンテンツ一覧取得

获取内容列表

smarty
{assign var="queries" value=$dataSet.emptyArray}
{append var="queries" index="cnt" value=0}
{append var="queries" index="filter" value="topics_flg = 1"}

{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  queries=$queries
  var='news_list'
}

{foreach from=$news_list.list item="news"}
  ID: {$news.topics_id}, タイトル: {$news.subject}
{/foreach}
smarty
{assign var="queries" value=$dataSet.emptyArray}
{append var="queries" index="cnt" value=0}
{append var="queries" index="filter" value="topics_flg = 1"}

{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  queries=$queries
  var='news_list'
}

{foreach from=$news_list.list item="news"}
  ID: {$news.topics_id}, 标题: {$news.subject}
{/foreach}

コンテンツ作成

创建内容

smarty
{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="subject" value="タイトル"}
{append var="body" index="contents" value="本文"}
{append var="body" index="topics_flg" value=1}

{api_internal
  endpoint='/rcms-api/1/news/insert'
  method='POST'
  member_id=1
  body=$body
  var='result'
}
smarty
{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="subject" value="标题"}
{append var="body" index="contents" value="正文"}
{append var="body" index="topics_flg" value=1}

{api_internal
  endpoint='/rcms-api/1/news/insert'
  method='POST'
  member_id=1
  body=$body
  var='result'
}

外部API呼び出し

外部API调用

基本構文

基本语法

smarty
{api_request
  url='https://api.example.com/endpoint'
  method='GET'
  headers=$headers
  body=$body
  var='response'
}
smarty
{api_request
  url='https://api.example.com/endpoint'
  method='GET'
  headers=$headers
  body=$body
  var='response'
}

POSTリクエスト例

POST请求示例

smarty
{assign var="headers" value=$dataSet.emptyArray}
{append var="headers" index="Content-Type" value="application/json"}
{append var="headers" index="Authorization" value="Bearer YOUR_API_KEY"}

{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="message" value="Hello"}

{api_request
  url='https://api.example.com/post'
  method='POST'
  headers=$headers
  body=$body|@json_encode
  var='response'
}
smarty
{assign var="headers" value=$dataSet.emptyArray}
{append var="headers" index="Content-Type" value="application/json"}
{append var="headers" index="Authorization" value="Bearer YOUR_API_KEY"}

{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="message" value="Hello"}

{api_request
  url='https://api.example.com/post'
  method='POST'
  headers=$headers
  body=$body|@json_encode
  var='response'
}

トリガー処理

触发器处理

コンテンツ更新時のトリガー

内容更新时的触发器

管理画面: [コンテンツ定義] → [トリガー設定]
利用可能なイベント:
イベントタイミング
作成時コンテンツ新規作成後
更新時コンテンツ更新後
削除時コンテンツ削除後
公開時公開ステータス変更時
利用可能な変数:
smarty
{$topics.topics_id}      {* コンテンツID *}
{$topics.subject}        {* タイトル *}
{$topics.contents}       {* 本文 *}
{$topics.ymd}            {* 公開日 *}
{$topics.ext_col_01}     {* 拡張項目 *}
管理后台: [内容定义] → [触发器设置]
可用事件:
事件触发时机
创建时内容新建完成后
更新时内容更新完成后
删除时内容删除完成后
发布时发布状态变更时
可用变量:
smarty
{$topics.topics_id}      {* 内容ID *}
{$topics.subject}        {* 标题 *}
{$topics.contents}       {* 正文 *}
{$topics.ymd}            {* 发布日期 *}
{$topics.ext_col_01}     {* 扩展字段 *}

フォーム送信時のトリガー

表单提交时的触发器

管理画面: [フォーム] → [トリガー設定]
smarty
{$inquiry.inquiry_id}    {* 回答ID *}
{$inquiry.name}          {* 名前 *}
{$inquiry.email}         {* メールアドレス *}
{$inquiry.message}       {* メッセージ *}
管理后台: [表单] → [触发器设置]
smarty
{$inquiry.inquiry_id}    {* 回复ID *}
{$inquiry.name}          {* 姓名 *}
{$inquiry.email}         {* 邮箱地址 *}
{$inquiry.message}       {* 留言内容 *}

外部サービス連携

外部服务联动

詳細な連携パターン: references/integrations.md を参照
详细联动方案: 请参考 references/integrations.md

Slack通知

Slack通知

smarty
{assign var="message" value=$dataSet.emptyArray}
{append var="message" index="text" value="通知メッセージ"}

{slack_send
  webhook_url="https://hooks.slack.com/services/xxx/yyy/zzz"
  body=$message|@json_encode
}
smarty
{assign var="message" value=$dataSet.emptyArray}
{append var="message" index="text" value="通知消息"}

{slack_send
  webhook_url="https://hooks.slack.com/services/xxx/yyy/zzz"
  body=$message|@json_encode
}

メール通知

邮件通知

smarty
{send_mail
  to="recipient@example.com"
  subject="件名"
  body="本文"
}
smarty
{send_mail
  to="recipient@example.com"
  subject="标题"
  body="正文"
}

GitHub Actions連携

GitHub Actions联动

smarty
{assign var="headers" value=$dataSet.emptyArray}
{append var="headers" index="Authorization" value="token YOUR_GITHUB_TOKEN"}
{append var="headers" index="Accept" value="application/vnd.github.v3+json"}

{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="event_type" value="kuroco-update"}

{api_request
  url='https://api.github.com/repos/owner/repo/dispatches'
  method='POST'
  headers=$headers
  body=$body|@json_encode
  var='response'
}
smarty
{assign var="headers" value=$dataSet.emptyArray}
{append var="headers" index="Authorization" value="token YOUR_GITHUB_TOKEN"}
{append var="headers" index="Accept" value="application/vnd.github.v3+json"}

{assign var="body" value=$dataSet.emptyArray}
{append var="body" index="event_type" value="kuroco-update"}

{api_request
  url='https://api.github.com/repos/owner/repo/dispatches'
  method='POST'
  headers=$headers
  body=$body|@json_encode
  var='response'
}

ベストプラクティス

最佳实践

負荷を考慮した実行時間

考虑负载的执行时间

  • システム負荷の低い時間帯(深夜・早朝)に設定
  • 大量データ処理は1日1回に制限
  • ページネーションを使用して分割処理
  • 选择系统负载低的时段(深夜、凌晨)执行
  • 大量数据处理限制为每日1次
  • 使用分页进行分段处理

エラーハンドリング

错误处理

smarty
{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  var='response'
}

{if $response.errors}
  {slack_send webhook_url="..." text="エラー: {$response.errors|@json_encode}"}
  {log message="エラー: {$response.errors|@json_encode}"}
{else}
  {log message="処理完了: {$response.pageInfo.totalCnt}件"}
{/if}
smarty
{api_internal
  endpoint='/rcms-api/1/news'
  method='GET'
  member_id=1
  var='response'
}

{if $response.errors}
  {slack_send webhook_url="..." text="错误: {$response.errors|@json_encode}"}
  {log message="错误: {$response.errors|@json_encode}"}
{else}
  {log message="处理完成: {$response.pageInfo.totalCnt}条"}
{/if}

タイムアウト対策

超时应对

大量データは分割処理:
smarty
{assign var="page" value=1}
{while true}
  {assign var="queries" value=$dataSet.emptyArray}
  {append var="queries" index="pageID" value=$page}
  {append var="queries" index="cnt" value=100}

  {api_internal endpoint='/rcms-api/1/news' method='GET' member_id=1 queries=$queries var='response'}

  {foreach from=$response.list item="item"}
    {* 処理 *}
  {/foreach}

  {if $page >= $response.pageInfo.totalPageCnt}{break}{/if}
  {assign var="page" value=$page+1}
{/while}

大量数据采用分段处理:
smarty
{assign var="page" value=1}
{while true}
  {assign var="queries" value=$dataSet.emptyArray}
  {append var="queries" index="pageID" value=$page}
  {append var="queries" index="cnt" value=100}

  {api_internal endpoint='/rcms-api/1/news' method='GET' member_id=1 queries=$queries var='response'}

  {foreach from=$response.list item="item"}
    {* 处理逻辑 *}
  {/foreach}

  {if $page >= $response.pageInfo.totalPageCnt}{break}{/if}
  {assign var="page" value=$page+1}
{/while}

関連スキル

相关技能

  • /kuroco-api-content
    - API設計・認証パターン、コンテンツCRUD操作
  • /kuroco-mng-api-browser
    - 管理API(mng_api)の操作
  • /kuroco-api-content
    - API设计与认证方案、内容CRUD操作
  • /kuroco-mng-api-browser
    - 管理API(mng_api)操作

関連ドキュメント

相关文档

  • ../kuroco-docs/docs/tutorials/how-to-use-batch.md
    - バッチ処理の使い方
  • ../kuroco-docs/docs/tutorials/auto-run-github-with-contents-update.md
    - GitHub Actions連携
  • ../kuroco-docs/docs/tutorials/send-slack-notification-after-a-form-has-been-submitted.md
    - Slack通知
  • ../kuroco-docs/docs/reference/trigger-variables.md
    - トリガー変数
  • ../kuroco-docs/docs/tutorials/how-to-use-batch.md
    - 批量处理使用方法
  • ../kuroco-docs/docs/tutorials/auto-run-github-with-contents-update.md
    - GitHub Actions联动
  • ../kuroco-docs/docs/tutorials/send-slack-notification-after-a-form-has-been-submitted.md
    - Slack通知设置
  • ../kuroco-docs/docs/reference/trigger-variables.md
    - 触发器变量