REST API と Hook でリダイレクトを扱う


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

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

リダイレクトのルールは、REST API でも作成・取得・更新・削除・並べ替えができます。数百件の移行表を登録するときや、ほかのシステムから登録するときに使います。また、プラグインや extension/acms の Hook で、照合の結果を差し替えられます。REST API そのものの使い方は REST API の概要 を参照してください。

使う前の準備

  1. REST API を有効にします(REST API の概要)。

  2. API トークンを発行します(REST API の認証と API トークン)。スコープは redirects:read(読み取り)と redirects:write(書き込み)を付けます。

  3. トークンを発行するユーザーは、ルールを登録するブログの管理者権限を持っている必要があります。

  4. 端末で、ベース 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 など)で操作します。

エンドポイントと本文のキー

メソッドとパス

内容

スコープ

GET /redirects

一覧。管理画面の一覧と同じ範囲(URL のブログのルールと、上の階層のブログのグローバルのルール。無効なものを含む)を、照合する順に返します。page / limit(最大 100、既定 20)を使えます

redirects:read

GET /redirects/{id}

1 件の取得。一覧の範囲外のルールは 404

redirects:read

POST /redirects

作成。URL のブログのルールの末尾に追加します

redirects:write

PATCH /redirects/{id}

一部の更新。URL のブログのルールだけが対象です

redirects:write

PUT /redirects/{id}

全体の置き換え

redirects:write

DELETE /redirects/{id}

削除。同じブログのルールの並び順を 1 から振り直します

redirects:write

POST /redirects/reorder

並べ替え

redirects:write

本文(JSON)のキーは次のとおりです。作成で省いたキーは「既定値」、更新で省いたキーは今の値のままです。

キー

型

既定値(作成)

説明

source

文字列

(必須)

転送元。完全一致・前方一致は / で始まるパス、正規表現はパターン。512 文字まで

match_type

文字列

exact

exact(完全一致)/ prefix(前方一致)/ regex(正規表現)

destination

文字列

(301〜308 では必須)

転送先。1024 文字まで。410 / 451 では保存せず、応答では null

status_code

整数

301

301 / 302 / 307 / 308 / 410 / 451

trigger

文字列

not_found_only

not_found_only(404 のときだけ)/ always(常に)

query

文字列

pass

pass(転送先へ引き継ぐ)/ ignore(引き継がない)/ exact(クエリも照合する。完全一致のときだけ)

scope

文字列

local

local(このブログだけ)/ global(下の階層のブログにも適用する)

status

文字列

open

open(有効)/ close(無効)

name

文字列

空

メモ。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

意味

#/source

required

転送元が空

#/source

invalid

/ で始まっていない、または前方一致で / を指定した

#/source

regex

正規表現の書き方の誤り

#/source

query

完全一致・query: exact 以外で ? を含む

#/source

duplicate

同じ転送元・同じ発火タイミングの有効なルールがある

#/source

matchKeyLength

エンコードした後の転送元が 512 文字を超える

#/destination

required

転送先が空

#/destination

invalid

転送先の書き方の誤り

#/destination

backReference

ドメインの部分に $1 などを使った

#/destination

loop

転送が繰り返される

#/scope

scope

このブログでは global を選べない

各キー

invalid / in

選べない値。型の誤り(文字列のところに数値など)も invalid

一覧・更新・削除・並べ替え

一覧

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);

実行の手順

  1. CSV(例 redirects.csv)とスクリプトを同じディレクトリに置きます。

  2. ACMS_API と ACMS_API_TOKEN を設定します(上の「使う前の準備」)。

  3. php import-redirects.php redirects.csv --dry-run を実行し、すべての行が「OK」になるまで CSV を直します。

  4. --dry-run を外して実行し、登録します。

  5. 管理画面の「リダイレクト管理」で件数と優先順位を確かめ、必要なら並べ替えます。CSV の上の行ほど優先順位が高くなります(末尾に追加するため)。

  6. 代表的な旧 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)。

引数

内容

$result

\Acms\Services\Redirect\MatchResult または null(一致しなかったとき)。rule(一致したルール)・location(転送先。410 / 451 のときは null)・statusCode を持ちます。新しい MatchResult を代入すると差し替え、null を代入すると転送を取り消します

$context

blogId・path(アクセスのパス)・query(クエリ文字列)・trigger(always または not_found_only)

例: ドメインを見て転送する

旧ドメインと新ドメインが同じ 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 が有効か、照合の対象になるアクセスか(管理画面・テンプレートを指定したアクセスなどは対象外)を確かめます。