データのマッピングと変換: さまざまな API とデータ形式の処理

各 e コマース プラットフォームは異なる言語を話します。 Amazon は、ネストされたアドレス オブジェクトを含む XML として注文を送信します。 Shopify はフラット文字列フィールドを含む JSON を返します。 eBay は、REST と従来の XML-RPC を組み合わせて使用​​します。 WooCommerce は、キーと値の配列にメタデータを埋め込みます。 ERP は、検証されたデータ型を使用した特定の内部形式のすべてを期待します。

データのマッピングと変換は、マルチチャネル統合を機能させる変換レイヤーです。正しく設定すれば、データはシステム間で静かに流れます。誤解を招くと、なぜ顧客の電話番号が都市のフィールドに入力されているのか、なぜ製品の重量が 2.2 倍もずれているのかをデバッグするのに何時間も費やすことになります。

重要なポイント

• 正規データ モデル (内部標準) により、N 対 N マッピングが排除され、N 対 1 と 1 対 N が優先されます。
• 単位変換エラーは、国境を越えた e コマースで最も一般的で最もコストのかかるデータ マッピングのバグです
• 防御的な解析 - すべてのフィールドを検証し、すべての欠損値をデフォルトにします - 連鎖的な失敗を防止します
• コードと一緒にマッピングをバージョン管理します。 API の変更により、バージョン管理されたスキーマなしで統合がサイレントに中断される

---

正規データ モデル

正規モデルがなければ、5 つのチャネルを ERP に接続するには、10 個の一意のマッピング (5 つのインバウンド + 5 つのアウトバウンド) が必要となり、それぞれが他のシステムの特性を処理します。 6 番目のチャネルを追加するには、さらに 2 つのマッピングが必要です。

正規モデルでは、各チャネルが単一の内部フォーマットにマッピングされ、単一の内部フォーマットからマッピングされます。 6 番目のチャネルを追加するには、他にいくつのチャネルが存在するかに関係なく、1 つの新しい受信マッパーと 1 つの新しい送信マッパーのみが必要です。

正規モデルの設計

正規モデルは次のようになります。

• すべてのチャネルのスーパーセット: 一部のチャネルがすべてのフィールドを使用しない場合でも、チャネルに必要なすべてのフィールドを含めます。
• 厳密に型指定: 日付は ISO 8601、重量はグラム単位、通貨は ISO 4217 コードを使用、価格は浮動小数点ではなく整数 (セント) です。
• バージョン付き: スキーマの変更は明示的であり、下位互換性があります。
• 文書化: すべてのフィールドに説明、データ型、検証ルール、およびソース マッピングが含まれています。

例: 正規順序モデル

簡略化された標準的な順序:

すべてのソースが同じ正規構造にどのようにマッピングされるかに注目してください。この変換では、パスの違い (ネストとフラット)、名前の違い (キャメルケースとパスカルケースとスネークケース)、および形式の違い (日付、数値、通貨) が処理されます。

---

マッピングに関する一般的な課題と解決策

データ マッピングには特殊なケースがたくさんあります。ここでは、最も一般的な問題とその解決方法を示します。

---

単位変換

単位換算エラーは実際の経済的損害を引き起こします。サイト上で 2.2 kg と記載されている商品が、Amazon では 2.2 ポンドとして表示されている場合、送料の見積もりが間違っており、寸法重量の計算も間違っており、顧客が予想の 2 倍の重さの商品を受け取ることになります。

重量換算

ルール: すべての重量をグラム単位で内部に保存します。アウトバウンドを各チャネルが必要とする単位に変換します。受信データの単位ラベルを決して信頼しないでください。その値が製品カテゴリにとって意味のあるものであることを検証してください。重さ2グラムのラップトップは当然キログラム単位です。

寸法変換

次元も同様に危険です。米国アマゾンはインチを期待している。 Amazon DE はセンチメートルを想定しています。出荷用ソフトウェアには数ミリメートルが必要な場合があります。

ルール: すべての寸法をミリメートル単位で内部に保存します。チャネルごとにアウトバウンドを変換します。寸法が物理的に妥当であることを検証します。

通貨換算

複数通貨の処理により、新たなレイヤーが追加されます。正規モデルでは、基本通貨の最小単位 (USD の場合はセント、GBP の場合はペンス、EUR の場合はサンチーム) で価格が保存されます。

国境を越えた注文の場合は、元の通貨金額と、使用される為替レートで変換された基本通貨金額の両方を保存します。これにより、通貨関連の不一致の監査証跡が作成されます。

---

データ正規化パターン

マーケットプレイスの生のデータは乱雑です。正規化により、正規モデルに入る前にクリーンアップされます。

テキストの正規化

• 空白の削除: API 応答では先頭と末尾の空白が一般的です。
• Unicode の正規化: 必要に応じて、全角文字、スマート引用符、および特殊文字を同等の ASCII 文字に変換します。
• 大文字と小文字の標準化: 内部データを一貫した大文字と小文字で保存します (例: 国コードの場合は大文字、名前の場合は大文字、電子メールの場合は小文字)
• HTML エンティティのデコード: & から &、< から < など。

アドレスの正規化

アドレスは、チャネル間で最も一貫性のないデータ タイプです。正規化パイプラインは次のことを行う必要があります。

1. フリーテキストの住所を構造化コンポーネント (番地、都市、州、郵便番号、国) に解析します。
2. 国の形式ルールに照らして郵便番号を検証する
3. 国を ISO 3166-1 alpha-2 コードに正規化します (US、GB、DE — 「米国」、「英国」、「ドイツ」ではありません)
4. 州/県を標準の略語に正規化する
5. 都市/州/郵便番号の組み合わせが地理的に一貫していることを検証する

SKU の正規化

異なるソースからの SKU は、同じ製品に対して異なる形式を使用する場合があります。

• サプライヤー：「ABC-001-BLK-L」
• アマゾン：「ABC001BLKL」
• Shopify: "abc-001-black-large"
• eBay: 「ABC 001 ブラック L」

正規モデルでは、単一の内部 SKU 形式を使用し、外部 SKU 形式を内部 ID にマッピングするルックアップ テーブルを維持する必要があります。

---

API フォーマットの処理

異なる API は異なる形式でデータを返します。変換レイヤーはそれらすべてを処理する必要があります。

JSON (Shopify、Walmart、TikTok ショップ)

最新の API のほとんどは JSON を使用します。解析は簡単ですが、次の点に注意してください。

• 数値精度: JSON 数値は、大きな整数 (2^53 を超える注文 ID) の精度が失われる可能性があります。必要に応じて文字列として解析します。
• ネスト構造: Shopify は、応答内の注文内に配送先住所をネストします。適切なパスナビゲーションを使用してください。
• ページネーション: カーソルベース (Shopify) またはページベース。ページ間のレート制限を処理します。

XML (Amazon SP-API レポート、eBay)

XML では、名前空間、属性と要素、エンコード宣言により複雑さが増します。

• 名前空間の処理: Amazon レポートは、XPath クエリが機能する前に登録する必要がある XML 名前空間を使用します。
• CDATA セクション: テキスト コンテンツは CDATA でラップされる場合があり、一部のパーサーはそれを取り除き、他のパーサーは保持します。
• 文字エンコーディング: 常に UTF-8 として解析されます。一部の従来のフィードは ISO-8859-1 を宣言しています。

CSV/TSV (Google ショッピング、Amazon フラット ファイル)

フィードベースのチャネルは表形式のデータを受け入れます。

• 列の順序は重要です: 一部のフィードはヘッダーではなく位置に依存します。
• エスケープ: カンマを含むフィールドは引用符で囲む必要があります。引用符を含むフィールドでは二重引用符を使用する必要があります。
• エンコーディング: ファイル先頭の BOM (バイト オーダー マーク) により、一部のシステムで解析エラーが発生します。それを剥がしてください。
• 行末: Windows (CRLF) と Unix (LF)。解析する前に正規化します。

EDI (企業小売、3PL)

電子データ交換は、大手小売業者や 3PL によって今でも使用されています。 EDI ドキュメント (850 発注書、856 事前出荷通知、810 請求書) は、X12 または EDIFACT 標準で定義された固定幅形式または区切り文字で区切られた形式を使用します。

---

変換時のエラー処理

データが予期したスキーマと一致しない場合、変換レイヤーは失敗、デフォルト、またはフラグを決定する必要があります。

戦略マトリックス

検証パイプライン

すべてのレコードは、変換後に検証パイプラインを通過する必要があります。

1. スキーマ検証: レコードは予想される構造と一致しますか?
2. 型の検証: 数値は実際に数値であり、日付は実際に日付ですか?
3. ビジネス ルールの検証: 注文の合計はプラスですか?配送先住所はサービスを提供している国にありますか?
4. 参照検証: SKU は製品カタログに存在しますか?

検証に失敗したレコードは隔離され、サイレントに削除されたり、不正なデータで処理されたりするのではなく、手動レビューのためにエラー キューに保存されます。

これらの検証エラーの監視については、統合監視 を参照してください。

---

バージョン管理と変更管理

API は変更されます。 Shopify は四半期ごとに新しい API バージョンを導入します。 Amazon は SP-API モデルを定期的に更新します。 eBay は従来のエンドポイントを廃止します。マッピング層は、ダウンタイムなしでこれらの変更を処理する必要があります。

バージョン管理戦略

• API バージョンをピン留め: 呼び出す API バージョンを常に指定します。 Shopify では 2025-01 をリクエストできます。 Amazon SP-API は、日付のあるモデル バージョンを使用します。
• マッパーのバージョンを設定: チャネル API が変更された場合は、既存のマッパー バージョンを変更するのではなく、新しいマッパー バージョンを作成します。移行中は両方のバージョンを並行して実行します。
• 自動回帰テスト: マッパーごとに、サンプル入力と予想される出力のセットを維持します。マッパーが変更されると、テストで意図しないリグレッションが検出されます。
• 非推奨のモニタリング: API 変更ログと日没通知を購読します。非推奨日の 60 日前に移行を計画します。

完全な統合アーキテクチャについては、柱となる投稿: 究極の e コマース統合ガイド を参照してください。

---

よくある質問

あるチャネルには存在するが別のチャネルには存在しないフィールドを処理するにはどうすればよいですか?

正規モデルには、すべてのフィールドのスーパーセットが含まれています。フィールドのないチャネルからの受信データを変換する場合は、フィールドを null または適切なデフォルトに設定します。フィールドを受け入れないチャネルにアウトバウンドを変換する場合は、単にフィールドを省略します。正規モデルは普遍的な翻訳者として機能します。すべての言語にすべての概念を表す単語があるわけではありませんが、それは問題ありません。

Node.js スタックでのデータ変換に最適なライブラリは何ですか?

JSON 変換の場合、JSONata、Lodash (パスのアクセスと操作用)、Zod (検証用) などのライブラリでほとんどのニーズをカバーできます。 XML の場合、解析には fast-xml-parser を使用し、構築には xmlbuilder2 を使用します。 CSV の場合、Papa Parse はエッジケースをうまく処理します。複雑な ETL パイプラインの場合は、Apache NiFi または徹底的な単体テストを備えたカスタム変換関数を検討してください。

ライブ API にアクセスせずにデータ マッピングをテストするにはどうすればよいですか?

実際の API 応答をフィクスチャとして記録し、単体テストで使用します。各マッパーには、実際の例、エッジ ケース (空のフィールド、最大長、特殊文字)、およびエラー ケース (不正な形式のデータ) を含む包括的なテスト スイートが必要です。マッピング コードを変更するコミットごとに、CI/CD でこれらのテストを実行します。 Nock (Node.js) や WireMock (Java) などのツールは、統合テスト用に API エンドポイントをモックできます。

ETL ツールを使用するか、カスタム変換コードを作成する必要がありますか?

有名なプラットフォームとの標準的な e コマース統合の場合、アプリケーション層 (Node.js/TypeScript または Python) のカスタム コードは、個別の ETL ツールよりも保守しやすくなります。 ETL プラットフォーム (Fivetran、Airbyte、Apache NiFi) は、20 以上のデータ ソースを複雑な変換パイプラインと統合するときに付加価値をもたらします。 3 ～ 8 チャネルの e コマース統合の場合、適切なテスト カバレッジを備えた専用マッパーは、よりシンプルでデバッグしやすいものです。

---

次は何ですか

データ マッピングは、マルチチャネル統合を信頼できるものにする地味な基盤です。変換レイヤーがあらゆるエッジケースを適切に処理すると、残りの統合スタックはクリーンで一貫性のある検証済みのデータで動作し、深夜のデバッグ セッションはなくなります。

Odoo を 15 以上のマーケットプレイスに接続する事前構築済みデータ マッパーについては ECOSIRE の統合サービス を探索するか、統合のためのカスタム変換要件について話し合う場合は 当社のチームに連絡 してください。

---

ECOSIRE によって発行 — Odoo ERP、Shopify eCommerce、OpenClaw AI にわたる AI を活用したソリューションで企業のスケールアップを支援します。