リンクを壊さずに Bitly から移行する：障害モードのプレイブック

Ana Kowalska は Elido のソリューションエンジニアで、Bitly のカットオーバーを通じて数十の移行プロジェクトを支援してきました。彼女は、移行後ではなく移行前に監査を行えば、ほとんどの苦労は回避できると考えています。

migrate-from-bitly-playbook では戦略的なアークを説明しています：何があるかを監査し、エクスポートし、インポートし、DNS を切り替える。Bitly の移行を一度もやったことがなければ、そちらが最初に読む適切な場所です。

この投稿は異なります。実際に壊れるもの - 概念的な計画が完成して本番データに対して実際に移行を実行しているときに出てくる具体的な障害モード - に焦点を当てています。7つが繰り返し発生し、7つすべてが知っていれば防げます。

TL;DR#

Bitly のスラッグは大文字小文字を区別します。多くのリダイレクトプラットフォームはそうではありません。bit.ly/AbCd と bit.ly/abcd は Bitly では異なるリンクであり、移行スクリプトがインポート時にスラッグを小文字に変換すると、異なる動作をします。
DNS TTL のギャップにより、CNAME を切り替えた後でもリダイレクトのギャップが発生します。5分前ではなく、カットオーバーの少なくとも24時間前に TTL を60秒に下げてください。
api-ssl.bitly.com エンドポイントを指すウェブフックは、Bitly アカウントをキャンセルまたは非アクティブ化した瞬間に発火を停止します。アカウントのステータスに触れる前に、すべてのダウンストリームコンシューマーを再配線してください。
パスセグメントを持つディープリンク（bit.ly/app/account/settings）は、パスプレフィックスでもマッチする Elido のルーティングルールと衝突します。ディープリンクスラッグを標準のリダイレクトスラッグとは別に監査してください。

実際に壊れる7つのこと#

ツールの議論の前に、障害の分類を把握しておくことが役立ちます。ほとんどの移行のポストモーテムはこれらのいずれかを指しています：

1. スラッグの大文字小文字の区別。 Bitly はスラッグの大文字小文字を保持します - bit.ly/SummerSale と bit.ly/summersale は別々のリンクです。インポートスクリプトがスラッグを小文字に正規化すると（URL 処理ライブラリでは一般的なデフォルト）、間違ったスラッグを暗黙的に作成し、大文字バリアントが 404 になります。これは混合ケースのスラッグが埋め込まれたメールキャンペーンに影響します。

2. 末尾スラッシュの動作。 bit.ly/campaign/ と bit.ly/campaign は Bitly のルーターでは同じリンクとして処理されます。プラットフォームによっては末尾スラッシュバリアントを別のパスとして扱います。Elido ワークスペースが厳格な URL 正規化が有効なリバースプロキシの前にある場合、末尾スラッシュリクエストは正規スラッグとは異なる解決をする可能性があります。

3. クエリ文字列の保持。 Bitly のリンク先 URL にすでにクエリパラメーターが含まれている場合 - https://acme.example/landing?source=bitly - そしてクリックが共有時に追加された UTM パラメーターも持っている場合、宛先のマージが Elido でも同じ動作をすることを確認する必要があります。追加された UTM に対する Bitly のデフォルト動作は、既存のクエリ文字列にマージすることです。宛先 URL にすでにパラメーターが含まれているリンクについては、これを明示的にテストしてください。

4. プラットフォームレベルでの UTM 追加。 Bitly のエンタープライズプランはワークスペースレベルの UTM 追加をサポートしています：元の宛先 URL に何が含まれていても、すべての送信リダイレクトに UTM が追加されます。Bitly でこれを有効にしていて文書化していなかった場合、Elido がまだ追加していない UTM に依存している analytics がある可能性があります。エクスポートする前に Bitly のワークスペース設定で自動追加ルールを確認してください。Elido の同等機能はワークスペースまたはキャンペーンレベルの UTM テンプレートです - その設定の場所はカスタムドメイン機能ページで説明されています。

5. DNS TTL のギャップ。 これはカットオーバー時のリダイレクトギャップの最も一般的な原因です。DNS リゾルバーは現在の TTL の期間、古い CNAME をキャッシュします。TTL が2年間86400秒に設定されていた場合、A レコードを切り替える5分前に300秒に変更することは、ほとんどのリゾルバーがあと23時間55分古いレコードを保持することを意味します。カットオーバーは即時ではありません。伝播します。

6. ウェブフックの再配線。 Bitly のウェブフックイベントを消費しているシステム - analytics パイプライン、CRM エンリッチメントジョブ、Shopify 注文アトリビューション - はすべて Bitly のエンドポイント URL に対して発火します。そのエンドポイントは、ウェブフックをサポートするプランを下回るプランに Bitly アカウントをキャンセルまたはダウングレードした瞬間に暗くなります。Bitly のウェブフック設定はアカウントレベルにあり、リンクデータと一緒にエクスポートされません。すべてのコンシューマーを手動でインベントリし、再設定する必要があります。

7. ディープリンクパスの衝突。 モバイルディープリンクはしばしばショート URL パスを使用してアプリのナビゲーション状態をエンコードします - bit.ly/app/profile/edit は yourapp://profile/edit のような宛先にマップするかもしれません。これらのスラッグを Elido に移行すると、スラッグ app/profile/edit にスラッシュが含まれます。Elido のルーターは Bitly の不透明なスラッグ処理とは異なり、スラッシュ区切りのパスを扱う可能性があります。パスセグメントを持つディープリンクスラッグが、ネストされたパスとして再解釈されるのではなく、正確なスラッグ文字列で作成されていることを確認してください。

移行前の監査：リスク層ごとのセグメント分け#

Bitly API（2026-05-12参照）は GET /v4/bitlink/{bitlink}/clicks/summary でリンクごとのクリック数を公開しています。エクスポートとインポートの前に、これを使ってインベントリをセグメント分けしてください。

実際のセグメント分け：

壊してはいけないプラン（上位1%）： 直近30日間のクリック数の中央値の10倍以上のリンク。メール、印刷物、有料広告のランディングページでライブです。カットオーバー後に自動チェックだけでなく手動確認が必要です。
監視プラン（次の9%）： 中央値以上のクリックボリュームを持つリンク。自動の 301 確認で十分ですが、予期せず解決するものにフラグを立ててください。
バルクプラン（残りの90%）： 低トラフィックまたはゼロトラフィックのスラッグ。プログラムで確認します。小さなエラー率を受け入れ、レポートで修正します。

インベントリステップでリンクごとの30日間のクリックサマリーをエクスポートしてください。Bitly API リファレンス（2026-05-12参照）に対する簡単なページネーションループでこのデータが得られます。グループビットリンクエンドポイントの link_clicks フィールドはライフタイムカウンターで粗いですが、トリアージには十分です：

# Bitly グループのすべてのリンクをページネーションして JSONL に書き込む
NEXT_URL="https://api-ssl.bitly.com/v4/groups/${GROUP_GUID}/bitlinks?size=100"
while [ -n "$NEXT_URL" ]; do
  RESP=$(curl -s -H "Authorization: Bearer ${BITLY_TOKEN}" "$NEXT_URL")
  echo "$RESP" | jq -c '.links[]' >> bitly-links.jsonl
  NEXT_URL=$(echo "$RESP" | jq -r '.pagination.next // empty')
done

link_clicks の降順で出力を並び替えてください。上位1%が壊してはいけないプランです。バルクインポートを実行する前に、そのスラッグを別のファイルにエクスポートしてください。

スラッグの保存：重要なインポート呼び出し#

POST /v1/links/bulk の Elido バルクインポートエンドポイントはリンクごとに slug フィールドを受け入れます。明示的に設定しないと、Elido は新しいランダムスラッグを生成します - 移行には間違った動作です。常にソーススラッグを渡してください。

# スラッグ保存付きのバルクインポート - 1回の呼び出しで100リンク
curl -s -X POST "https://api.elido.app/v1/links/bulk" \
  -H "Authorization: Bearer ${ELIDO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mig-batch-$(date +%s)" \
  -d '{
    "workspace_id": "'"${WORKSPACE_ID}"'",
    "domain_id": "'"${DOMAIN_ID}"'",
    "links": [
      {
        "slug": "SummerSale",
        "destination_url": "https://acme.example/summer",
        "tags": ["bitly-migrated", "campaign-summer"]
      },
      {
        "slug": "AbCd",
        "destination_url": "https://acme.example/landing",
        "tags": ["bitly-migrated"]
      }
    ]
  }'

この呼び出しで注目すべき2点。まず、スラッグの値は "SummerSale" と "AbCd" です - Bitly での表示とまったく同じ混合ケースで保持されています。小文字にしないでください。次に、Idempotency-Key ヘッダーは部分的なバッチを安全に再実行できることを意味します。Elido は重複を作成する代わりに既存のリンクを返します。これは再開が必要な可能性のある移行の正しいパターンです。

壊してはいけないプランについては、バッチではなく対話形式でリンクごとにインポートを実行し、進む前にそれぞれを確認してください。バルクプランについては、1回の呼び出しで100ずつバッチし、レスポンスのエラー配列を処理して、競合または失敗したスラッグを検出してください。

ギャップのない DNS カットオーバー#

DNS カットオーバーはライブトラフィックが移動する瞬間です。正しく行えば、ユーザーは中断を経験しません。古い TTL で行うと、分単位ではなく時間単位のギャップが発生します。

シーケンスが重要です。以下のタイムライン図を参照してください。

T-7日に TTL を60秒に下げ、T-0に A レコードを切り替え、T+5分に95%伝播、T+1時間に TTL を復元、T+24時間に監査パスを示す水平 DNS カットオーバータイムライン

詳細なタイムライン：

T−7日： CNAME または A レコードの TTL を60秒に下げます。これはほとんどのチームが見逃す重要なステップです。RFC 1034 §3.6（IETF datatrackerのリソースレコードキャッシュに関するセクション）は、TTL をリゾルバーがレコードを保持できる最大キャッシュ期間として定義しています。現在の TTL が86400（1日）の場合、変更は現在キャッシュされているバージョンが期限切れになった後にのみ有効になります。カットオーバーの少なくとも1つの完全な現在 TTL 期間前に TTL を下げる必要があります。1週間が安全です。24時間が最小限です。

T−1時間： 低い TTL が伝播したことを確認します。少なくとも3つの異なるリゾルバーエンドポイントから dig @8.8.8.8 links.yourbrand.com +ttl のようなツールを使用してください。報告された TTL は60秒に近いはずです。

T−0： CNAME ターゲットを Bitly のエッジから Elido のエッジに切り替えます。Elido 側では、ドメインはすでにワークスペースに登録および確認されているはずです - Elido のエッジがトラフィックを受け入れる準備ができる前に DNS を切り替えないでください。伝播後の最初のリクエストが自動オンデマンド TLS 証明書発行をトリガーし、その1回のリクエストで約2〜3秒で完了します。以降のリクエストはキャッシュにヒットし、EU リージョンのエッジで一桁ミリ秒で解決されます。

T+5分： 2番目のネットワークからスポットチェックを実行します（オフィスのリゾルバーキャッシュをバイパスするためにモバイルホットスポットを使用）。curl -sI https://links.yourbrand.com/any-known-slug は Elido のエッジヘッダーから提供された、期待される宛先を指す 301 Moved Permanently を返すはずです。

T+1時間： TTL を通常の運用値（300または3600秒）に戻します。TTL を60秒に維持し続けると DNS プロバイダーとリゾルバーインフラへの負荷が増加します。

T+24時間： 完全なスラッグ監査を実行します（次のセクション参照）。

RFC 7231 §6.4.2によると、301 Moved Permanently レスポンスは、明示的な cache-control ヘッダーがオーバーライドしない限り、中間者によって無期限にキャッシュされる可能性があります。これは、TTL ギャップ中に古い Bitly 宛先にヒットしたクライアントが Bitly のインフラを指す 301 をキャッシュした可能性があることを意味します。これらのキャッシュされたリダイレクトは Bitly のインフラがライブである限り正しく解決されます。そのため30日間の Bitly アカウントの重複ウィンドウが重要です。

301 チェーン監査：スクリプト化された夜間確認#

カットオーバー後、壊してはいけないプランに対して夜間の確認ループを実行します。目的は、動作が変わったスラッグを検出することです - 予期しない宛先を返すもの、404 を返すもの、または2ホップを超えるリダイレクトチェーンになったもの。

# 上位スラッグが Elido を通じて正しく解決することを確認する
# top-slugs.txt: 1行1スラッグ、プロトコルプレフィックスなし
DOMAIN="links.yourbrand.com"
FAIL=0

while IFS= read -r slug; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    --max-redirs 0 \
    "https://${DOMAIN}/${slug}")
  LOCATION=$(curl -s -I --max-redirs 0 \
    "https://${DOMAIN}/${slug}" \
    | grep -i '^location:' | tr -d '\r' | cut -d' ' -f2)

  if [ "$STATUS" != "301" ]; then
    echo "FAIL [$STATUS] $slug → expected 301"
    FAIL=$((FAIL + 1))
  else
    echo "OK  [301] $slug → $LOCATION"
  fi
done < top-slugs.txt

echo "---"
echo "Failures: $FAIL"
exit $FAIL

カットオーバー後の最初の2週間、毎晩壊してはいけないプラン（ほとんどのチームで通常50〜200スラッグ）に対してこれを実行してください。出力をアラートチャンネルにパイプします。FAIL がゼロ以外の場合、朝のトラフィックピーク前に人間が確認する必要があります。

--max-redirs 0 フラグは意図的です：最終宛先ではなく Elido のリダイレクトを確認したいためです。Status が 301 ではなく 200 の場合、Elido 側の何かがリダイレクトするのではなく直接宛先を提供しています。これは、スラッグが直接パススルーとして設定されたリンクに解決したことを意味します。調査する価値があります。

監視プランには軽い週次スキャンを実行します。バルクプランには、ダウンストリームシステムからのエラーレポートに依存します - メール内のリンク切れはバウンス率の変化を生成し、メールプラットフォームがそれを表示します。

ウェブフックの再配線#

Bitly のウェブフックはBitly API リファレンス（2026-05-12参照）のウェブフックセクションに文書化されています。各ウェブフックはクリックイベントで発火し、ビットリンク、リファラー、ユーザーエージェントフィールドを含みます。一般的なコンシューマー：

Shopify： どのショートリンクがコンバージョンをもたらしたかを追跡するアトリビューションアプリ。Bitly のウェブフック検証を呼び出すサードパーティエンドポイントを指す Shopify アプリの管理パネルで設定。
Stripe： 一部の請求アトリビューションパイプラインが、Bitly ウェブフック経由で取得した元のショートリンクの UTM データで受信したトライアルサインアップにタグを付ける。
Slack： クリックサマリーを #marketing チャンネルに投稿するリンクパフォーマンスボット。
カスタム ETL パイプライン： エンリッチメントやアトリビューション結合のために Bitly クリックイベントを取り込むデータウェアハウスパイプライン。

ウェブフックの移行チェックリスト：

アカウントを変更する前に Bitly のウェブフック設定をエクスポートする。Bitly API の GET /v4/workspaces/{workspace_guid}/webhooks がリストを返す。ファイルに保存する。
各コンシューマーについて、Bitly イベントを受信しているエンドポイント URL と HMAC 検証に使用されているシークレットを識別する。
同等の Elido ウェブフックエンドポイントを設定する。Elido のウェブフックペイロードは Bitly のものとは異なるスキーマを持っています - フィールドは似ていますが同一ではありません。新しいスキーマを受け入れるようにコンシューマーのハンドラーを調整する。
重複ウィンドウ中は両方のウェブフックを並行して実行する。カットオーバー日からウェブフックを発火するよう Elido を設定しながら、Bitly ウェブフックをアクティブに保つ。コンシューマーは重複ウィンドウ中に1回のクリックに対して2つのイベントを受け取ります - ショート URL + タイムスタンプで重複排除するか、重複ウィンドウ中のダブルカウントを既知の成果物として受け入れる。
Elido ウェブフック配信の72時間の確認後、各コンシューマーから Bitly ウェブフック設定を削除する。

シークレットローテーションの猶予ウィンドウは重複期間です。すべてのコンシューマーが確認されるまで Elido ウェブフックシークレットをローテーションしないでください。1つのコンシューマーが更新される前にシークレットをローテーションすると、そのコンシューマーはエラーなしでサイレントにイベントをドロップします - HMAC チェックが失敗し、ほとんどのウェブフックハンドラーは無効な署名ペイロードをアラートなしで破棄します。

ロールバック計画：Bitly を30日間生かし続ける#

ロールバック手順はシンプルです：DNS CNAME を Bitly のターゲットに戻します。TTL のドロップを事前にステージングして DNS レコードがまだ60秒にある（復元するまで）ため、DNS の巻き戻しは2分以内に伝播します。

開始前にロールバックコマンドをステージングしてください：

# ロールバックスクリプト - DNS を Bitly に戻すために実行する（DNS プロバイダーに合わせて調整）
# AWS CLI を使用した Route 53 の例
aws route53 change-resource-record-sets \
  --hosted-zone-id "${HOSTED_ZONE_ID}" \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "links.yourbrand.com",
        "Type": "CNAME",
        "TTL": 60,
        "ResourceRecords": [{"Value": "cname.bitly.com"}]
      }
    }]
  }'

カットオーバー前にこれをラップトップ上のファイルと共有ランブックの場所に保存してください。アクティブなインシデント中にインフラコマンドを書く最悪の瞬間は対処中です。

カットオーバー後30日間、Bitly アカウントをリンク解決を維持する有料プランでアクティブに保ってください。migrate-from-bitly-playbookは90日間を推奨しています。30日はコストを管理する必要があるチームにとって実際的な最小値です。30日間のウィンドウ中、まだ Bitly を通じて解決するトラフィック（キャッシュされたリダイレクト、印刷物の古い bit.ly リンク）は引き続き機能します。30日後、analytics で残存する Bitly トラフィックを評価し、延長するかどうかを決定します。

30日間のウィンドウ中に監視すること：

カスタムドメインの Elido のエラーレート（アクセスログの予期しない 404 を監視）。
Bitly へのトラフィックのスパイク（Bitly ダッシュボードがトラフィックを表示します。スパイクは、高ボリュームスラッグのキャッシュされたリダイレクトがまだ Bitly を通じて解決していることを意味する可能性があります）。
再配線したコンシューマーのウェブフックコンシューマーエラーレート。

移行後監査：記録すべきもの#

30日間のウィンドウ後、最終監査パスを実行します。監査ログに属するもの：

チェック	方法	合格基準
スラッグ数の一致	`wc -l bitly-export.jsonl` vs Elido API のカウント	1%以内（意図的に削除されたアーカイブリンクを考慮）
壊してはいけないプランの 301 チェック	夜間監査スクリプト	7日連続でゼロ失敗
クリックボリューム照合	Elido の30日間クリック合計と昨年同期間の Bitly の30日間合計を比較	期待される季節変動内
ウェブフックコンシューマーの確認	各コンシューマーが Elido イベントを受信して正しく処理していることを確認	7日間サイレントドロップなし
DNS TTL の復元	`dig +ttl links.yourbrand.com`	運用値での TTL（300秒以上）

これをチームの監査テーブルに記録してください。ワークスペースが Business または Enterprise プランの場合、Elido の監査ログはインポート中のすべての API 操作を記録し、API 経由で照会できます。インポートバッチレコードを引き出し、このテーブルと共にスナップショットを保存してください。

よくある落とし穴：現場からの3つのパターン#

メールアトリビューションを1週間失った DACH の ecommerce ブランド。 ドイツの小売業者が送信時に購読者ごとの UTM を追加した Bitly スラッグを使ったニュースレターキャンペーンを実行していました。移行スクリプトは Elido にインポートする前にすべてのスラッグを小文字に正規化しました。カットオーバー後、メールプラットフォームは元の混合ケーススラッグを持つリンクを生成していました。スラッグのケースが一致しなかったため、それらのリンクは Elido から 404 を返しました。修正はケースが保存されたスラッグでインポートを再実行することでしたが、その時には7日間のメールトラフィックが 404 に落ちていました。そのコホートのアトリビューションは回復不能でした。教訓：移行が完了したと宣言する前に、各アクティブチャンネルから1つのライブリンクをテストしてください。

モバイルユーザーを三重リダイレクトした SaaS スタートアップ。 グロースチームが Cloudflare のプロキシ（オレンジ雲）モードで前置された Bitly カスタムドメインを持っていました。カットオーバー後、モバイルユーザーは3つのリダイレクトを受けていました：Cloudflare → Elido エッジ → 宛先。余分なホップは、Elido に引き渡す前に HTTP を HTTPS に書き換え、その後 Elido が自身の 301 を発行した Cloudflare ページルールから来ていました。iOS Safari は Cloudflare の中間リダイレクトを30日間の永続リダイレクトとしてキャッシュしました。修正は Cloudflare レコードをグレー雲（DNS のみ）に設定し、競合するページルールを削除することでした。Safari のキャッシュされたリダイレクトは自然に期限切れになるのに30日かかりました。カットオーバー後ではなく前に CDN プロキシモードを確認してください。

Bitly グループを見逃したエージェンシー。 エージェンシーが単一の Bitly アカウント下で3つのクライアントブランドを管理し、それぞれが独自のカスタムドメイン設定を持つ異なる Bitly グループ下にありました。移行スクリプトはデフォルトグループ - API ユーザーのトークンが作成されたグループ - のみを照会しました。2つのクライアントドメインはきれいに移行されました。3番目のドメインはサブグループ下にあり、エクスポートされませんでした。カットオーバー後、製品ローンチのメールキャンペーンが未移行のカスタムドメインを指した状態で送信されました。ドメインはまだ Bitly の CNAME を完全な TTL で持っており、Bitly はリンクを正しく提供していましたが、そのドメインのカットオーバーウィンドウは完了したと宣言されていました。その慌ただしさは締め切り下での完全な再移行でした。教訓：エクスポートステップを開始する前に GET /v4/user/groups ですべてのグループを列挙してください。トークンがすべてのグループへのアクセス権を持っていることを確認してください。

次のステップ#

migrate-from-bitly-playbookは、移行計画を最初から始めるチームのための完全な戦略的シーケンスを説明しています。この投稿はその障害モードのコンパニオンです - 一緒に使ってください。

移行先の製品側については、solutions/marketersページで、ほとんどの移行プロジェクトがアクセスしようとしているアトリビューションとキャンペーントラッキング機能を説明しています。切り替えが価値があることをまだ確認している場合は、/compare/vs-bitlyページが機能パリティのリファレンスです。

Rebrandly や Short.io と並べて Elido を評価している場合、elido-vs-bitly 比較では4つのトラフィックボリュームでの価格と機能のトレードオフを説明しています。カスタムドメイン機能ページでは DNS 確認と TLS プロビジョニングのメカニズムを詳しく文書化しています - DNS カットオーバーウィンドウの前に読む価値があります。

移行の失敗はほぼ常に回避可能です。監査スクリプト、TTL の規律、ウェブフックインベントリにカットオーバー前2時間の作業がかかります。その後のインシデント対応の数日間を節約できます。

引用と情報源

Bitly API Reference - dev.bitly.com/api-reference、2026-05-12参照
RFC 1034 - Domain Names: Concepts and Facilities, §3.6（リソースレコードキャッシュ）- datatracker.ietf.org/doc/html/rfc1034
RFC 7231 §6.4.2 - HTTP/1.1 Semantics and Content: 301 Moved Permanently - datatracker.ietf.org/doc/html/rfc7231#section-6.4.2
Bitly API - Groups and Bitlinks endpoints - dev.bitly.com/api-reference、2026-05-12参照

Elidoを試す

URLを貼り付けて短縮リンクを取得

登録不要。リンクは30日間有効。永久に保存するには登録してください。

Free、登録不要 · 1日あたり2件