Skip to main content
ホームブログガイド連携に影響を与えずに配送追跡APIキーを設定およびローテーションする方法

連携に影響を与えずに配送追跡APIキーを設定およびローテーションする方法

17TRACK

配送追跡APIキーを安全に設定・ローテーションするには、認証情報をサーバー側のシークレット管理サービスに保管し、それらを使用するすべてのアプリケーションを特定し、古いキーを無効化する前に新しいキーをテストしてください。プロバイダーが認証情報の併用をサポートしている場合は、利用者を段階的に移行し、検証が完了してから古いキーを失効させます。置き換えによって既存のキーが直ちに無効になる場合は、ダウンタイムがゼロになると想定せず、永続キューと復旧確認を用いた協調的な切り替えを計画してください。

ダウンタイムなしで配送追跡APIキーを設定・ローテーションする方法

このガイドは、ECプラットフォーム、注文管理システム、倉庫ソフトウェア、顧客通知サービスで追跡連携を維持する開発者および運用チームを対象としています。目的は認証済みリクエストを送信することだけではなく、変更の間も配送登録、追跡更新、下流処理を維持することです。

プロバイダーが認証情報をどのように扱うか確認する

本番設定を変更する前に、プロバイダーの認証情報ライフサイクルを確認してください。「再生成」と表示されたダッシュボード操作は、「別のキーを作成」とは異なる動作をする場合があります。ボタンのラベルから動作を推測しないでください。

  • 認証形式:必要なヘッダーまたはその他の認証方式、エンドポイントのバージョン、アカウントとの関連付けを確認します。
  • 併用:2つの認証情報を同時に有効なままにできますか。置き換えを生成すると以前の認証情報は直ちに失効しますか。
  • 権限:キーに個別のスコープ、環境制限、アクセス制御があるか確認します。利用可能な場合はこれらを使用し、存在すると決めつけないでください。
  • 失効:認証情報を無効化する方法と、考慮すべき反映遅延があるかを確認します。
  • 運用上の影響:クォータ、登録済み配送、Webhook設定がアカウント、アプリケーション、個別のキーのいずれに属するかを確認します。

17TRACKとの連携では、まず公式Tracking APIドキュメントとTracking API製品ページを確認してください。ドキュメントで連携に必要な認証契約を確認し、ローテーションを予定する前に、アカウント設定またはサポートを通じて認証情報のライフサイクル動作を確認します。以下の手順は運用ランブックであり、17TRACKが特定のデュアルキー方式や再生成ワークフローを提供しているという主張ではありません。

判断ルール:同時に有効であることが確認された場合にのみ、キーを併用するロールアウトを使用します。それ以外の場合は、ローテーションを認証情報の協調的な置き換えとして扱ってください。プロバイダーがサポートしていない重複期間を、デプロイ戦略で作り出すことはできません。

キーを一度設定し、システム全体に拡散させない

認証をサーバー側に保持する

本番用認証情報は、管理されたシークレットストアまたは同等の管理対象システムに保存します。アプリケーションには、ワークロードID、デプロイプラットフォーム、または承認済みの別の仕組みを通じて取得させます。読み取りアクセスは、必要とするワークロードと運用担当者に限定してください。

キーをブラウザーのJavaScript、モバイルアプリのバンドル、ソースコード、コンテナイメージ、共有設定例に埋め込まないでください。顧客向けの追跡ページはバックエンドを呼び出し、バックエンドが追跡プロバイダーに認証することで、プロバイダーの認証情報を公開しないようにします。

OWASPのSecrets Management Cheat Sheetは、集中管理されたシークレット管理、アクセス制御、監査、ライフサイクル管理を推奨しています。REST Security Cheat Sheetも、ログ記録やその他の処理によって漏えいする可能性があるため、APIキーをURLに含めないよう助言しています。プロバイダーが文書化している認証方式に従い、リクエストログや診断エクスポートから認証値を削除してください。

環境を分離し、デプロイ済みバージョンを特定する

プロバイダーがサポートしている場合は、開発、ステージング、本番で別々の認証情報を使用します。別個の認証情報やアカウントを利用できない場合は、その制約を文書化し、非本番ジョブが制御されていない本番書き込みを実行しないようにします。

シークレットには、SHIPMENT_TRACKING_API_KEYのような論理的な設定参照名を付けます。シークレット管理サービスのバージョンまたは非機密のデプロイラベルは別に記録します。このラベルにより、認証情報自体を調査・ログ出力せずに「このワーカーはどのバージョンを使用しているか」を確認できます。

アプリケーションが更新を受け取る方法を明確に決めます。起動時に環境変数を読み取るプロセスは、変更された値を受け取るために再起動または再デプロイが必要になるのが一般的です。マウントされたシークレットファイルや実行時参照では、更新動作が異なります。シークレットストアを更新しただけでは、実行中のすべてのプロセスが置き換えを適用した証拠にはなりません。

ローテーション前にリクエストを復旧可能にする

追跡処理をプロバイダーに送信する前に永続化します。配送登録では、内部操作ID、配送参照、処理状態、再試行履歴を保持します。この業務ペイロードは認証情報から分離し、キュー内のジョブが実行時に有効な認証情報を使用できるようにします。

APIキーをキューメッセージにシリアライズしないでください。そうすると遅延したジョブが古い認証情報に紐付けられ、シークレットがキューストレージ、デッドレターキュー、デバッグツールに拡散します。

書き込み操作では、再試行を有効にする前にプロバイダーの重複処理ルールを確認します。タイムアウトは登録が失敗した証拠ではありません。接続が中断される前にプロバイダーがリクエストを受け付けていた可能性があります。文書化されたべき等性の仕組みがあれば使用し、なければ再送信前に配送状態を照合してください。

利用者の一覧と監視のベースラインを作成する

最も見落とされやすい利用者は、メインアプリケーションではないことがよくあります。スケジュールされたインポート、キューワーカー、サーバーレス関数、管理スクリプト、サポートツール、災害復旧用デプロイ、現在スケールゼロになっているサービスを一覧化します。

各利用者について、所有者、環境、シークレット参照、更新方法、実行スケジュール、デプロイ方法を記録します。認証情報をメモリに保持する可能性がある長時間実行ジョブも特定します。また、設定変更後も古い認証ヘッダーを保持する可能性がある再利用可能なHTTPクライアントを確認します。

切り替え前に、次のベースラインを確立します。

  • サービス、環境、エンドポイント、デプロイバージョン別に分類した認証失敗。
  • プロバイダーの応答遅延、タイムアウト、レート制限応答、サーバーエラー。
  • キューの深さ、最も古い保留ジョブの経過時間、デッドレター量。
  • 成功した配送登録と未解決の登録試行。
  • Webhookが連携の一部である場合の、Webhook受信および処理の健全性。

連携の健全性と配送の進行を分けて考えます。新しい配送業者イベントがない荷物は、必ずしもAPI障害の証拠ではありません。ローテーション中は、配送ステータスが変化した荷物の数よりも、認証済みリクエストの成功と処理キューの健全性の方が直接的な指標です。

サポートされている場合はキーを併用してローテーションする

  1. 有効なキーを失効させずに置き換えを作成する。古い認証情報が引き続き有効であることを確認します。新しい認証情報を別のシークレットバージョンとして保存し、適切にアクセスを制限します。
  2. 置き換えを分離して検証する。対象環境に対して、文書化された影響の小さい操作を実行します。HTTP結果と、レスポンス本文に含まれるアプリケーションレベルの結果の両方を確認します。
  3. 代表的なワークフローをテストする。単なる接続確認ではなく、アプリケーションが実際に必要とする操作を検証します。登録が必要な場合は、承認済みのテスト配送を使用し、クォータや課金への影響を考慮します。
  4. 小規模な利用者グループにデプロイする。1つのワーカーグループまたはアプリケーションインスタンスを置き換えに移行し、認証、処理結果、キューの動作を確認します。
  5. 残りすべての利用者に展開する。各サービスが再読み込みまたは再起動するたびに一覧を更新します。スケジュールタスク、休止中のワークロード、復旧設定も含めます。
  6. 適切な検証期間にわたって監視する。関連するワーカーの稼働時間、設定キャッシュの動作、再試行遅延、ジョブスケジュールを対象にします。適用を証明できる普遍的な待機時間はありません。
  7. 古いキーを失効させ、再度検証する。古い利用者を監視し、保持要件とインシデント対応要件に従って古いシークレット参照を廃止します。

プロバイダー側のキー使用状況レポートを利用できない場合は、デプロイ記録とアプリケーションが報告するシークレットバージョンラベルを使用して適用を確認します。これは運用上の証拠になりますが、完全な利用者一覧の代わりにはなりません。

即時置き換えを協調的な切り替えとして扱う

置き換えの発行によって古いキーが直ちに無効になる場合、ローリングデプロイで中断のない認証を保証することはできません。処理が失われるのではなく安全に遅延するよう、移行を設計してください。

  1. 認証情報を置き換える前に、アプリケーションのデプロイ、シークレット参照、運用担当者のアクセス、復旧コマンドを準備します。
  2. 制御された境界で外向きの追跡リクエストを一時停止し、実行可能な場合は永続ストレージへの処理受付を継続します。
  3. 実行中のリクエストを排出または記録します。あいまいな書き込み結果は失敗として自動処理せず、照合対象としてマークします。
  4. プロバイダーの認証情報を置き換え、シークレットストアを更新し、すべての利用者を更新します。
  5. 保留中の全処理を解放する前に、認証とワークフローの確認を実行します。
  6. プロバイダーのレート制限を守り、重複登録を確認しながら、処理を段階的に再開します。

連携を一時停止できず、処理を保持できず、または予測可能な方法で認証情報を更新できない場合は、定期的なローテーションの前にその弱点を修正してください。ただし、漏えいが疑われる場合は、一時的な中断が発生しても直ちに失効させて封じ込める必要があります。

API認証をWebhookセキュリティから分離する

外向きAPIキーと受信Webhook検証シークレットは、異なる目的で使用されます。一方をローテーションするともう一方も変わる、または両方が同じ値を使用すると想定しないでください。プロバイダーが文書化しているWebhook認証と配信動作に個別に従います。

外向き認証情報の切り替え中も、別の停止理由がない限りWebhook受信を継続します。プロバイダーの仕様に従って受信メッセージを検証し、アーキテクチャ上可能であれば確認応答の前に永続的に受け付け、重複配信に耐えられるよう処理します。

認証済みAPI呼び出しの成功は、Webhookの配信や処理が健全であることを証明しません。2つの経路を別々に確認し、プロバイダーの設計上必要でない限り、同じメンテナンス作業で両方の認証情報を変更しないでください。

リトライストームを発生させずに障害を解決する

症状最初に確認する項目安全な対応
デプロイ後の認証失敗シークレットバージョン、ヘッダー形式、環境、空白、キャッシュされたクライアント盲目的な再試行を停止し、設定を修正して1件のリクエストを検証する。
一部のワーカーだけが失敗する古いプロセス、未適用のデプロイ、遅延ジョブ、古いシークレットキャッシュ影響を受けた利用者を更新し、バージョンラベルを比較する。
復旧中のレート制限バックログの解放速度と合計同時実行数復旧を抑制し、文書化された再試行ガイダンスに従う。
登録がタイムアウトするプロバイダーがすでに処理を受け付けたかどうか再実行前に照合するか、文書化されたべき等性を使用する。

HTTP 401は通常、認証の欠落または無効性に関係し、403はサーバーがリクエストを拒否したことを意味します。プロバイダー固有のレスポンス本文が原因をより正確に説明する場合があります。すべての403を期限切れキーとして分類したり、失敗したすべての操作がHTTPエラーステータスを使用すると想定したりしないでください。

適切な一時的障害には、上限付きのバックオフとジッターを伴う再試行を使用します。無効な認証情報を繰り返し送信しても修復されません。運用担当者に通知し、処理を保持し、設定エラーが制御不能なリクエストストームにならないようにします。

変更前にロールバックと完了条件を定義する

キーを併用するローテーションでは、ロールバックとは、古い認証情報がまだ有効で信頼できる間、一時的に利用者を古い認証情報へ戻すことを意味します。失効後はこの選択肢はありません。古いキーが侵害された可能性がある場合は、可用性を回復するためだけに復元せず、別の認証情報を発行して前進してください。

一覧化したすべての利用者が置き換えを使用し、認証エラーが通常のベースラインに戻り、キュー内の処理が回復し、あいまいな書き込みが照合され、Webhook処理が健全な場合にのみローテーションを完了します。キーの値を記録せず、所有者、完了時刻、デプロイ済みシークレットバージョン、失効結果を記録します。

継続的なAPIセキュリティのため、組織のポリシー、認証情報の漏えいリスク、プロバイダーの機能に基づいてローテーションスケジュールを選択します。漏えいや不適切なアクセスが疑われる場合は、スケジュール外でもローテーションします。連携が安全にサポートできない任意の頻度よりも、再現可能でテスト済みの手順の方が有用です。

FAQ

ダウンタイムなしで追跡APIキーをローテーションできますか。

プロバイダーが認証情報の同時利用をサポートし、失効前にすべての利用者を移行できる場合は可能です。再生成によって古いキーが直ちに無効になる場合は、外向きリクエストを制御された状態で中断する計画を立ててください。永続キューはその間の処理を保持できますが、プロバイダー接続を継続的に利用可能にするものではありません。

キューに入った配送ジョブにAPIキーを含めるべきですか。

いいえ。配送処理とその処理メタデータを保存し、ワーカー実行時に有効な認証情報を解決します。これによりシークレットの漏えいを減らし、遅延したジョブが無効化されたキーを繰り返し使用することを防げます。

キーをローテーションすると登録済み配送は削除されますか。

どちらの結果も想定しないでください。登録済み配送と関連設定がアカウント、アプリケーション、認証情報のいずれに紐付くかを確認します。認証に成功しただけでは、置き換え後の認証情報が期待される配送記録にアクセスできることは証明されません。

リポジトリやログにキーが表示された場合はどうすべきですか。

侵害された可能性があるものとして扱います。速やかに失効または置き換えを行い、利用可能な場合はアクセス記録と使用記録を調査し、インシデント対応プロセスに従います。表示された値を削除するだけでは不十分です。履歴、ログエクスポート、その他のシステムにコピーが残っている可能性があります。

古いスケジュールジョブが以前のキーを使用しているかどうかを確認するにはどうすればよいですか。

シークレット参照、デプロイ済み設定、実行時の更新動作を確認します。安全な場合は制御された実行を行うか、次回のスケジュール開始前にデプロイを検証します。ダッシュボードが静かな状態でも、使用頻度の低い利用者が移行済みであるとは限りません。

参考資料