shopify-redirect-mapping

Shopify リダイレクトマッピング

404 になっている URL のリストから、タイプを考慮したファジーマッチングで Shopify ストア上に有効な 301 リダイレクトを作成します。残ったものは手動レビューキューに入れます。この作業の目的は、検索流入の評価を取り戻し、失われた訪問者を救うことであり、完璧な 1 対 1 のマップを作ることではありません。API ではなくスプレッドシートから一括適用する場合は、最終マップを関連する shopify-matrixify スキルの Redirects シートに渡してください。

最も重要なルール：精度より再現率

関連性はあるものの誤ったリダイレクトでも、404 よりは優れています。近い商品や適切なカテゴリーにたどり着いた訪問者は購入に至る可能性がありますが、リンク切れのページにたどり着いた訪問者は離脱します。301 の転送先がトピックに関連していれば、Google は旧ページの評価をある程度引き継ぎますが、URL が 404 になると評価はまったく引き継がれません。そのため、完璧なマッチを目指すのではなくカバレッジを優先し、誤りは人によるレビューパスで見つけてください。

実例（匿名化された自動車ライフスタイルブランド）。 最初のパスでは、すべての URL タイプに保守的な類似度しきい値 0.92 を一律に使用しました。リンク切れ URL 1,010 件のうち、リダイレクトが作成されたのは 6 件だけで、実質的に何もできていません。マーチャントはこれを役に立たないと判断しました。同じエクスポートをタイプごとのしきい値とタイプ間のフォールバックを使って再実行すると、有効なリダイレクトが 725 件（カバレッジ約 72％）作成されました。教訓は明白です。保守的な初回パスをそのまま適用してはいけません。精度を優先したしきい値は安全に見えて、何も実現しません。

タイプごとのしきい値（提案ではなくデフォルト値）

URL タイプによって許容できる曖昧さは異なります。各リンク切れパスをプレフィックスで分類し、以下のしきい値で同じタイプの有効な在庫だけを対象にマッチングしてください。

• 商品：0.85。 「同じサフィックスで別の商品」のマッチ（販売終了した -jacket が別の -jacket に転送されるなど）を一部受け入れます。これは再現率を高めるために許容するコストであり、実際に誤っているものはレビューで除外します。
• コレクション：0.70。 リンク切れのコレクション URL の多くは、再編による変更です。近いコレクションであれば、ホームページより適切な転送先になります。
• ブログ／ページ：0.85。 コレクションに解決されるブランドページは 0.70 です。残りはレビューキューで確認します。

タイプ間のフォールバック順

パスが自身のタイプのしきい値を超えられない場合は、諦めるのではなく、下位のタイプにフォールバックしてください。

• 商品パス： 商品のマッチング @0.85 → コレクションのファジーマッチング @0.70 → レビューキュー。カテゴリーのページはホームページより適切な転送先です。誤った商品は、商品が見つからない場合よりも悪いため、弱い商品マッチは無理に採用せず、コレクションにフォールバックします。
• コレクションパス： コレクションのマッチング @0.70 → レビューキュー。

ホームページの / へ黙ってフォールバックしてはいけません。 ホームページへのフォールバックはカバレッジが 100％に見える一方で、その URL に人の確認がまだ必要であることを示す唯一のシグナルを失わせ、リダイレクトのトピック上の価値をゼロに薄めてしまいます。何にもマッチしないパスは、ホームページではなくレビューキューに入れてください。

しきい値では解決できないこと

アルゴリズムから見ると文字列がほぼ同一の、仕様の不一致です。たとえば、12mm の部品のスラッグは 14mm の部品のスラッグと 1 文字しか違わず、S サイズのバリアントは XL サイズとほぼ同じように見えます。ファジーマッチングは自信を持って誤ったものを選んでしまいます。これらはレビューで自動適用対象から手動で除外します。この判断はなくならず、どのようなしきい値でも解消できません。

3 つのバケットに分けた出力

マッチしたパスは、必ず次のいずれか 1 つのバケットに入ります。これにより、パス全体を監査でき、レビューの範囲も明確になります。

1. 自動適用：タイプごとのしきい値をクリアしています。適用前に目視確認しますが、デフォルトでは適用します。
2. レビュー：信頼度の低いマッチ、メディアアセット（.jpg、.mp4、/assets/）、形式が不正な行、キューに回されたすべての項目が含まれます。ここでは人が転送先を設定または確認します。
3. スキップ：最適な転送先がソースパスと一致する場合は何もしません。ソースパスを重複排除し、1 つのリンク切れ URL につきリダイレクトを 1 件だけ作成します。

レビューパスの予算

反復を想定してください。上記の匿名化されたケースでは、フォールバック段階を追加し、レビューキューを処理するにつれて、数回（6 → 725 件のリダイレクト）にわたって作業しました。初回の取り組みでは、少なくとも2～3回のパスを予算に組み込んでください。実行し、分類結果を確認し、しきい値を調整するかターゲットを手動で修正して、再実行します。リダイレクトマップが一度で完成したなら、精度を優先するよう調整し、網羅性を犠牲にしたということです。

ストアへのアクセス

このスキルは、在庫情報を読み取り、Admin API を通じてリダイレクトを書き込みます。どちらか一方の方法を選び、トークンをコミット対象のファイルに書き込まないでください。

方法 A、カスタムアプリのトークン。 Shopify 管理画面で、Settings → Apps and sales channels → Develop apps の順に進み、アプリを作成します。このスキルに必要最小限のスコープ（read_products、read_content、read_online_store_navigation、write_online_store_navigation）を付与してインストールし、Admin API アクセストークンをコピーします。環境変数に保存します。

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # env, not disk

方法 B、Shopify CLI OAuth（トークンの保存不要）。 shopify store auth --store $SHOPIFY_STORE --scopes read_products,read_content,read_online_store_navigation,write_online_store_navigation を実行してから、shopify store execute で検証済みの操作を実行します。

ツールキットの事前確認。 方法 B は Shopify CLI を利用します。まず shopify version を実行し、インストールされていない場合はインストールしてください。Admin GraphQL スキーマ全体を参照し、検証済みの実行を行うには、このスキルと Shopify 公式 AI ツールキットプラグインを組み合わせてください。Claude Code では claude plugin list を確認し、まだない場合は次を実行します。

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

推奨ですが、必須ではありません。方法 A で必要なのは curl とトークンだけです。ツールキットがエージェントに API を提供し、このスキルが手順を提供します。

変更前にプレビューし、破壊的な操作を避ける

• 書き込む前に読み取ります。 まず、最新の在庫情報と既存のリダイレクト一覧を取得します。リダイレクトを作成する前に既存の一覧を照会し、重複をスキップしてください。すでにリダイレクトされているソースパスに対して urlRedirectCreate を実行すると、エラーになります。
• 最初にバックアップします。 大量に書き込む前に、ストアの現在のリダイレクトをエクスポートします（Matrixify エクスポート、または urlRedirects のダンプ）。これにより、作業を元に戻せます。
• ストアフロントではなく、Admin API で検証します。 ストアフロントは CDN にキャッシュされており、最新の状態を正しく反映しないことがあります。書き込みのたびに API でリダイレクトを再照会して確認し、その後、古いパスをいくつか curl -I で抜き取り確認し、301 とマッピング先の location が返ることを確認します。

スクリプトではなくレシピ

references/pipeline.md の GraphQL とマッチングロジックは、コピーして適宜変更するための出発点です。エージェントは現在のスキーマに合わせて、取り組みごとに使い捨てのコードを書き、実行してから破棄します。これにより、Shopify の四半期ごとのスキーマ変更を経ても作業を適切に保ち、気づかないうちに古くなるバイナリを配布せずに済みます。8段階のランブック、マッチングアルゴリズムの仕様、urlRedirectCreate と Matrixify による適用方法、リダイレクト先が404になったケースを検出するロットスイープ（urlRedirectUpdate）、および WordPress URL の変換方法は、すべてここにあります。

参考資料

• references/pipeline.md：GSC の404エクスポート → 在庫情報の取得 → マッチングアルゴリズムの仕様 → 適用 → リダイレクト先が404になったケースのロットスイープ → curl -I による検証までの8段階のランブックと、WordPress パターンの変換方法です。

出典とメンテナンス

最終確認日：2026-07-05。GraphQL は Admin API 2025-07 に固定されています。Shopify は四半期ごとに順次バージョンを非推奨にするため、バージョン固有の情報を信頼する前に、shopify.dev でミューテーション名とクエリ名を確認してください。第三者でも実行できる読み取り専用の再確認方法：

# 1. List existing redirects (confirms scope + shows current map)
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ urlRedirects(first:10){ edges{ node{ path target } } } }"}'

# 2. Probe an old path and confirm it 301s where you expect
curl -sI "https://$SHOPIFY_STORE/old-path" | grep -iE "^(HTTP|location)"

正式なドキュメント：Shopify のURL リダイレクトとAdmin GraphQL API。404 のエクスポート元はGoogle Search Consoleです（Pages → Not found）。これらのスキルには、ドキュメントに記載されていない運用上の知見がまとめられていますが、参考資料の代わりにはなりません。