複数マーケットプレイスのデータパイプライン：地域をまたぐ出品者アカウント管理

Amazonのデータパイプラインを1つのマーケットプレイスから3つへ拡張する作業は、同じコードを3回実行すれば済むものではありません。米国、日本、ドイツのマーケットプレイスには、時差よりも根本的な違いがあります。同じ種類のレポートでも形式が異なり、通貨換算をどの段階で、どのレートを使って行うかを明確に決める必要があります。APIレスポンスとダウンロードファイルの日付表記にも一貫性がなく、統合型か地域別かというアカウント構造によって、どの認証情報でどのデータへアクセスできるかが変わります。

多くのチームは、まず1つのマーケットプレイス向けに構築し、次へ拡張する際に相違点を一つずつ発見します。初期導入が1つだけでも、最初から複数マーケットプレイスを想定して設計する方が効率的です。設定駆動アーキテクチャにするための追加コストは小さく済みます。一方、1つのマーケットプレイス向けに値をハードコードした実装を、他地域にも対応できるよう改修するコストは大きくなります。

マーケットプレイス間の実際の違い

利用できるレポートの違いは、SP-APIのドキュメントから読み取れる以上に大きなものです。すべてのマーケットプレイスで利用できる種類もあれば、北米限定、EU限定、特定の地域別エンドポイント限定のものもあります。例えば、VATの規制対応に関するレポートはEUのマーケットプレイス固有で、北米には相当するものがありません。また、一部のFBA在庫レポートはAmazon.co.jpとAmazon.comで列構成が異なります。同じレポートタイプIDでも、マーケットプレイスのエンドポイントによって異なるスキーマが返されます。

日時の扱いは、気付きにくいバグの原因になり続けます。AmazonのAPIはタイムスタンプをUTCで返しますが、ダウンロードしたレポートの日付列には、明記されないまま現地のタイムゾーンが使われることがよくあります。現地時間を使うレポートでは、日本のマーケットプレイス向けのファイルの日付はJST、ドイツの同じレポートは時期に応じてCETまたはCESTです。一方、V2精算レポートのposted-date-time列などは、UTCであるとドキュメントに明記されています。すべての日付列をUTCとして扱うコードは、日付別集計で1日のずれを生みます。データは一見正しく見えるため、検出が困難です。

運用上、最も影響が大きい違いは通貨です。Amazonは各マーケットプレイスの現地通貨で精算します。米国はUSD、日本はJPY、ドイツはEURです。通貨を明示せずに元の金額を保存するパイプラインは、時間とともに悪化するデータ品質の問題を生みます。発見した時点で、数か月分の修正が必要になることもあります。適切な設計では、すべての金額に通貨コードを付けて保存し、抽出層に換算処理をハードコードするのではなく、分析時に換算します。

設定駆動アーキテクチャ

保守しやすい複数マーケットプレイス向けパイプラインの中心は、各マーケットプレイス固有の設定を一か所に集約する設定層です。抽出コード全体に条件分岐を散在させません。各設定ブロックには、エンドポイント、認証情報への参照、現地のタイムゾーン、通貨コード、対応するレポートの種類、標準スキーマと異なるレポートの形式変更を定義します。

抽出コード自体は、特定のマーケットプレイスに依存しなくなります。対象の設定を読み込み、適切な認証情報を選び、日付フィールドに正しいタイムゾーンを適用し、すべての金額に設定済みの通貨コードを付けます。新しいマーケットプレイスを追加するには、設定ブロックと形式の差異を追加すればよく、抽出ロジックを変更する必要はありません。

この方法には、データモデルが明確になるという副次的な利点もあります。通貨コード、タイムゾーン、レポート形式の差異をコードのコメントではなく設定ファイルに記載すると、個々の例外に対応した開発者だけでなく、パイプラインに関わる全員が確認できます。

マーケットプレイスごとのYAML状態管理

単一マーケットプレイス向けのYAMLによる状態追跡は、複数マーケットプレイスにも自然に拡張できます。ただし、マーケットプレイスごとに状態ファイルを分けるか、1つのファイル内にマーケットプレイス別のセクションを設けるかは、意識して選ぶ必要があります。

状態ファイルはマーケットプレイスごとに分けることを強く推奨します。状態ファイルを巡る競合なしに各パイプラインを独立して実行でき、他に影響を与えずに1つのマーケットプレイスの抽出をリセットしたり再実行したりできます。抽出ファイルをマーケットプレイス別に整理するディレクトリ構成にも自然に対応します。状態ディレクトリにstate/us.yaml、state/jp.yaml、state/de.yamlを置く構成は、セクションを入れ子にした単一ファイルと違い、構造そのものが意味を伝えます。

ファイル名から対象が分かる場合でも、状態ファイルのスキーマにはマーケットプレイス識別子を明記すべきです。この重複があることで、デバッグや監査の際に、どのマーケットプレイスのデータを確認しているかが曖昧になりません。

レジストリベースのレポート定義

対応するすべてのレポートについて、ID、利用可能なマーケットプレイス、想定スキーマ、形式の差異を構造化して定義するレポートレジストリは、複数マーケットプレイス向けパイプラインで最も効果の大きい投資です。これがなければ、どのレポートが存在し、地域ごとに何が異なり、列名が何を意味するかという知識は、構築した開発者の頭の中にとどまります。

レジストリは複数の役割を同時に果たします。Amazonが時折変更したり廃止したりするレポートタイプIDを、一元的に管理できます。マーケットプレイスごとのスキーマの差異を文書化することで、散在する条件分岐ではなくプログラムで違いを処理しやすくなります。検証も可能です。ダウンロードした各ファイルを想定スキーマと照合し、不一致があれば、そのままディスクへ書き込むのではなく調査対象として通知できます。

レジストリは不足状況の分析も容易にします。想定するレポートの一覧と各マーケットプレイスのYAML状態ファイルがあれば、簡単なスクリプトで、欠落、データの古さ、繰り返し発生するエラーをすべてのマーケットプレイスについて一度に特定できます。レジストリがなければ、データ構造を照会するだけでは済まず、抽出コードを理解する必要があります。

規模拡大に伴う運用上の注意点

3つのマーケットプレイスで抽出を並行実行すると、単一の場合にはない実行時刻の問題が生じます。夕方に要求し、翌朝にダウンロードする2段階のワークフローでは、米国、日本、ドイツの「夕方」と「朝」がUTCでは異なる時刻になることを考慮しなければなりません。ドイツに適した単一のスケジュールでは、日本にとって都合の悪い時刻に要求することになり、米国の営業日の境界を外す可能性もあります。

実用的な解決策は、マーケットプレイスごとに現地時刻でスケジュールを組むことです。全世界共通のスケジュールではなく、各パイプラインを現地の営業日に合わせて実行します。運用は複雑になりますが、タイムゾーンに起因する競合状態をなくし、断続的なデータ欠落を防げます。

複数マーケットプレイスでは、レート制限もより重要になります。SP-APIは、出品者とアプリケーションの組み合わせごとに、操作別のレート制限を適用します。また、1つの出品者アカウントで同一リージョン内の複数のマーケットプレイスをカバーできます。3つのマーケットプレイスへ大量のレポート要求を並行送信すると、単一の場合には起きない形で共有枠を使い切る可能性があります。マーケットプレイス単位ではなく出品者・アプリケーション・操作の単位でレート制限を明示的に追跡すれば、原因を特定しにくいスロットリングエラーを防げます。

Amazon Seller Centralのデータ抽出を自動化する：CLIを中心とした手法 — 単一マーケットプレイス向けの基盤：2段階のワークフロー、YAMLによる状態追跡、決定的なファイル命名。
Amazon出品者向けに本番運用可能なデータ基盤を構築する — tva-fetchのアーキテクチャと、70+種類のレポートに対応するSP-API連携パターン。
EC分析における通貨の正規化 — 通貨換算のタイミングと、複数市場の財務データに系統的な誤差を持ち込まない方法。