時間のかかる処理をジョブで実行する
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
時間のかかる処理は、ジョブとして受け付けます。受け付けると 202 を返し、処理はレスポンスの後で続きます。進み具合は GET /jobs/{id} で確かめます。リクエスト時間の上限があるレンタルサーバーでも、途中で切られずに動かすための仕組みです。
ジョブを始めるエンドポイント
処理 | メソッドとパス | スコープ | 権限 | 本文 |
|---|---|---|---|---|
データベースのバックアップ |
|
| バックアップの管理者(ロールでは | なし |
WordPress(WXR)形式のエクスポート |
|
| URL のブログの管理者 |
|
静的書き出し |
|
| URL のブログの管理者 | なし(管理画面のブログの設定を使う) |
エントリーの CSV インポート |
|
| URL のブログの編集者以上 |
|
キーワード検索のテキストの再構築 |
|
| URL のブログの管理者 |
|
プラグインの有効化 |
|
| URL のブログの管理者 |
|
プラグインの無効化 |
|
| URL のブログの管理者 |
|
fulltext:write は write に含まれますが、ほかは「強い権限」のスコープです。
通しの例(キーワード検索の再構築)
# 1. 実行できるかだけを確かめる(ジョブは作らない)→ 204
curl -s -i -X POST "${ACMS_API}/fulltext/rebuild/?dry_run=1" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-d '{"target":"category"}'
# HTTP/2 204
# acms-dry-run: true
# 2. 始める → 202
curl -s -i -X POST "${ACMS_API}/fulltext/rebuild/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-d '{"target":"category"}'HTTP/2 202
content-type: application/json; charset=utf-8
location: https://example.com/rest-api/acms/v1/jobs/7a9b5318-2ca5-4725-897f-9eb0a9620a56/
{"id":"7a9b5318-2ca5-4725-897f-9eb0a9620a56","type":"fulltext","status":"queued","progress":0,"result":null,"error":null,"created_datetime":"2026-11-12T13:51:40+09:00","updated_datetime":"2026-11-12T13:51:40+09:00","links":{"self":"https://example.com/rest-api/acms/v1/jobs/7a9b5318-2ca5-4725-897f-9eb0a9620a56/"}}# 3. 終わるまで状態を確かめる(Location の URL)
curl -s "${ACMS_API}/jobs/7a9b5318-2ca5-4725-897f-9eb0a9620a56/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"{
"id": "7a9b5318-2ca5-4725-897f-9eb0a9620a56",
"type": "fulltext",
"status": "succeeded",
"progress": 100,
"result": { "target": "category", "rebuilt": 18 },
"error": null,
"created_datetime": "2026-11-12T13:51:40+09:00",
"updated_datetime": "2026-11-12T13:51:40+09:00",
"links": { "self": "https://example.com/rest-api/acms/v1/jobs/7a9b5318-2ca5-4725-897f-9eb0a9620a56/" }
}終わるまで待つシェルスクリプトの例です(jq を使います)。
#!/bin/sh
# wait-job.sh <ジョブの URL>
JOB_URL="$1"
while :; do
STATUS=$(curl -s "${JOB_URL}" -H "Authorization: Bearer ${ACMS_API_TOKEN}" | jq -r '.status')
echo "status: ${STATUS}"
case "${STATUS}" in
succeeded) exit 0 ;;
failed) curl -s "${JOB_URL}" -H "Authorization: Bearer ${ACMS_API_TOKEN}" | jq '.error'; exit 1 ;;
esac
sleep 5
doneジョブの表現
キー | 説明 |
|---|---|
| ジョブの ID(UUID) |
|
|
|
|
| 進捗(0〜100 の %)。実行中は管理画面の進捗ログから読み、成功したら 100 |
| 成功したときの結果(下の表)。それ以外は |
| 失敗したときの理由。それ以外は |
| 受け付けた日時 / 状態が変わった日時 |
| このジョブの URL |
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
CSV インポートの例
# まず simulate=true で検証だけ行う
curl -s -i -X POST "${ACMS_API}/imports/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-F "file=@entries.csv;type=text/csv" \
-F "category_id=3" \
-F "simulate=true"
# 問題が無ければ本番
curl -s -i -X POST "${ACMS_API}/imports/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-F "file=@entries.csv;type=text/csv" \
-F "category_id=3"CSV の形式は、管理画面のエントリーの CSV インポートと同じです。WordPress・Movable Type・ユーザーの CSV の取り込みと、バックアップの復元は REST API では行えません。
決まりごと
ジョブの状態を読めるのは、ジョブを始めた本人のトークンで、そのジョブを始められるスコープ(
backups:writeなど)を持つときだけです。それ以外は 404 です。ジョブの記録は 30 日を過ぎると消えます。
バックアップ・エクスポート・静的書き出し・CSV インポートは、管理画面と同じロックを使います。同じ処理が実行中のときは 409
conflictです。作ったバックアップ・エクスポートのファイルのダウンロードと、バックアップの復元は、REST API では行えません。管理画面から行います。
プラグインの有効化・無効化の対象は、管理画面の一覧にあるインストール済みで更新が要らないプラグインです。すでにその状態なら 409 です。インストール・アンインストール・アップデートは管理画面から行います。
?dry_run=1は、認可・入力の検証・実行中でないことを確かめるだけで、ジョブを作らずに 204 を返します。
よくある質問・つまずき
GET /jobs/{id} が 404 になります
ジョブを始めたのと別のトークンで読んでいるか、ジョブを始められるスコープの無いトークンです。30 日を過ぎたジョブも 404 です。
202 が返ったのに処理が進みません
処理はレスポンスの後で同じプロセスが続けます。サーバーの設定(PHP の実行時間など)で止まると、status が running のまま変わらないことがあります。progress と updated_datetime の変化、監査ログ、サーバーのエラーログを確かめてください。
409 conflict になります
管理画面か別の API の呼び出しで、同じ処理が実行中です。終わってから始め直してください。