REST API と Hook でリダイレクトを扱う
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
リダイレクトのルールは、REST API でも作成・取得・更新・削除・並べ替えができます。数百件の移行表を登録するときや、ほかのシステムから登録するときに使います。また、プラグインや extension/acms の Hook で、照合の結果を差し替えられます。REST API そのものの使い方は REST API の概要 を参照してください。
使う前の準備
REST API を有効にします(REST API の概要)。
API トークンを発行します(REST API の認証と API トークン)。スコープは
redirects:read(読み取り)とredirects:write(書き込み)を付けます。トークンを発行するユーザーは、ルールを登録するブログの管理者権限を持っている必要があります。
端末で、ベース URL とトークンを環境変数に入れておきます。
export ACMS_API_TOKEN='acms_...' # 発行したトークン
export ACMS_API='https://example.com/rest-api/acms/v1'redirects:read/redirects:writeは専用のスコープで、汎用のread/writeには含まれません。操作するブログは URL で決まります。子ブログのルールは、子ブログの URL(
https://example.com/news/rest-api/acms/v1など)で操作します。
エンドポイントと本文のキー
メソッドとパス | 内容 | スコープ |
|---|---|---|
| 一覧。管理画面の一覧と同じ範囲(URL のブログのルールと、上の階層のブログのグローバルのルール。無効なものを含む)を、照合する順に返します。 |
|
| 1 件の取得。一覧の範囲外のルールは 404 |
|
| 作成。URL のブログのルールの末尾に追加します |
|
| 一部の更新。URL のブログのルールだけが対象です |
|
| 全体の置き換え |
|
| 削除。同じブログのルールの並び順を 1 から振り直します |
|
| 並べ替え |
|
本文(JSON)のキーは次のとおりです。作成で省いたキーは「既定値」、更新で省いたキーは今の値のままです。
キー | 型 | 既定値(作成) | 説明 |
|---|---|---|---|
| 文字列 | (必須) | 転送元。完全一致・前方一致は |
| 文字列 |
|
|
| 文字列 | (301〜308 では必須) | 転送先。1024 文字まで。410 / 451 では保存せず、応答では |
| 整数 |
|
|
| 文字列 |
|
|
| 文字列 |
|
|
| 文字列 |
|
|
| 文字列 |
|
|
| 文字列 | 空 | メモ。255 文字まで |
応答には、さらに id・sort(ブログごとの並び順。1 から)・created_datetime・updated_datetime・blog_id・links が入ります。
作成する
curl -X POST "${ACMS_API}/redirects/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"source": "/old/page/", "destination": "/new/page/", "status_code": 301, "name": "2026年リニューアル"}'成功すると 201 と、作成したルールを返します(値は例です)。
{
"id": 7,
"name": "2026年リニューアル",
"status": "open",
"source": "/old/page/",
"match_type": "exact",
"destination": "/new/page/",
"status_code": 301,
"trigger": "not_found_only",
"query": "pass",
"scope": "local",
"sort": 3,
"created_datetime": "2026-11-12T13:40:18+09:00",
"updated_datetime": "2026-11-12T13:40:18+09:00",
"blog_id": 1,
"links": {
"self": "https://example.com/rest-api/acms/v1/redirects/7/",
"blog": "https://example.com/rest-api/acms/v1/blogs/1/"
}
}保存せずに検査だけする(dry_run)
?dry_run=1 を付けると、保存せずに、管理画面と同じ検査(重複・ループ・書き方)だけを行います。検査に通ると 200、通らないと 422 を返します。
curl -X POST "${ACMS_API}/redirects/?dry_run=1" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"source": "/loop/", "destination": "/loop/", "status_code": 301}'{
"type": "https://developer.a-blogcms.jp/rest-api/problems/validation-failed",
"title": "入力内容にエラーがあります。",
"status": 422,
"detail": "1 件の項目を修正してください。",
"instance": "/rest-api/acms/v1/redirects",
"code": "validation_failed",
"errors": [
{ "pointer": "#/destination", "code": "loop", "detail": "転送先が転送元に戻るため、転送が繰り返されます。" }
]
}errors の code は、管理画面の検査と同じものです。
pointer | code | 意味 |
|---|---|---|
|
| 転送元が空 |
|
|
|
|
| 正規表現の書き方の誤り |
|
| 完全一致・ |
|
| 同じ転送元・同じ発火タイミングの有効なルールがある |
|
| エンコードした後の転送元が 512 文字を超える |
|
| 転送先が空 |
|
| 転送先の書き方の誤り |
|
| ドメインの部分に |
|
| 転送が繰り返される |
|
| このブログでは |
各キー |
| 選べない値。型の誤り(文字列のところに数値など)も |
一覧・更新・削除・並べ替え
一覧
curl -H "Authorization: Bearer ${ACMS_API_TOKEN}" "${ACMS_API}/redirects/?limit=100&page=1"応答は items・meta(total など)・links の形です(REST API の概要)。並びは照合する順で、?order や絞り込みは使えません。
更新
curl -X PATCH "${ACMS_API}/redirects/7/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"trigger": "always", "status": "close"}'取得したときの ETag を If-Match で送ると、ほかの人が先に変更していた場合に上書きしません(REST API で安全に書き込むための仕組み)。上の階層のブログのルールは、そのブログの URL から更新します(この URL では 404)。
削除
curl -X DELETE "${ACMS_API}/redirects/7/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}"成功すると 204 を返します。削除の回数には、トークンごとの 1 時間あたりの上限(rest_api_destructive_limit_per_hour)があります。
並べ替え
ids に、URL のブログのルールすべての ID を、照合する順(先に照合するものが先)に、重複なく指定します。上の階層のブログのルールは含めません。足りない・多い場合は 422 です。
curl -X POST "${ACMS_API}/redirects/reorder/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"ids": [12, 7, 9, 8]}'CSV から一括で登録する
管理画面には CSV の読み込みはありません。数百件の移行表は、REST API を呼ぶスクリプトで登録します。次は、CSV を 1 行ずつ POST /redirects に送る PHP のスクリプトです(PHP 8.3〜8.5、curl 拡張が必要)。
CSV の形式
1 行目は見出しです。列の順番は自由で、見出しの名前でキーを決めます。空の欄は既定値になります。カンマや {2,3} を含む値は、ダブルクォートで囲みます。Excel で保存した UTF-8(BOM 付き)の CSV も読めます。
source,destination,status_code,match_type,trigger,query,scope,name
/about/company.html,/company/,301,exact,,,,リニューアル
/about/access.html,/company/access/,301,exact,,,,リニューアル
"^/news(/.*)?$",/topics$1/,301,regex,,,,ディレクトリ名の変更
/item?id=5,/products/blue-chair/,301,exact,always,exact,,旧カート
/campaign/2025/,,410,prefix,,,,終了したキャンペーンスクリプト(import-redirects.php)
<?php
declare(strict_types=1);
/*
* CSV のリダイレクトのルールを、REST API(POST /redirects)で登録する。
*
* 使い方:
* export ACMS_API='https://example.com/rest-api/acms/v1'
* export ACMS_API_TOKEN='acms_...'
* php import-redirects.php redirects.csv --dry-run # 検査だけ(保存しない)
* php import-redirects.php redirects.csv # 登録する
*/
$api = (string) getenv('ACMS_API');
$token = (string) getenv('ACMS_API_TOKEN');
if ($api === '' || $token === '') {
fwrite(STDERR, "環境変数 ACMS_API と ACMS_API_TOKEN を設定してください。\n");
exit(1);
}
$file = $argv[1] ?? '';
$dryRun = in_array('--dry-run', $argv, true);
if ($file === '' || !is_readable($file)) {
fwrite(STDERR, "使い方: php import-redirects.php redirects.csv [--dry-run]\n");
exit(1);
}
$handle = fopen($file, 'r');
$header = fgetcsv($handle, escape: '');
if (!is_array($header)) {
fwrite(STDERR, "CSV の見出しの行を読めませんでした。\n");
exit(1);
}
$header[0] = (string) preg_replace('/^\xEF\xBB\xBF/', '', (string) $header[0]); // BOM を除く
$header = array_map(fn ($name) => trim((string) $name), $header);
$url = rtrim($api, '/') . '/redirects/' . ($dryRun ? '?dry_run=1' : '');
$line = 1;
$failed = 0;
while (($row = fgetcsv($handle, escape: '')) !== false) {
$line++;
if ($row === [null]) {
continue; // 空行
}
$values = array_combine($header, array_pad(array_slice($row, 0, count($header)), count($header), ''));
$value = fn (string $key, string $default = '') => trim((string) ($values[$key] ?? '')) !== '' ? trim((string) $values[$key]) : $default;
$body = [
'source' => $value('source'),
'match_type' => $value('match_type', 'exact'),
'status_code' => (int) $value('status_code', '301'),
'trigger' => $value('trigger', 'not_found_only'),
'query' => $value('query', 'pass'),
'scope' => $value('scope', 'local'),
'status' => $value('status', 'open'),
'name' => $value('name'),
];
if (!in_array($body['status_code'], [410, 451], true)) {
$body['destination'] = $value('destination');
}
for ($attempt = 1; $attempt <= 3; $attempt++) {
$retryAfter = 0;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json',
'Accept: application/json',
],
CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
CURLOPT_HEADERFUNCTION => function ($ch, string $headerLine) use (&$retryAfter): int {
if (preg_match('/^Retry-After:\s*(\d+)/i', $headerLine, $match) === 1) {
$retryAfter = (int) $match[1];
}
return strlen($headerLine);
},
]);
$response = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status !== 429) {
break;
}
sleep(max(1, $retryAfter)); // リクエストが多すぎる。待ってから送り直す
}
$json = is_string($response) ? json_decode($response, true) : null;
if ($status === 201 || ($dryRun && $status === 200)) {
echo "{$line}行目: OK {$body['source']}\n";
continue;
}
$failed++;
$details = [];
foreach ((is_array($json) ? ($json['errors'] ?? []) : []) as $error) {
$details[] = ($error['pointer'] ?? '') . ' ' . ($error['code'] ?? '') . ' ' . ($error['detail'] ?? '');
}
if ($details === []) {
$details[] = is_array($json) ? (string) ($json['title'] ?? '') : 'レスポンスを読めませんでした';
}
echo "{$line}行目: 失敗 ({$status}) {$body['source']} " . implode(' / ', $details) . "\n";
}
fclose($handle);
echo $failed === 0 ? "すべて成功しました。\n" : "{$failed} 件失敗しました。\n";
exit($failed === 0 ? 0 : 1);実行の手順
CSV(例
redirects.csv)とスクリプトを同じディレクトリに置きます。ACMS_APIとACMS_API_TOKENを設定します(上の「使う前の準備」)。php import-redirects.php redirects.csv --dry-runを実行し、すべての行が「OK」になるまで CSV を直します。--dry-runを外して実行し、登録します。管理画面の「リダイレクト管理」で件数と優先順位を確かめ、必要なら並べ替えます。CSV の上の行ほど優先順位が高くなります(末尾に追加するため)。
代表的な旧 URL をいくつか
curl -Iで確かめます。
途中で失敗した行があっても、ほかの行の登録は続けます。失敗した行だけを CSV に残して、もう一度実行してください(成功した行をもう一度送ると、重複で失敗します)。
CSV の中で同じ転送元を 2 回書くと、2 回目は重複で失敗します。
トークンごとの 1 分あたりのリクエスト数に上限(
rest_api_rate_limit_per_minute、既定 300)があります。超えると 429 とRetry-Afterが返るため、スクリプトは待ってから送り直します。
Hook で照合の結果を変える(extendsRedirectMatch)
ルールを照合した後、転送の直前に呼ばれます。一致した結果を差し替えたり、取り消したり、ルールに一致しなかったアクセスに転送を足したりできます。雛形は extension/acms/Hook.php にあります。Hook を使うには、config.server.php の HOOK_ENABLE を 1 にします(既定は 0)。
引数 | 内容 |
|---|---|
|
|
|
|
例: ドメインを見て転送する
旧ドメインと新ドメインが同じ a-blog cms に届く場合に、旧ドメインへのアクセスだけを新ドメインへ送る例です(よくある移行のパターンと登録例 の「ドメインを移した」)。extension/acms/Hook.php の extendsRedirectMatch に書きます。
public function extendsRedirectMatch(?\Acms\Services\Redirect\MatchResult &$result, array $context): void
{
// 旧ドメインへのアクセスを、パスとクエリを保ったまま新ドメインへ 301 で送る
$host = strtolower($_SERVER['HTTP_HOST'] ?? '');
if ($context['trigger'] === 'always' && $host === 'old.example.jp') {
$location = 'https://www.new-example.jp' . $context['path'];
if ($context['query'] !== '') {
$location .= '?' . $context['query'];
}
$result = new \Acms\Services\Redirect\MatchResult(null, $location, 301);
}
}例: 英語ページの転送先を変える
public function extendsRedirectMatch(?\Acms\Services\Redirect\MatchResult &$result, array $context): void
{
// 英語ページからの転送先を、英語のページのパスに変える
if ($result !== null && $result->location !== null && str_starts_with($context['path'], '/en/')) {
$result = new \Acms\Services\Redirect\MatchResult($result->rule, '/en' . $result->location, $result->statusCode);
}
// ルールに一致しなかった旧キャンペーンのページを、404 のときだけトップへ 302 で転送する
if (
$result === null
&& $context['trigger'] === 'not_found_only'
&& str_starts_with($context['path'], '/campaign/')
) {
$result = new \Acms\Services\Redirect\MatchResult(null, '/', 302);
}
}ルールに由来しない転送を足すときは、
ruleにnullを渡します。差し替えた結果は、転送先の書き方(
/で始まるパスかhttp/httpsの URL)と、ステータスコードが 301 / 302 / 307 / 308 / 410 / 451 のどれかで転送先の有無と合っているかを確かめてから送ります。合わないときは転送せずに、ログ(「リダイレクトの転送先またはステータスコードが不正なため転送しませんでした」)を残します。転送が繰り返されないか(ループ)は確かめません。転送先の URL で、同じ転送をもう一度足さないようにしてください。
照合の対象になるアクセス(GET / HEAD。管理画面・API などを除く)ごとに、
alwaysで 1 回、ページが見つからなかったときにnot_found_onlyでもう 1 回呼ばれます。ページキャッシュに当たるアクセスでも呼ばれるため、データベースや外部への問い合わせなどの重い処理は避けてください。triggerがalwaysのときに転送を足すと、ページがあっても転送します。ページが無いときだけ足すなら、not_found_onlyのときに絞ります。サイト内のパスの転送先は、サイトのルートからのパスで書きます。サブディレクトリに設置しているサイトでは、転送の直前に設置先のディレクトリが付きます。
よくある質問・つまずき
403 になる
トークンを発行したユーザーが、URL のブログの管理者権限を持っていない可能性があります。また、トークンに redirects:read / redirects:write のスコープが付いているかを確かめます(汎用の read / write では使えません)。
PATCH・DELETE が 404 になる
上の階層のブログのグローバルのルールは、一覧には出ますが、子ブログの URL からは更新・削除できません。ルールの blog_id のブログの URL で操作します。
並べ替えが 422 になる
ids に、URL のブログのルールすべてを含める必要があります。一覧を取得した後にルールが増減していないか、上の階層のブログのルールを含めていないかを確かめます。
Hook が呼ばれない
HOOK_ENABLE が有効か、照合の対象になるアクセスか(管理画面・テンプレートを指定したアクセスなどは対象外)を確かめます。