リダイレクト

目次

リダイレクト管理


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

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

リダイレクト管理は、旧 URL から新しい URL への転送や、削除したページの 410 応答を、管理画面で登録する機能です。サイトのリニューアルで URL を変えたとき、カテゴリーのコードを変えたとき、別のドメインへ移ったとき、ページを削除したときなどに使います。.htaccess や Web サーバーの設定を書き換える必要はありません。

このページでは、登録の手順と、作成・編集の画面の項目を説明します。関連するページは次のとおりです。

できること

  • 転送元のパスを、完全一致・前方一致・正規表現のどれかで照合します。

  • ステータスコード 301 / 302 / 307 / 308 で転送します。410 / 451 は転送せず、そのステータスのページを返します。

  • 転送先には、サイト内のパス(/ で始まるもの)か、http / https で始まる別のドメインの URL を指定します。

  • 正規表現では、一致した部分を $1 などで転送先に差し込めます。

  • 「404 のときだけ」転送するか、「常に」転送するかを、ルールごとに選びます。

  • クエリ文字列を転送先へ引き継ぐか、クエリ文字列まで含めて照合するかを、ルールごとに選びます。

  • ルールはブログごとに持ちます。「グローバル」にすると、下の階層のブログにも適用します。

  • 優先順位(照合の順番)を決め、有効・無効を切り替えます。

  • 保存のときに、同じ転送元の重複と、転送が繰り返される設定(ループ)を見つけて止めます。

ほかの機能との違い

URL にかかわる既存の機能と役割が違います。目的に合わせて使い分けてください。

機能

役割

転送するか

リダイレクト管理

リクエストのパスをルールと照合し、別の URL へ転送する。または 410 / 451 を返す

する

エイリアス

同じブログを、別のドメインや別のブログコードでも表示する

しない

ルール

URL や条件に応じて、テーマやモジュールなどの設定を切り替える

しない

Web サーバーの設定(.htaccess など)

a-blog cms より前に、サーバーが転送する

する

リダイレクトのルールが照合するのはパスだけで、ドメインは照合しません。エイリアスの別のドメインでアクセスした場合も、同じパスのルールに一致します。ドメインごとに転送先を変えたいときは、Web サーバーの設定か、Hook(REST API と Hook でリダイレクトを扱う)を使います。

画面の場所と権限

管理画面の「その他管理」の「リダイレクト」で管理します(URL は /bid/{ブログID}/admin/redirect_index/)。サイト全体にかかわるルールは、ルートブログに置くのが基本です。

  • 使えるのは、そのブログの管理者権限を持つユーザーです(Webhook・エイリアスの管理と同じ権限です)。

  • 上の階層のブログのルールも一覧に出ますが、編集できるのは、そのブログの管理者権限があるときだけです。

登録から動作確認までの手順

旧 URL /old/page/ を新しい URL /new/page/ へ 301 で転送する例です。

  1. 転送の一覧(旧 URL と新しい URL の組)を用意します。件数が多いときは、REST API と Hook でリダイレクトを扱う の CSV からの一括登録も検討してください。

  2. 「リダイレクト管理」で「リダイレクトを作成」を押し、転送元(マッチ方式「完全一致」、パス /old/page/)・ステータスコード(301)・転送先(/new/page/)を入力して作成します。項目の意味は次の表のとおりです。

  3. 旧ページが残っていても転送したいときは、発火タイミングを「常に」にします(既定は「404 のときだけ」)。

  4. 前方一致・正規表現のルールが先にあると、そちらに先に一致します。優先順位を確かめます。

  5. ログアウトした状態(ブラウザのシークレットウィンドウなど)で /old/page/ を開き、/new/page/ へ移ることを確かめます。

「リダイレクトを作成」のモーダル
「リダイレクトを作成」のモーダル

ターミナルでは、curl -I で応答のヘッダーを確かめられます。

curl -I https://example.com/old/page/
HTTP/2 301
cache-control: no-store, max-age=0
pragma: no-cache
expires: 0
location: /new/page/
  • 転送の応答には、ブラウザにキャッシュさせないヘッダーを付けています。ルールを直したり消したりすると、次のアクセスからすぐに反映されます。

  • Location のサイト内のパスは、サブディレクトリに設置しているサイトでは設置先のディレクトリを付けて返します。

  • 日本語を含む転送先は、送るときにパーセントエンコードします。管理画面では日本語のまま入力できます。

作成・編集の画面の項目

「リダイレクトを作成」のモーダルと、一覧の行の「編集」で開く「リダイレクトを編集」のモーダルは、同じ項目です。右の列は、REST API と Hook でリダイレクトを扱う で同じ値を送るときのキーです。

項目(画面の名前)

選択肢・入力

新規作成時の値

説明・入力例

REST API のキー

ステータス

「有効」のチェック

有効(チェックあり)

有効のルールだけを照合します。チェックを外すと無効で保存され、照合しません(ルールは残ります)

status(open / close)

転送元(マッチ方式)

完全一致 / 前方一致 / 正規表現

完全一致

照合のしかたです。違いは リダイレクトの照合の規則 を参照

match_type(exact / prefix / regex)

転送元(パス)

文字列(512 文字まで)

空

完全一致・前方一致は / で始まるパス。例: /old/page/、/news/。正規表現は区切り文字なしのパターン。例: ^/blog/(\d+)$

source

ステータスコード

301 恒久的な移動 / 302 一時的な移動 / 307 一時的な移動(メソッドを保つ) / 308 恒久的な移動(メソッドを保つ) / 410 削除済み(転送しない) / 451 法的な理由で公開できない(転送しない)

301

410 / 451 を選ぶと「転送先」の欄は使いません

status_code(数値)

転送先

文字列(1024 文字まで)

空

/ で始まるサイト内のパス、または http / https で始まる URL。例: /new/page/、https://www.example.jp/。正規表現では $1 や ${1} で一致した部分を使えます

destination

発火タイミング

404 のときだけ(ページが存在しないときだけ転送する) / 常に(ページが存在していても転送する)

404 のときだけ

照合するタイミングです。リダイレクトの照合の規則 の「発火タイミングと照合の順番」を参照

trigger(not_found_only / always)

クエリ文字列

転送先へ引き継ぐ / 引き継がない / クエリも照合する(完全一致のみ)

転送先へ引き継ぐ

「クエリも照合する」は完全一致のときだけ選べます。転送元に ?id=5 のようにクエリまで書きます

query(pass / ignore / exact)

グローバル

「下の階層のブログにも適用する」のチェック

チェックあり(使えないブログではなし)

チェックすると、下の階層のすべてのブログでも照合します。下の階層に別のドメインのブログがあるブログでは選べません

scope(global / local)

メモ

文字列(255 文字まで)

空

管理用のメモです

name

REST API で作成するときの既定値は、画面と一つだけ違います

REST API で scope を省くと local(このブログだけ)で作成します。画面の既定はグローバルです。

保存できないもの

保存するときに次の検査をし、当てはまる項目の下にメッセージを出します。

画面のメッセージ

原因と直し方

転送元を入力してください。

転送元が空です

転送元は「/」で始まるパスで入力してください。前方一致でサイト全体(「/」)は指定できません。

完全一致・前方一致で / から始まっていない、または前方一致で / だけを指定しています。サイト全体を転送するときは正規表現 ^/(.*)$ を使います

正規表現の書き方に誤りがあります。

正規表現として解釈できません。括弧の数や、エスケープの漏れを確かめます

転送元に「?」を含められるのは、完全一致で「クエリも照合する」を選んだときだけです。

転送元に ? を書いたまま、別のマッチ方式やクエリ文字列の設定を選んでいます

同じ転送元・同じ発火タイミングのリダイレクトがすでにあります。

このブログの有効なルールに、同じマッチ方式・同じ転送元・同じ発火タイミングのものがあります。片方を無効にするか、削除します

転送元が長すぎます。日本語や記号はエンコードすると長くなるため、エンコードした後で512文字以内になるよう短くしてください。

日本語の多いパスは、エンコードした後の長さで数えます

転送先を入力してください。

301 / 302 / 307 / 308 で転送先が空です

転送先は「/」で始まるパスか、http / https で始まる URL で入力してください。

//example.com、javascript:、.. を含むパス、ユーザー名やパスワードを含む URL などは使えません

転送先のドメインの部分には「$1」などの後方参照を使えません。パス・クエリの部分で使ってください。

https://example.com$1 のように、ドメインの直後に後方参照を書いています。https://example.com/$1 のように / の後ろに書きます

転送先が転送元に戻るため、転送が繰り返されます。

転送先が自分の転送元に一致する、またはほかのルールをたどって転送元に戻ります。転送先を見直します

下の階層に別のドメインのブログがあるため、下の階層のブログには適用できません。

「グローバル」を外します

優先順位

一覧には、このブログのルールと、上の階層のブログで「グローバル」にしたルールが、照合する順に並びます。優先順位は一覧の並びで決まり、行をドラッグして並べ替えます。

  • 並べ替えられるのは、このブログのルールだけです。

  • 下の階層のブログのルールは、上の階層のブログのルールより先に照合されます。そのため、上の階層のルールより後ろへは移動できません。

  • 有効にするとき、同じ転送元のルールがすでに有効な場合や、転送が繰り返される場合は、そのルールは無効のまま残り、エラーで知らせます。

  • 削除したルールは戻せません。一時的に止めるだけなら、無効にします。

ステータスコードの使い分け

コード

画面の表示

使う場面

301

恒久的な移動

URL を恒久的に変えたとき。サイトのリニューアルやドメインの移転など、多くの場合はこれを選びます

302

一時的な移動

キャンペーン期間だけ別のページへ案内するなど、元の URL に戻す予定があるとき

307

一時的な移動(メソッドを保つ)

302 と同じ用途で、リクエストのメソッドを変えずに転送したいとき

308

恒久的な移動(メソッドを保つ)

301 と同じ用途で、リクエストのメソッドを変えずに転送したいとき

410

削除済み(転送しない)

ページを削除し、代わりのページが無いとき。404 より明確に「削除した」ことを伝えます

451

法的な理由で公開できない(転送しない)

裁判所の命令や権利者の申し立てなど、法的な理由で公開をやめたとき

転送するのは GET / HEAD のアクセスだけです。フォームの送信(POST など)は、307 / 308 を選んでも転送しません。410 / 451 のときに表示するページは、410 / 451 のページをテーマで作る を参照してください。

よくある質問・つまずき

転送されない

次の順に確かめてください。

  1. ルールが有効か。 一覧の「ステータス」が「有効」になっているかを見ます。

  2. ログインしていないか。 ログインしていると、非公開のエントリーなどが表示されるため、「404 のときだけ」のルールが動かないことがあります。ログアウトするか、シークレットウィンドウで確かめます。

  3. 旧 URL のページが残っていないか。 「404 のときだけ」は、ページが表示できるときは転送しません。旧ページを残したまま転送するなら「常に」にします。

  4. 先に別のルールに一致していないか。 照合は優先順位の順で、最初に一致したルールを使います。上にある前方一致・正規表現のルールに先に一致していないかを見ます。

  5. パスの書き方。 大文字と小文字は区別します(/Old/ と /old/ は別)。サイトのルートからのパスで書きます。

  6. 子ブログの URL ではないか。 /news/old/ のように子ブログのコードで始まる URL は、子ブログのアクセスとして照合します。ルートブログのルールを効かせるには「グローバル」にするか、子ブログにルールを登録します。

  7. 実在するファイルではないか。 同梱の .htaccess は、実在するファイル(/old/page.html というファイルが残っている、など)へのアクセスを a-blog cms に渡しません。ファイルを削除してください。

  8. 照合しない URL ではないか。 管理画面・API・テンプレートを指定したアクセス・ログイン画面などは照合しません(リダイレクトの照合の規則 の「照合しない URL」)。

転送が 2 回起きる

同梱の .htaccess は、拡張子の無いパスの末尾に / を付けて 301 で転送します。/old/page へのアクセスは、まず /old/page/ へ転送され、そのあとでルールに一致します。照合では末尾の / の有無を区別しないため、ルールは 1 つで足ります。

一時的に別のページへ案内したい

キャンペーン期間だけ案内するときは、ステータスコードを「302 一時的な移動」、発火タイミングを「常に」にします。期間が終わったら、ルールのステータスを無効にするか削除します。

「グローバル」を選べない

下の階層に、別のドメインのブログがあるブログでは選べません(「下の階層に別のドメインのブログがあるため、このブログでは使えません。」)。パスだけで照合するため、別のドメインのブログで意図せず一致するのを防ぐためです。子ブログそれぞれにルールを登録してください。

ブログを削除したら、ルールはどうなるか

ブログを削除すると、そのブログのリダイレクトのルールも削除されます。

リダイレクトの照合の規則


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

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

リダイレクト管理 で登録したルールが、どの URL に、どの順番で一致するかを説明します。

照合するパス

  • 照合するのは、サイトのルートからのパスです(ブログのディレクトリからの相対ではありません)。子ブログの URL も、ブログのコードを含めて書きます(/news/old/ など)。

  • サブディレクトリに設置しているサイトでは、設置先のディレクトリを除いたパスで照合します。

  • 末尾の / の有無は区別しません。/old/page/ と /old/page は同じです。

  • 大文字と小文字は区別します。

  • パーセントエンコードの有無は区別しません。日本語のパスは、日本語のまま書けます。

  • ドメインは照合しません。エイリアスの別のドメインでアクセスした場合も、パスで照合します。

転送先にサイト内のパス(/ で始まるもの)を書いた場合も、サイトのルートからのパスとして扱います。サブディレクトリに設置しているサイトでは、転送するときに設置先のディレクトリが付きます。例えば /sub/ に設置したサイトで転送先を /new/ にすると、/sub/new/ へ転送します。

同梱の .htaccess との関係

  • 拡張子の無いパスで末尾に / が無いアクセスは、.htaccess が先に末尾に / を付けて 301 で転送します。ルールの照合はそのあとです。

  • /index.html で終わるアクセスは、.htaccess が先に / で終わる URL へ転送します。

  • 実在するファイルへのアクセスは、a-blog cms に届きません。

マッチ方式

マッチ方式

一致するもの

例

完全一致

パスが同じもの

/old/page/ は /old/page/ だけに一致

前方一致

転送元のパスと、その下のパス。パスの区切りで判定します

/old/ は /old/ と /old/a/b/ に一致し、/older/ には一致しない

正規表現

正規表現に一致するもの

^/blog/(\d+)$ は /blog/123/ に一致

前方一致

前方一致で一致した場合、転送先は入力した URL そのままです。転送元より後ろのパスは、転送先に付きません。/old/a/b/ を /new/a/b/ のように、後ろのパスを残して転送したいときは、正規表現を使います。前方一致でサイト全体(/)は指定できません。

正規表現

  • 区切り文字(/ や #)は付けずに、中身だけを書きます。{2,3} のような量指定子も、そのまま書けます。

  • UTF-8 として照合します(PHP の u 修飾子を付けて照合します)。(?i) などの修飾子をパターンの先頭に書けます。

  • 照合する文字列は、先頭に / が付き、末尾の / を除いたパスです。$ で終わりを固定するときは、末尾の / を書かないでください。トップページは / です。

  • 転送元は / で始めなくても保存できますが、^/ で始めると意図しない一致を避けられます。

  • 転送先では、$1 や ${1} で一致した部分を使えます。差し込む値は、URL として正しくエンコードし直します。

  • 転送先のドメインの部分(:// から最初の / まで)には、$1 などを使えません。

  • 書き方に誤りのある正規表現は保存できません。

例は よくある移行のパターンと登録例 の「正規表現の例」を参照してください。

クエリ文字列

設定

照合

転送先

転送先へ引き継ぐ(既定)

パスだけで照合します

アクセスしたクエリ文字列を付けます。転送先にすでに同じキーがあれば、転送先の値を残します

引き継がない

パスだけで照合します

クエリ文字列を付けません

クエリも照合する(完全一致のみ)

パスとクエリ文字列の両方で照合します。キーの並び順は問いません。アクセスに余分なキーがあれば一致しません

クエリ文字列を付けません

例: 転送先 /new/?ref=doc(クエリ文字列「転送先へ引き継ぐ」)のルールに ?utm_source=x&ref=y でアクセスすると、Location: /new/?ref=doc&utm_source=x になります(転送先の ref を残し、utm_source を足す)。

「クエリも照合する」は、旧サイトが /item?id=5 のようにクエリ文字列でページを区別していた場合に使います。転送元に ? から後ろも書きます。転送元に ? を書けるのは、この設定のときだけです。広告や解析のためのパラメーター(utm_source など)を転送で落とさないため、既定は「転送先へ引き継ぐ」です。

発火タイミングと照合の順番

発火タイミング

照合するとき

404 のときだけ

ページを表示しようとして、URL に合うページが見つからなかったとき。ページがあれば転送しません

常に

ページがあるかどうかを調べる前。ページがあっても転送します。ページキャッシュがあるページでも転送します

1 回のアクセスでは、次の順に照合し、最初に一致したもので転送します。

  1. 「常に」のルール

  2. 通常のページの表示

  3. ページが見つからなかった(404)ときは、「404 のときだけ」のルール

「常に」のルールは、ログインの有無・非公開のブログ・メンテナンスモードに関係なく転送します。

「404 のときだけ」は、閲覧を拒否したために 404 を返しているページ(閲覧権限の無いエントリーや、404 を返す設定の非公開ブログなど)では照合しません。拒否の結果を転送で上書きしないためです。迷ったときは、既存のページを隠す心配の無い「404 のときだけ」を選んでください。

照合の優先順位の具体例

同じ発火タイミングのルールどうしは、次の順に照合します。管理画面の一覧の「優先順位」の順と同じです。マッチ方式(完全一致かどうか)による優先はありません。

  • 下の階層のブログのルールを、上の階層のブログのルールより先に照合します。親と子のブログに同じ転送元のルールがあれば、子のブログのルールが使われます。

  • 同じブログのルールは、一覧で並べた順に照合します。

例 1: 前方一致と完全一致

優先順位

マッチ方式

転送元

転送先

1

前方一致

/service/

/solutions/

2

完全一致

/service/web/

/solutions/web-design/

/service/web/ へのアクセスは、1 の前方一致に先に一致し、/solutions/ へ転送します。2 を使いたいときは、2 を 1 より上へ並べます。

例 2: 発火タイミングの違い

優先順位

マッチ方式

転送元

転送先

発火

1

完全一致

/about/

/company/

404 のときだけ

2

前方一致

/

(保存できない)

—

3

正規表現

^/about(/.*)?$

/corporate$1/

常に

/about/ へのアクセスでは、優先順位に関係なく先に「常に」の 3 を照合し、/corporate/ へ転送します。1 は、3 が無いか一致しないときに、ページが見つからなかった場合だけ使われます。(2 のように、前方一致で / は保存できません。)

例 3: 親と子のブログ

所属ブログ

グローバル

転送元

転送先

ルートブログ

グローバル

^/news/(.*)$(正規表現)

/topics/$1

子ブログ(コード news)

—

/news/special/(完全一致)

/special-2026/

/news/special/ へのアクセスは子ブログのアクセスなので、子ブログのルールを先に照合し、/special-2026/ へ転送します。それ以外の /news/… は、ルートブログのグローバルのルールで /topics/… へ転送します。

下の階層のブログとの関係

  • 「グローバル」(下の階層のブログにも適用する)にしたルールは、下の階層のすべてのブログでも照合します。サイト全体の移行用のルールは、ルートブログにグローバルで登録すると、子ブログにも効きます。

  • 「グローバル」にしていないルールは、そのブログへのアクセスだけで照合します。子ブログのコードで始まる URL(/news/…)は子ブログへのアクセスなので、ルートブログの「グローバル」にしていないルールには一致しません。

  • 子ブログにルールを追加しても、上の階層のグローバルのルールは引き続き効きます(足し合わせて照合します)。

  • 下の階層に別のドメインのブログがあるブログでは、「グローバル」を選べません。パスだけで照合するため、別のドメインのブログで意図せず一致するのを防ぐためです。

「グローバル」を選べるかどうかは、保存するときにだけ確かめます

グローバルのルールを保存した後で、下の階層に別のドメインのブログを作ったり、ブログの親を付け替えたりした場合は、そのブログでもグローバルのルールが照合されます。ブログの構成を変えたときは、ルールを見直してください。

照合しない URL

次のアクセスは、ルールで照合しません。

  • GET / HEAD 以外のアクセス(フォームの送信など)

  • 管理画面、API、メディアのダウンロード、テンプレートを指定したアクセス、共有プレビュー、ログイン画面などの認証のページ

  • コマンドラインからの実行(静的書き出しなど)

  • ブログを特定できない URL(どのブログのドメインにも当たらないアクセス)

  • .php で終わる旧 URL(下記)

.php で終わる旧 URL

  • /index.php?… は、a-blog cms が先に /?… へ転送し、トップページを表示します。転送後の /?p=123 などを、発火タイミング「常に」・クエリ文字列「クエリも照合する」のルールで受けてください(転送元は /?p=123)。

  • index.php 以外の .php は、同梱の .htaccess がアクセスを禁止しているため、a-blog cms に届きません。Web サーバーの設定で転送してください。

よくある質問・つまずき

「404 のときだけ」のルールが、ページがあるのに動いてしまう

ログインしていない訪問者には表示できないページ(非公開・予約公開前など)は、訪問者から見ると「ページが見つからない」ことがあります。その URL は転送されることがあります。逆に、ログインしていると表示できるため転送されません。動作はログアウトした状態で確かめてください。

ページキャッシュを使っていても転送されるか

「常に」のルールは、ページキャッシュを返す前に照合するため、キャッシュ済みの旧 URL も転送します。「404 のときだけ」は、ページが見つからなかったときに照合します。

転送のループを防ぐには

保存のときに、転送先が転送元に戻る組み合わせ(ほかのルールをたどって戻る場合を含む)を「転送先が転送元に戻るため、転送が繰り返されます。」で止めます。正規表現で後方参照を使う転送先は保存のときに判定できないため、転送のときに、転送先が同じルールにもう一度一致する場合は転送しません。

よくある移行のパターンと登録例


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

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

よくある移行の場面ごとに、ルールの登録例をまとめます。画面の操作は リダイレクト管理、照合の細かい規則は リダイレクトの照合の規則 を参照してください。

表の見方

各例の表の列(マッチ方式・転送元・転送先・コード・発火)は、作成・編集の画面の同名の項目に対応します。書いていない項目は、新規作成時の値(クエリ文字列「転送先へ引き継ぐ」など)のままです。例のドメインは example.com(今のサイト)、www.new-example.jp(移転先)です。

サイトリニューアルで URL の構成が変わった

ページごとに新しい URL を決めた

旧ページと新ページが 1 対 1 で対応するときは、完全一致で 1 件ずつ登録します。旧ページは削除済みのため、発火は「404 のときだけ」で足ります。

マッチ方式

転送元

転送先

コード

発火

完全一致

/about/company.html

/company/

301

404 のときだけ

完全一致

/about/access.html

/company/access/

301

404 のときだけ

完全一致

/recruit/index.html

/careers/

301

404 のときだけ

  • /recruit/index.html へのアクセスは、同梱の .htaccess が先に /recruit/ へ転送します。転送元は /recruit/ と書いても同じ結果です。

  • 旧 URL のファイル(about/company.html など)がサーバーに残っていると、a-blog cms に届かず転送されません。ファイルを削除してください。

ディレクトリごと名前を変えた

/news/ 以下を /topics/ 以下へ、後ろのパスを残して移すときは正規表現を使います。前方一致は、転送先に後ろのパスを付けません。

マッチ方式

転送元

転送先

コード

発火

正規表現

^/news(/.*)?$

/topics$1/

301

404 のときだけ

アクセスした URL

転送先

/news/

/topics/

/news/2024/04/

/topics/2024/04/

/newsletter/

一致しない

照合するパスは末尾の / を除いたもの(/news、/news/2024/04)です。(/.*)? で「/news だけ」と「/news/ 以下」の両方に一致させています。

拡張子 .html の URL をやめた

マッチ方式

転送元

転送先

コード

発火

正規表現

^/(.+)\.html$

/$1/

301

404 のときだけ

/about/company.html は /about/company/ へ転送します。エントリーの URL に .html を使っているサイトでは、表示できるエントリーには一致させたくないため、必ず「404 のときだけ」にします。

カテゴリーのコードを変えた

カテゴリーのコードを news から topics に変えた例です。カテゴリーの一覧(/news/、/news/page/2/)と、エントリー(/news/entry-123.html)の URL が変わります。古いコードの URL はページが無くなるので、発火は「404 のときだけ」にします。

優先順位

マッチ方式

転送元

転送先

コード

発火

1

完全一致

/news/

/topics/

301

404 のときだけ

2

正規表現

^/news/(.+\.html)$

/topics/$1

301

404 のときだけ

3

正規表現

^/news/(.+)$

/topics/$1/

301

404 のときだけ

  • 2 はエントリー(.html で終わる URL)を、末尾に / を付けずに転送します。3 は一覧のページ送りなどを、末尾に / を付けて転送します。2 を 3 より上に並べます(3 は .html の URL にも一致するため)。

  • カテゴリーが子ブログにある場合(/blog/news/ など)は、照合するパスもブログのコードから書きます(^/blog/news/(.+)$)。ルールは子ブログに登録するか、ルートブログに「グローバル」で登録します。

カテゴリーの階層を変えた(/service/web/ を /web/ に上げた、など)ときも、同じように書けます。

マッチ方式

転送元

転送先

コード

発火

正規表現

^/service/web(/.*)?$

/web$1/

301

404 のときだけ

ドメインを移した

リダイレクトのルールはパスだけで照合し、ドメインを見ません。そのため、移転の方法で登録のしかたが変わります。

旧ドメインの a-blog cms を残して、新しいサイトへ転送する

旧ドメインで旧サイト(a-blog cms)を動かしたまま、すべてのアクセスを新しいドメインへ送る例です。旧サイトのルートブログに登録します。

マッチ方式

転送元

転送先

コード

発火

グローバル

正規表現

^/(.*)$

https://www.new-example.jp/$1

301

常に

チェックあり

  • 旧ページが残っていても転送するため、発火は「常に」にします。

  • /about/ は https://www.new-example.jp/about へ転送します(照合するパスに末尾の / が無いため)。移転先のサイトが末尾に / を付けて転送する設定なら、そのまま届きます。

  • 後方参照($1)は、ドメインの後ろの / より後ろにだけ書けます。

  • クエリ文字列は「転送先へ引き継ぐ」(既定)のままにすると、?utm_source=… などを移転先へ渡します。

  • 下の階層に別のドメインのブログがあると「グローバル」を選べません。その場合は、ブログごとに登録します。

旧ドメインと新ドメインが同じ a-blog cms に届く

エイリアスやブログのドメインの設定で、旧ドメインと新ドメインのどちらでも同じサイトが表示される場合、上のルールは新ドメインへのアクセスにも一致し、転送が繰り返されます。この場合はリダイレクト管理ではなく、Web サーバーの設定で、ドメインを見て転送してください。プラグイン・extension/acms の Hook でドメインを見て転送する例は、REST API と Hook でリダイレクトを扱う にあります。

ブログのドメインを変えたあとに旧ドメインへ来たアクセスが、どのブログにも当たらない場合(「404 Not Found Blog」と表示される場合)も、a-blog cms のルールでは扱えません。Web サーバーの設定で転送してください。

ページを削除した・公開をやめた(410 / 451)

代わりのページが無い削除には 410、法的な理由で公開をやめたページには 451 を使います。転送はせず、そのステータスのページを表示します。ページの作り方は 410 / 451 のページをテーマで作る を参照してください。

場面

マッチ方式

転送元

コード

発火

削除したエントリー 1 件

完全一致

/campaign/2025-summer.html

410

404 のときだけ

終わったキャンペーンのディレクトリを丸ごと

前方一致

/campaign/2025/

410

404 のときだけ

削除の申し立てを受けたページ

完全一致

/column/entry-321.html

451

常に

  • 410 / 451 のときは「転送先」を入力しません。

  • ページをまだ表示できる状態で 410 / 451 にしたいときは、発火を「常に」にします。

  • 閲覧が許されていないアクセス(非公開のブログ、閲覧権限の無いエントリーなど)では、「常に」でも 410 / 451 にしません。訪問者には、もともとの応答(404 など)が返ります。

クエリ文字列でページを区別していた旧 URL

旧サイトが /item?id=5 や /?p=123 のように、クエリ文字列でページを区別していた場合の例です。マッチ方式「完全一致」、クエリ文字列「クエリも照合する(完全一致のみ)」にして、転送元に ? から後ろも書きます。

マッチ方式

転送元

転送先

コード

発火

クエリ文字列

完全一致

/item?id=5

/products/blue-chair/

301

常に

クエリも照合する(完全一致のみ)

完全一致

/item?id=6

/products/red-chair/

301

常に

クエリも照合する(完全一致のみ)

完全一致

/?p=123

/blog/hello-world.html

301

常に

クエリも照合する(完全一致のみ)

  • /?p=123 のパス / はトップページとして表示できるため、「404 のときだけ」では転送されません。発火は「常に」にします。/item も同じく、一覧などのページとして表示できる場合があるため「常に」が確実です。

  • キーの並び順は問いません(?a=1&b=2 と ?b=2&a=1 は同じ)。ただし、アクセスに余分なキーがあると一致しません(/item?id=5&utm_source=mail は一致しない)。

  • /index.php?p=123 は、a-blog cms が先に /?p=123 へ転送します。転送元は /?p=123 と書きます。

  • /item?id=5 へのアクセスは、同梱の .htaccess が先に /item/?id=5 へ転送し、そのあとでこのルールに一致します。

正規表現の例

正規表現は区切り文字を付けずに書きます。照合する文字列は、先頭に / が付き、末尾の / を除いたパスです(/news/2024/ なら /news/2024)。次の例は、照合の処理と同じ規則で、表のとおりに転送先を組み立てることを確かめています。

目的

転送元(正規表現)

転送先

アクセスした URL → 転送先

ディレクトリ名の変更(後ろを残す)

^/news(/.*)?$

/topics$1/

/news/2024/04/ → /topics/2024/04/

拡張子 .html をやめる

^/(.+)\.html$

/$1/

/about/company.html → /about/company/

日付の階層を 1 つの名前にまとめる

^/blog/(\d{4})/(\d{2})/(\d+)\.html$

/blog/$1-$2-$3.html

/blog/2019/08/123.html → /blog/2019-08-123.html

言語ごとのディレクトリをまとめて変える

^/(en|zh)/info(/.*)?$

/$1/news$2/

/zh/info/a/ → /zh/news/a/

大文字・小文字を区別しない

(?i)^/Download(/.*)?$

/downloads$1/

/DOWNLOAD/ → /downloads/

日本語のディレクトリ名

^/お知らせ/(.+)$

/news/$1/

/%E3%81%8A%E7%9F%A5%E3%82%89%E3%81%9B/abc/ → /news/abc/

サイト全体を別のドメインへ

^/(.*)$

https://www.new-example.jp/$1

/about/ → https://www.new-example.jp/about

  • 量指定子 {4} や {2,3} は、そのまま書けます。

  • 日本語のパスは、日本語のまま書けます(アクセスのパスはデコードしてから照合します)。

  • $1 に差し込む値は、URL として正しくエンコードし直します。/ は区切りとして残します。

  • 一致しなかったグループ((/.*)? が空のとき)の $1 は空になります。

  • 後方参照を使う転送先は、保存のときにループを判定できないため、転送のときに確かめます。転送先が同じルールにもう一度一致する場合は、そのルールでは転送しません。

正規表現のルールを多く登録すると、照合が重くなります

前方一致・正規表現のルールは、アクセスのたびに順に照合します。数百件になる場合は、完全一致で書けないか、1 つの正規表現にまとめられないかを検討してください。

よくある質問・つまずき

前方一致で転送したら、後ろのパスが消えた

前方一致は、転送先を入力したとおりに使います。後ろのパスを残すときは、正規表現と $1 を使います(「ディレクトリごと名前を変えた」)。

正規表現のルールより、完全一致のルールを優先したい

照合は「優先順位」の順で、マッチ方式による優先はありません。例外にしたい完全一致のルールを、正規表現・前方一致のルールより上へドラッグします。

どの URL が一致するか、登録前に試したい

REST API の ?dry_run=1 を使うと、保存せずに検査(重複・ループ・書き方)だけを行えます。照合の結果そのものは、ルールを無効にして登録しておき、検証環境で有効にして curl -I で確かめるのが確実です。

410 / 451 のページをテーマで作る


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

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

ステータスコードが 410(削除済み)・451(法的な理由で公開できない)のルールに一致すると、転送せずに、テーマのテンプレートでページを表示します。このページでは、そのテンプレートの作り方を説明します。ルールの登録は リダイレクト管理 を参照してください。

表示するテンプレートの決まり方

ステータス

設定キー

既定値

応答のステータス行

410

tpl_410

410.html

410 Gone

451

tpl_451

451.html

451 Unavailable For Legal Reasons

  • テンプレートは、使っているテーマから探し、無ければ親のテーマ、最後に system テーマのものを使います。system テーマの 410.html / 451.html は、見出しと一文だけのページです。

  • load_yaml_tpl が on のサイト(既定)では、404 などのエラーページと同じく、テーマの template.yaml の tpl_410 / tpl_451 の指定も使えます。

  • 「常に」で一致した場合も「404 のときだけ」で一致した場合も、同じテンプレートを使います。

テーマに 410.html が無いときは、system テーマの次のページを HTTP/2 410 で返します。

<!doctype html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>410 Gone</title>
  </head>
  <body>
    <h1>410 Gone</h1>
    <p>お探しのページは削除されました。</p>
  </body>
</html>

テーマにテンプレートを置く手順

  1. サイトで使っているテーマのディレクトリを確かめます(管理画面の「テーマ」で選んでいるテーマ。例: themes/mysite@site/)。公式テーマを直接書き換えず、公式テーマを親にした自分のテーマに置きます。

  2. テーマのディレクトリの直下に 410.html(451 は 451.html)を作ります。下の例をそのまま使えます。

  3. ルールを 1 件登録します(例: マッチ方式「完全一致」、転送元 /test-gone/、ステータスコード「410 削除済み(転送しない)」)。

  4. ログアウトした状態で /test-gone/ を開き、作ったページが表示されることを確かめます。

  5. curl -I でステータスが 410 であることを確かめます(下の「確かめ方」)。

  6. 確認用のルールを削除します。

完全な例: 公式テーマ(site)のレイアウトを使う

公式テーマ site の 404.html と同じく、/_layouts/base.html を継承して、ヘッダー・フッターをサイトと揃える例です。site テーマを親にしたテーマの直下に 410.html として置きます。

@extends("/_layouts/base.html")

@section("page-title")
<div class="page-title-wrapper">
  <div class="page-title-filter"></div>
  <div class="page-title-inner">
    <div class="acms-container">
      <div class="page-title-text-wrap">
        <h1 class="page-title">410</h1>
        <p class="page-title-en">410 Gone</p>
      </div>
    </div>
  </div>
</div>
@endsection

@section("main")
<div class="container-md">
  <section class="not-found-content">
    <h2 class="not-found-title">お探しのページは削除されました。</h2>

    <p class="not-found-paragraph">
      このページは公開を終了しました。お手数ですが、キーワード検索またはホームへ戻るボタンから、ほかのページをお探しください。
    </p>

    <div class="not-found-search">
      @include("/include/parts/search-general.html", {"search-id":"410"})
    </div>

    <p class="not-found-button">
      <a href="%{BASE_URL}" class="button is-width-lg is-bg-white-bordered">ホームに戻る</a>
    </p>
  </section>
</div>
@endsection

451 のページは、同じ形で 451.html を作り、見出しと文言を変えます。

@extends("/_layouts/base.html")

@section("page-title")
<div class="page-title-wrapper">
  <div class="page-title-filter"></div>
  <div class="page-title-inner">
    <div class="acms-container">
      <div class="page-title-text-wrap">
        <h1 class="page-title">451</h1>
        <p class="page-title-en">451 Unavailable For Legal Reasons</p>
      </div>
    </div>
  </div>
</div>
@endsection

@section("main")
<div class="container-md">
  <section class="not-found-content">
    <h2 class="not-found-title">このページは公開を停止しています。</h2>

    <p class="not-found-paragraph">
      法令上の理由により、このページの公開を停止しました。ご不明な点は<a href="%{BASE_URL}contact/">お問い合わせページ</a>からご連絡ください。
    </p>

    <p class="not-found-button">
      <a href="%{BASE_URL}" class="button is-width-lg is-bg-white-bordered">ホームに戻る</a>
    </p>
  </section>
</div>
@endsection

お問い合わせページの URL(%{BASE_URL}contact/)は、site テーマの 404 ページと同じものです。サイトに合わせて変えてください。

完全な例: レイアウトを使わないテーマ

レイアウトの継承を使っていないテーマでは、1 つの HTML として書きます。共通のヘッダーやフッターを @include で読み込めます(パスはテーマに合わせて変えてください)。

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="robots" content="noindex">
  <title>ページは削除されました | %{BLOG_NAME}</title>
</head>
<body>
  <main>
    <h1>お探しのページは削除されました</h1>
    <p>このページは公開を終了しました。</p>
    <p><a href="%{BLOG_URL}">%{BLOG_NAME} のトップページへ戻る</a></p>
  </main>
</body>
</html>
  • 通常のテンプレートと同じく、@include やモジュールを使えます。

  • Basic 認証・閲覧権限の確認が済んでから表示します。認証していない訪問者や、閲覧を拒否された訪問者には表示しません。

  • シークレットのブログ・カテゴリーでログイン画面へ案内するアクセスや、メンテナンス画面を表示するアクセスでは、410 / 451 にしません。

  • 410 / 451 のページは、ページキャッシュに保存しません。

template.yaml で別の名前のファイルを使う

エラーページを errors/ ディレクトリにまとめているテーマでは、テーマの template.yaml に書きます。

tpl_404: errors/404.html
tpl_410: errors/410.html
tpl_451: errors/451.html

テーマにファイルを置く場所は、themes/(テーマ)/errors/410.html です。template.yaml は親のテーマのものも読みます(子のテーマに書いたものが優先です)。

確かめ方

curl -sI https://example.com/test-gone/ | head -1
HTTP/2 410

ブラウザで開いたときは、開発者ツールのネットワークの欄でステータスを確かめます。

よくある質問・つまずき

system テーマの簡単なページが出る

使っているテーマ(とその親のテーマ)に 410.html / 451.html がありません。ファイルの名前と置き場所、template.yaml の tpl_410 / tpl_451 を確かめます。

410 にならず、404 や別の画面になる

  • ルールの発火が「404 のときだけ」で、ページが表示できる状態です。「常に」にします。

  • 閲覧が許されていないページ(非公開のブログなど)、ログイン画面へ案内するページ、メンテナンス中のページは、410 / 451 にしません。

  • ログインしていると、ページが表示できるため「404 のときだけ」のルールに一致しません。ログアウトして確かめます。

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