Amazon Seller Centralのデータ抽出を自動化する：CLIを中心にしたアプローチ

Amazon Seller Centralでは、多くのデータをSP-APIで取得できます。一方、量は少なくても運用上重要な一部のデータは、Seller Centralの画面からしか取得できません。ブラウザーでレポートをリクエストし、生成を待ち、別途ダウンロードする必要があります。これを安定して自動化するには、見た目以上の細かな対応が必要で、デモでは動く仕組みの多くが、本番環境では数日以内に機能しなくなります。

主な課題は技術そのものではありません。ブラウザー自動化は成熟しており、レポートのエンドポイントも文書化され、データ形式も十分に理解されています。問題は運用です。Amazonの画面は予告なく変わり、レート制限は厳しく、取得できるレポートはマーケットプレイスやアカウントの種類によって異なります。また、ブラウザー自動化が依存するセッション状態は劣化し、パイプラインが何の通知もなくデータを出力しなくなるまで、異常を検知しにくいことがあります。

APIとブラウザー：実際のトレードオフ

SP-APIは、注文、在庫、精算、FBAのフルフィルメント、カタログの実績など、業務データとして重要なレポートの大半に対応しています。これらにはAPIだけを使う方法が明らかに適しています。高速で信頼性が高く、画面変更の影響も受けません。SP-API認証を適切に実装するための投資は、LWA認証情報、トークンの更新、リクエストの送信頻度制御を含め、短期間で回収できます。

ただし、SP-APIではまったく取得できない種類のレポートもあります。Advertising APIの提供範囲を超える広告レポート、一部のコンプライアンス関連書類、いくつかの財務サマリー形式には、ブラウザー操作が必要です。ブラウザー自動化は、こうしたケースに限り、運用コストを十分に理解したうえで、慎重に採用すべきです。

取得頻度の低いレポートなら、必要なときに手動で書き出す方法も、決して不合理ではありません。判断すべきなのは、想定する運用期間において、ブラウザーセッションの維持、ログイン処理、CAPTCHAやMFAへの対応といった自動化の負荷が、手作業の負荷を本当に下回るかどうかです。毎日の業務データでは自動化が明らかに有利です。月次のコンプライアンスレポートでは、判断はそれほど単純ではありません。

基盤となる決定論的なファイル命名

データ抽出パイプラインで最も影響の大きい設計判断は、抽出方法ではなく、取得したファイルの命名と保存方法です。タイムスタンプや連番を使うと、時間とともに運用上の問題が積み重なります。レポートが想定した期間を網羅しているか一目で分からず、重複排除が不確実になり、命名規則を変えるたびに特定のファイルへ依存する下流処理も更新しなければなりません。

決定論的な命名規則では、レポートの種類、マーケットプレイス識別子、対象期間、重複排除用のコンテンツハッシュという主要な属性を、ファイル名に直接含めます。EUマーケットプレイスの特定期間の精算レポートは、いつリクエストしてダウンロードしても同じファイル名になるべきです。このファイルシステム上の冪等性により、ある種のパイプライン障害をまとめて防ぎ、データディレクトリ自体から内容を把握できるようになります。

実装では、ファイルを書き込む前に、各レポートの主要属性を統一した形式で表す必要があります。多くのレポートでは簡単ですが、Amazonが必要なメタデータをすべてファイル内に含めていない場合は複雑になります。その場合、命名に使うメタデータをリクエスト時の情報から導出するため、ダウンロードまでその情報を追跡する必要があります。

YAMLによる状態管理

無人で動くデータ抽出CLIには、永続的な状態管理が必要です。どのレポートをリクエストし、何が処理待ちで、何を正常にダウンロードし、何がどのエラーで失敗したかを記録します。データベースによる管理は自然な選択ですが、依存先が増えてデプロイが複雑になり、問題の規模に見合わない運用負荷が生じます。

レポートの種類ごと、複数マーケットプレイスならマーケットプレイスごとにYAMLファイルを用意すれば、最小限のインフラで必要な機能の大半を実現できます。状態ファイルには、各リクエストのパラメーター、送信時刻、取得可能になる予定時刻、ダウンロード状況、発生したエラーを記録します。これだけで、最後に成功した状態からの再開、何をいつ収集したかという監査証跡、欠けている対象期間の検出に対応できます。

YAMLによる状態管理の実用上の制約は、同時アクセスです。複数のプロセスやマシンから実行すると、ファイルベースの管理では競合状態が生じます。1台のマシンで順次実行するパイプラインなら問題になりません。分散構成では軽量なデータベースが適切で、移行が必要になった際もYAMLの構造を素直にスキーマへ対応付けられます。

翌日取得するレポートの2段階ワークフロー

Amazonの一部のレポートは非同期で生成されます。リクエストするとAmazonのキューに入り、数分から数時間後に取得できるようになります。最も信頼性の高い方法は、処理を2回に分けるワークフローです。リクエスト処理で未送信の要求をまとめて送信し、ダウンロード処理で前回の確認以降に取得可能になったレポートを回収します。

リクエスト処理は、通常は夜遅くなど決まった時刻に実行し、直近の完了済み期間について必要な全種類のレポートを要求します。YAML状態ファイルに各リクエストIDと送信時刻を記録します。翌朝のダウンロード処理では、保留中の全リクエストの状態を問い合わせ、準備ができたレポートをダウンロードして完了と記録します。まだ取得できないレポートは保留状態のまま残し、次回のダウンロード処理で再試行します。

この分離には、レポート生成の待ち時間を、パイプラインが目標とするデータ提供時期から切り離せるという重要な運用上の利点があります。取得できるまで処理を止めて待つと、遅延が変動し、タイムアウト処理も複雑になります。代わりに、締め切り時刻までに要求したレポートは、翌日の所定の時間帯での提供を目標とします。その時点でAmazonが生成を完了していないレポートは、次回の処理まで保留状態のまま残します。その時間帯の中で実際に取得できる時刻は、パイプラインではなくAmazonのキューに左右されます。

設計で考慮すべき障害は、レポートの有効期限と重複リクエストです。Reports APIがレポートを保持する期間は最大90日なので、ダウンロードの遅れを検知する必要があります。また、同じ期間の要求を重複送信すると、冗長なファイルが生成され、APIの利用枠を浪費します。YAML状態ファイルは、有効なリクエストがある期間を記録し、その要求が期限切れになるか、確定的に失敗するまで再要求を防ぐことで、両方に対応します。

本番環境で起きる障害

本番環境で最もよく起きる障害は、レポート抽出自体ではなく、認証情報の管理です。SP-APIはLWA（Login With Amazon）アクセストークンを使います。このトークンは1時間で期限切れになり、より長いものの有限の有効期間を持つリフレッシュトークンで更新する必要があります。開発時に更新を正しく処理できていたパイプラインでも、本番環境で長期間無人運転すると、リフレッシュトークンを更新しないまま期限切れとなり、失敗することがあります。

ブラウザーによる抽出では、別の障害が起きます。セッションCookieの期限切れ、Amazonによる新たな確認手順の追加、CSSセレクターや画面遷移を壊すインターフェース変更などです。ファイルをダウンロードできたことだけでなく、そのファイルに想定したデータ構造が含まれるかを明示的に検証しなければ、こうした障害は表面化しません。

本番環境の障害の大半を防ぐ運用上の原則は、各段階での検証です。開始前に認証情報が有効かを確認し、要求した各レポートが想定したスキーマを返すかを確認します。ダウンロードしたファイルの対象期間が、要求した期間と一致するかも確認します。徹底して検証するパイプラインは、失敗を即座に明確に知らせます。入力を信頼するだけのパイプラインは、気付かれないまま失敗し、大きな損失を生みます。

複数マーケットプレイスのデータパイプライン：地域をまたぐ出品者アカウントの管理：マーケットプレイス別の設定とYAMLの状態管理により、単一マーケットプレイスの抽出をUS、JP、DEへ拡張します。
Amazon出品者向けに本番運用できるデータ基盤を構築する：tva-fetchのアーキテクチャと、その基盤となるSP-API連携パターンを紹介します。
FastAPIとTimescaleDBを使ったAmazonデータウェアハウスの構築：抽出したデータをディスクに保存した後の活用方法を解説します。