時間のかかる処理をジョブで実行する


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

時間のかかる処理は、ジョブとして受け付けます。受け付けると 202 を返し、処理はレスポンスの後で続きます。進み具合は GET /jobs/{id} で確かめます。リクエスト時間の上限があるレンタルサーバーでも、途中で切られずに動かすための仕組みです。

ジョブを始めるエンドポイント

処理

メソッドとパス

スコープ

権限

本文

データベースのバックアップ

POST /backups

backups:write

バックアップの管理者(ロールでは backup_export)

なし

WordPress(WXR)形式のエクスポート

POST /exports

exports:write

URL のブログの管理者

include_child_blogs(真偽値。子ブログを含めるか。既定 false)

静的書き出し

POST /static-exports

static-exports:write

URL のブログの管理者

なし(管理画面のブログの設定を使う)

エントリーの CSV インポート

POST /imports(multipart/form-data)

imports:write

URL のブログの編集者以上

file(必須。UTF-8 か Shift_JIS の CSV)・category_id(取り込み先のカテゴリー。省略時は CSV の指定)・simulate(true で保存せずに検証だけ。既定 false)

キーワード検索のテキストの再構築

POST /fulltext/rebuild

fulltext:write

URL のブログの管理者

target(必須。blog・category・user・entry)

プラグインの有効化

POST /plugins/activate

plugins:write

URL のブログの管理者

class_name(必須。管理画面の一覧に出るプラグインのクラス名)

プラグインの無効化

POST /plugins/deactivate

plugins:write

URL のブログの管理者

class_name(必須)

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

ジョブの ID(UUID)

type

backup・export・static-export・import・fulltext・plugin

status

queued(受け付けた)・running(実行中)・succeeded(成功)・failed(失敗)

progress

進捗(0〜100 の %)。実行中は管理画面の進捗ログから読み、成功したら 100

result

成功したときの結果(下の表)。それ以外は null

error

失敗したときの理由。それ以外は null

created_datetime / updated_datetime

受け付けた日時 / 状態が変わった日時

links.self

このジョブの URL

type

result の項目

backup

file(作ったバックアップのファイル名)

export

file(作ったエクスポートのファイル名)

static-export

error_count(書き出しの失敗の数)・errors(path・code の配列)

import

inserted(作成)・updated(更新)・failed(失敗)の件数・warnings(media・embed・other ごとの警告の数)・simulate

fulltext

target・rebuilt(作り直した件数)

plugin

class_name・status(有効・無効の状態)

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 の呼び出しで、同じ処理が実行中です。終わってから始め直してください。