Merchant Center に商品データをアップロードするには、ファイルベースのフィード、Merchant API、またはその両方を組み合わせて使用します。
- ファイルベースの商品フィード: SFTP、Google Cloud Storage、Google スプレッドシート、またはスケジュール設定された取得を使用して、CSV、TSV、または XML ファイルをアップロードします。
- Merchant API: 商品データの変更に伴う増分アップデートのリクエストを、バックエンドから直接プログラムで送信します。また、カタログ全体の定期的な同期も行います。
このガイドでは、両方のアプローチを比較し、どちらか一方（または両方）を使用するタイミングについて説明します。また、一部またはすべての商品をファイル フィードから API に移行する場合に備えて、段階的な移行プレイブックを提供します。
データソースのアプローチを選択する
カタログの変動性、バックエンド アーキテクチャ、運用ワークフローを評価して、Merchant API、ファイル フィード、ハイブリッド設定のいずれを使用するかを決定します。
Merchant API を使用するケース
次のような場合は、API メイン データソースを使用します。
- 直接的なプログラムによる統合: ファイルを生成してファイル転送パイプライン（SFTP や Google Cloud Storage など）を管理するのではなく、バックエンドから直接 API を呼び出すことを好む場合。
- 価格と在庫の変動が大きい: 商品の価格や在庫レベルが 1 日を通して頻繁に変動する。
- データ変更時の即時更新: 次のスケジュールされたファイルの生成とアップロードを待つのではなく、バックエンドで商品が変更されたらすぐに Google に送信する場合。
- カタログの増分更新: 変更に応じて個々の商品を挿入、更新、削除します。毎回カタログ全体を再アップロードする必要はありません。
- 属性の部分更新: 商品のペイロード全体を再送信せずに、商品の特定のフィールド（
productInputs.patchを使用したpriceやavailabilityなど）を更新する場合。
ファイル フィードを使用するタイミング
次のような場合は、ファイルベースのメイン データソースを使用します。
- 静的カタログ: 商品データの変更頻度が低い（1 日に 1 回以下など）。
- デルタ トラッキングなしのスナップショットのみのバックエンド: バックエンドは、カタログ全体の完全なスナップショットのみをエクスポートし、アイテムレベルの変更や明示的な商品の削除を追跡できません。
- スプレッドシート ベースのワークフロー: エンジニアリング以外のチームが、Google スプレッドシートまたは CSV ファイルで商品データを直接キュレートまたはオーバーライドします。
- メンテナンスの手間が少ないオペレーション: リクエストのペース調整、再試行処理、定期的なカタログ全体の同期を伴う API 統合を運用するのではなく、Merchant Center がフェッチとスナップショット処理を処理する、スケジュール設定されたファイル エクスポートを希望する場合。
両方を使用する状況
次のシナリオでは、同じ Merchant Center アカウントでファイル フィードと Merchant API を組み合わせることができます。
- 分割された商品カタログ: 変化の激しい商品（期間限定セールや回転率の高い在庫など）には Merchant API を使用し、静的なカタログ セグメントや個別の商品ラインにはファイル フィードを使用します。各商品が 1 つのプライマリ データソースによってのみアップロードされるようにします（並行使用とプライマリ データソースの所有権を参照）。
- API のメインデータとファイルベースの補助フィード: API のメインデータソースを使用してコア商品データを管理し、エンジニアリング以外のチームまたはサードパーティ パートナーが、属性ルールで結合されたファイルベースの補助フィード（Google スプレッドシートや CSV ファイルなど）を使用して追加の属性を提供します。または、その逆を行います。
- 部分的または段階的な移行: 特定の市場、カテゴリ、サブアカウントを API に移行し、残りのカタログはファイル フィードに保持します。
一部またはすべての商品をファイル フィードから Merchant API に移行する場合は、移行ハンドブックの手順に沿って操作してください。
アーキテクチャの主な違い
ファイル フィードとプッシュベースの Merchant API では、Google が商品データを処理および管理する方法が異なります。
| コンセプト | ファイル フィード | Merchant API |
|---|---|---|
| 統合モデル | オフライン ファイル ダンプ: カタログをファイルにエクスポートし、SFTP、Google Cloud Storage、Google スプレッドシート、またはスケジュール設定された取得を使用して転送します。 | 直接的なプログラムによる統合: バックエンドが API エンドポイントにリクエストを直接送信します。 |
| ミューテーションの粒度 | 一括処理: 1 つのアイテムを変更するには、通常、ファイル全体を再処理する必要があります。 | きめ細かいトランザクション: 変更された商品のみを挿入、パッチ、削除できます。 |
| 同期のタイミング | バッチ同期: 変更は、次回のスケジュール設定されたファイルのエクスポートと転送のサイクルまでバックエンドで待機します。 | 即時呼び出しまたはスケジュール設定された呼び出し: 定期的な完全同期とともに、増分変更が発生したときにすぐに送信できます。 |
| 削除の動作 | 暗黙的（スナップショット）: 各ファイルは完全なスナップショットです。メインファイルから行を削除すると、商品が削除されます。 | 明示的: スナップショットのコンセプトはありません。productInputs.delete を呼び出して、廃止された商品を削除します。 |
| リソース表現 | 単一状態: ファイルの行は未加工の入力を表します。 | 未加工と処理済みを分離する: API は、データを ProductInput（未加工の入力）と Product（最終的な処理済みの状態）に分割します。 |
| 属性（フィード）ルール | Merchant Center の管理画面で、未加工ファイルの列に適用されます。 | Merchant Center の管理画面でサポートされています。API データをサードパーティの補助ファイルと統合する場合は必須。バックエンドで処理される単一ソースの変換の場合は省略可能。 |
並行使用とメイン データソースの所有権（「最終更新が優先」）
同じ Merchant Center アカウントでファイル フィードと API の両方を使用できますが、特定の商品を挿入するには 1 つの方法のみを使用することを強くおすすめします。
Merchant Center は「最後に更新されたものが優先される」モデルで動作します。最新の商品挿入をプッシュしたプライマリ データソース（API またはファイル フィード）が、その商品のデータのプライマリ オーナーシップを取得します。
- ファイル データソースが商品を所有している場合: 後続のファイル アップロードで商品が省略されると、暗黙的な削除がトリガーされ、Merchant Center から商品が削除されます。
- API データソースが商品を所有している場合: ファイル フィードが商品を所有しなくなったため、ファイル アップロードから商品を除外しても効果はありません。削除するには、
accounts.productInputs.deleteを呼び出す必要があります。 - 誤って所有権が再取得されるリスク: API push の後に更新されたファイル フィードが実行され、そのフィードに商品が含まれている場合、ファイル データソースが所有権を再取得します。その後、ファイルから省略すると、商品が予期せず削除されます。
予期しない削除や API 更新の損失を回避するため、API とファイルのメイン データソースの両方を使用して、同じ商品に対して同時に更新を実行しないでください。
API に関する主な考慮事項
実装を開始する前に、Merchant API の次の重要な動作を理解しておいてください。
柔軟なデータソース（言語やラベルなし）
特定のターゲット フィードラベルと言語を事前に定義する必要があるファイル フィードとは異なり、Merchant API では、feedLabel または contentLanguage を指定せずにプライマリ データソースを作成できます。
- 柔軟なアップロード: 言語やフィードラベルの組み合わせに関係なく、商品を 1 つのデータソースにアップロードできます。
- 管理の簡素化: 対象市場ごとに個別のデータソースを作成して管理する必要がありません。注: データソース戦略の選択について詳しくは、データソース戦略を選択するをご覧ください。
同期戦略と割り当て
カタログ全体を 1 つのバッチでアップロードするファイル フィードとは異なり、Merchant API の統合は、増分更新とペースを調整した完全同期の両方を考慮して設計します。
- 増分アップデートと定期的な完全同期を組み合わせる: バックエンドで商品属性が変更されたときに、
productInputs.insertリクエストまたはproductInputs.patchリクエストを送信します。増分アップデートのみに依存すると、時間の経過とともにデータの同期がずれる可能性があるため、定期的に完全同期を実行して、カタログを信頼できる情報源と照合します（これにより、30 日間の商品の有効期限も更新されます）。完全同期を実行する頻度は、カタログのサイズと使用可能な API 割り当てによって異なります。 - API の割り当てを考慮してリクエストのペースを調整する: すべての商品に対して一度に API を呼び出さないでください。増分変更は発生時に送信できますが、完全同期リクエストは 1 日に均等に分散して、1 分あたりおよび 1 日あたりのメソッド呼び出しの割り当て内に収まるようにします。詳細については、割り当てと制限と商品を頻繁に更新するをご覧ください。
統合のテスト
本番環境に移行する前に、安全な環境で統合ロジックを検証します。
テスト アカウントを使用する
本番環境で変更を行う前に、サンドボックス化されたテストアカウントで移行の初期手順を実行することをおすすめします。
- テスト アカウントを作成する: 独立したテスト アカウントを設定して、ライブ広告や無料リスティングに影響を与えることなく安全にテストを行います。
- API データソースを作成する: API メイン データソースを作成する練習をします。
- 属性ルールをテストする: データ変換と補助フィードの結合を検証します。
- ペイロードとプロダクト キーを検証する: サンプル プロダクトをプッシュして、SKU の大文字と小文字の区別、エンコード、エラー処理を検証します。
詳しくは、ステップ 1: テスト用アカウントを作成するとテスト用アカウントのガイドをご覧ください。
プロダクト キーの整合性を検証する
プログラマティック ペイロードの商品キーが、ファイル フィードの SKU と完全に一致していることを確認します。Google では、次の情報を組み合わせて商品を識別します。
offerId（ファイル フィードではidと呼ばれます。大文字と小文字を区別します）contentLanguage（例:en）feedLabel（例:US）
特殊文字とエンコード
商品 ID に /、%、~ などの文字が含まれている場合は、API 呼び出しでエンコード形式（パディングなしの base64url エンコード）を使用します。詳細については、ProductInput.name をご覧ください。
同時実行制御
リアルタイム統合では、ネットワーク レイテンシが原因で、更新が順番どおりに到着しないことがあります。古い更新で新しいデータが上書きされないようにするには、ProductInput リソースの versionNumber フィールドを使用します。
移行の詳細な手順
一部またはすべての商品をファイル フィードから Merchant API に移行する場合は、このハンドブックに沿って、インプレッションや配信履歴を失うことなく商品を移行してください。
1. テスト アカウントで移行をリハーサルする
本番環境で変更を行う前に、accounts.createTestAccount メソッドを使用してサンドボックス化されたテスト アカウントを作成します（テスト アカウント ガイドをご覧ください）。テスト アカウントは、デフォルトでオファーが承認され、ドメインの確認が不要で、データが一般に公開されない、隔離された環境を提供します。
テスト アカウントを使用して本番環境の設定をミラーリングし、移行をエンドツーエンドでリハーサルします。
- 商品フィードの設定をミラーリングする: テスト アカウントにファイル メイン データソース（および補助データソース）を作成し、本番環境のフィード ファイルのサンプルをアップロードします。
- テスト用の API データソースとルールを作成する: API メイン データソースを作成し、必要な属性ルールまたは補助フィードの結合を構成します。
- 所有権の引き継ぎとキーの調整をテストする: サンプル商品の
productInputs.insertリクエストを送信し、API データソースが重複する商品を作成せずに既存の商品の所有権を引き継ぐことを確認します。 - 更新と削除を確認する:
productInputs.patchを使用して部分的な更新をテストし、productInputs.deleteを使用して削除をテストします。products.getを使用して、結果のリソースを検査します。
2. 本番環境の API データソースを作成する
データを push する前に、アカウントに API タイプのメイン データソースを作成します。
API のメイン データソースを作成する
API push を受け入れるデータソースを作成するには、dataSources エンドポイントに POST リクエストを送信します。詳細については、メイン商品データソースを作成するをご覧ください。
3. カスタム属性ルールを移行する
カスタム属性ルールは特定のデータソースにバインドされるため、ファイル データソースから新しい API データソースに自動的に転送されることはありません。
属性ルールの移行方法は、その目的によって異なります。
- クロスソースの統合とサードパーティの補助フィード: メインの API データを外部の補助データソース（サードパーティのサプライヤー ファイル、在庫スプレッドシート、プロモーション フィードなど）と組み合わせる場合は、Merchant Center の管理画面で属性ルールを再作成し、新しい API データソースに適用する必要があります。クライアントサイドの前処理では、複数の独立したソースにまたがるデータを結合するルールを置き換えることはできません。
- 単一ソースのデータ変換: 単一ソースのクリーンアップ、デフォルト値、またはメインのカタログデータの文字列形式については、次のいずれかを選択します。
- バックエンド変換（推奨）: API を呼び出す前に、独自のシステムで変換を適用します。これにより、プログラムによる制御が容易になり、テストが容易になり、デバッグが簡素化されます。
- Merchant Center の属性ルール: Merchant Center で引き続き自動的に管理する場合は、Merchant Center の管理画面で新しい API データソースの変換ルールを再作成します。
4. API 統合を有効にする
本番環境の API 統合を有効にして、新しい API メイン データソースで商品の挿入、更新、削除を開始します。
商品の挿入と更新（オーナー権限の引き継ぎ）: 統合から
productInputs.insertリクエストとproductInputs.patchリクエストを送信します。既存のファイル フィード商品と同じキー（offerId、contentLanguage、feedLabel）を使用して API で商品を挿入すると、API データソースがその商品の所有権を取得し、配信履歴を保持します。詳しくは、商品を挿入すると商品を追加、管理するをご覧ください。販売終了となった商品を削除する: カタログから商品が削除されるたびに
productInputs.deleteを明示的に呼び出すように統合を構成します。段階的にデプロイする: カタログが大きい場合は、Merchant Center のサブアカウントまたはデータソースを 1 つずつ有効にします。
同時実行を構成する: 多数のリクエストを送信する場合は、同時リクエストを処理し、複数の接続を管理するようにクライアントを構成します。同時リクエストのコードをリファクタリングするガイドをご覧ください。
5. ファイル データソースの更新を一時停止する
API 統合が有効になったら、次のスケジュール設定されたファイル実行の前にファイルの更新を停止して、ファイル データソースが API の更新を上書きしないようにします。
- SFTP / FTP の場所、Google Cloud Storage、Google スプレッドシートへの新しいファイルのアップロードを停止します。
- Merchant Center の管理画面で、ファイル データソースに移動し、スケジュール設定された取得を一時停止します。
- ファイル データソースが所有する既存の商品は、API 統合によって挿入されるまで、最大 30 日間有効なままになります。
6. 移行が完了するまで待ってから確認する
有効なすべての商品がファイル データソースから API データソースに移行されるまで待ちます。増分アップデートでは、商品が変更されるたびに移行されますが、通常の統合を通じてカタログ全体の同期を段階的に実行すると、カタログ全体の移行が高速化されます（同期戦略と割り当てをご覧ください）。
このフェーズでは、次のことを行います。
- Merchant Center の管理画面で、商品数を確認します。ファイル データソースの数が
0に減少し、API データソースの数がアクティブなカタログと一致するまで待ちます。 products.getを使用して、属性とカスタム属性ルールが想定どおりに統合されていることを確認します。- Merchant Center UI の API 診断ツールをモニタリングして、エラー率と API のパフォーマンスを追跡します。
7. ファイル データソースをデコミッションする
移行が完了し、ファイル フィードのアイテム数が 0 になった後:
- 更新がリアルタイムで反映されていることを確認します。
- Merchant Center の管理画面で以前のファイル データソースを削除して、ファイルベースの更新によって API データが誤って上書きされないようにします。