このページは Cloud Translation API によって翻訳されました。

カタログ情報をインポートする

このページでは、カタログ情報をインポートして最新の状態に保つ方法について説明します。

このページのインポート手順は、レコメンデーションと検索の両方に適用されます。データをいったんインポートすると、両方のサービスでそのデータを使用できるようになります。そのため、両方のサービスを使用する場合、同じデータを 2 回インポートする必要はありません。

商品データは、BigQuery からインポートでき、またはリクエスト内でデータをインラインで指定できます。Merchant Center をリンクすることを除いて、これらの各手順は 1 回限りのインポートです。カタログが定期的にインポートして、カタログが最新の状態であることを確認するようおすすめします（できれば、毎日）。

カタログを最新の状態に保つをご覧ください。

商品アイテムを個別にインポートすることもできます。詳細については、製品をアップロードするをご覧ください。

始める前に

カタログのインポートを開始する前に、次のことを行う必要があります。

プロジェクトを設定する。
サービスアカウントを作成します。
サービスアカウントをローカル環境に追加します。

詳細については、設定の前提条件をご覧ください。

カタログのインポートに関する考慮事項

このセクションでは、カタログデータの一括インポートに使用できる手段、各手段を使用するタイミング、その制限事項について説明します。

BigQuery	説明	コマース向け Vertex AI Search スキーマを使用する、以前に読み込まれた BigQuery テーブルからデータをインポートします。 Google Cloud コンソールまたは curl を使用して実行できます。
	使うタイミング	属性の多い商品カタログがある場合。BigQuery のインポートでは Vertex AI Search for Commerce スキーマが使用されます。このスキーマは、Key-Value カスタム属性など、他のインポートオプションよりも多くの商品属性を備えています。大量のデータがある場合。BigQuery のインポートにはデータの上限はありません。すでに BigQuery を使用している場合。
	制限事項	Vertex AI Search for Commerce スキーマにマッピングされる BigQuery テーブルを作成する追加のステップが必要です。
Cloud Storage	説明	Cloud Storage バケットに読み込まれたファイルから JSON 形式のデータをインポートします。各ファイルは 2 GB 以下である必要があります。一度にインポートできるファイル数は最大で 100 個です。インポートは、 Google Cloud コンソールまたは curl を使用して行うことができます。カスタム属性を許可する `Product` JSON データ形式を使用します。
	使うタイミング	1 回で大量のデータを読み込む必要がある場合。
	制限事項	変更がすぐに反映されないため、棚卸しと価格の更新が頻繁にあるカタログには適していません。
インラインインポート	説明	`Product.import` メソッドの呼び出しを使用してインポートします。このオブジェクトは、Vertex AI Search for Commerce スキーマよりも商品カタログ属性が少ない `ProductInlineSource` オブジェクトを使用しますが、カスタム属性をサポートしています。
	使うタイミング	フラットで非リレーショナルカタログデータがある場合や、数量や価格の更新頻度が高い場合。
	制限事項	一度にインポートできるカタログアイテムは最大 100 個です。ただし、多くの読み込みステップを実行できます。アイテム数の上限はありません。

チュートリアル

このセクションでは、動画とシェルチュートリアルを使用して、さまざまなカタログインポート方法について説明します。

動画チュートリアル

この動画では、Retail API を使用してカタログをインポートする方法について説明します。

BigQuery からカタログをインポートするチュートリアル

このチュートリアルでは、BigQuery テーブルを使用して、大量のカタログデータを無制限にインポートする方法を説明します。

このタスクを Cloud Shell エディタで直接行う際の順を追ったガイダンスについては、[ガイドを表示] をクリックしてください。

ガイドを表示

Cloud Storage からカタログをインポートするチュートリアル

このチュートリアルでは、多数のアイテムをカタログにインポートする方法について説明します。

このタスクを Cloud Shell エディタで直接行う際の順を追ったガイダンスについては、[ガイドを表示] をクリックしてください。

ガイドを表示

インラインでカタログデータをインポートするチュートリアル

このチュートリアルでは、商品をカタログにインラインでインポートする方法について説明します。

このタスクを Cloud Shell エディタで直接行う際の順を追ったガイダンスについては、[ガイドを表示] をクリックしてください。

ガイドを表示

カタログのインポートに関するベストプラクティス

高品質な結果を生成するには、高品質なデータが必要です。データにフィールドが存在しないか、実際の値ではなくプレースホルダ値が存在する場合、予測と検索結果の品質が低下します。

カタログデータをインポートするときは、次のベストプラクティスを実施するようにしてください。

プライマリ商品とバリエーション商品を慎重に区別してください。データをアップロードする前に、商品レベルをご覧ください。
- データをインポートするのにかなりの労力を費やした後に、商品レベルの構成を変更する。バリエーションではなく、プライマリアイテムが検索結果またはおすすめとして返されます。
- 例: プライマリの SKU グループが V ネックシャツの場合、レコメンデーションモデルは V ネックシャツと、おそらくクルーネックシャツとスクープネックシャツを返します。ただし、バリエーションが使用されておらず、各 SKU がプライマリである場合、V ネックシャツのすべての色とサイズの組み合わせが、おすすめパネルに個別のアイテムとして返されます（ブラウンの V ネックシャツ、サイズ XL、ブラウンの V ネックシャツ、サイズ L から ホワイトの V ネックシャツ、サイズ M、ホワイトの V ネックシャツ、サイズ S まで）。
- バリエーション ID がメインの商品 ID とともに collectionMemberIds[] に含まれている限り、コレクションはまとめて認識されます。これにより、ユーザーがセット内の 1 つ以上の商品を購入した商品コレクションがユーザーイベントでキャプチャされ、セット全体が購入としてクレジットされます。これにより、将来の関連クエリで、同じユーザーに特定のコレクション内の他のプロダクトを簡単に提供できるようになります。
- 例: ユーザーが以前に布団カバーを購入したため、枕カバーなど、ベッドシーツコレクションの関連商品が返されます。
商品アイテムインポートの上限を確認します。
- Cloud Storage からの一括インポートの場合、各ファイルのサイズは 2 GB 以下である必要があります。1 回の一括インポートリクエストで一度に最大 100 個のファイルを含めることができます。
- インラインインポートの場合、一度にインポートできる商品アイテムは 5,000 個までです。
必須のカタログ情報がすべて含まれていて、正しいことを確認します。プレースホルダの値は使用しないでください。
可能な限り多くのオプションのカタログ情報を格納してください。
特にGoogle Cloud コンソールを使用して収益指標を取得する予定がある場合は、すべてのイベントで単一の通貨が使用されていることを確認してください。Vertex AI Search for Commerce API では、カタログごとに複数の通貨を使用することはできません。
カタログを最新の状態に保ちます（理想的には毎日）。定期的なカタログのインポートをスケジュール設定すると、時間の経過とともにモデルの品質が低下することを回避できます。コマース向け検索コンソールを使用してカタログをインポートするときに、定期的な自動インポートをスケジュール設定できます。または、Google Cloud Scheduler を使用して、インポートを自動化することもできます。
まだインポートされていない商品アイテムのユーザーイベントを記録しない。
カタログ情報をインポートしたら、プロジェクトの Error Reporting とロギング情報を確認します。エラーが複数見つかった場合は、エラーを確認し、エラーの原因となったプロセス上の問題を修正します。

Vertex AI Search for Commerce のデータ取り込みパイプラインには、商品カタログとユーザーイベントの両方のデータが含まれます。このデータストリームは、フィードバックメカニズムによる堅牢なモデルトレーニングと継続的な評価の基盤となります。正確で完全なデータ取り込みは前提条件であるだけでなく、基盤となるモデルの適応性を維持するために不可欠な継続的なプロセスです。これにより、検索結果の品質と関連性が直接影響を受け、投資収益率が大幅に向上します。

コマース検索ソリューションを設計する際は、次のデータ取り込みのベストプラクティスを検討してください。

一括インポート、リアルタイムストリーミング、またはその両方か？

Vertex AI Search for Commerce には、カタログの取り込み方法として次の 2 つがあります。

一括インポート
リアルタイムストリーミング

このデュアルアプローチにより、さまざまなお客様のバックエンドの多様なアーキテクチャニーズに対応できます。1 つの方法だけを選択する必要はありません。特定の要件に基づいて一括インポートとストリーミング更新の両方を使用するハイブリッド取り込みモードを使用できます。

一括インポートは、一度に数千もの商品を大規模に追加、削除、更新する場合に最適です。一方、リアルタイムストリーミングは、比較的小規模な商品に対して継続的な更新が必要な場合に適しています。これらの方法のどちらを選択するかは、商品カタログの性質、更新頻度、バックエンドシステムの全体的なアーキテクチャによって異なります。

一括インポート機能は、次の 3 つの異なるデータソースをサポートしています。

BigQuery: BigQuery を使用すると、カタログデータをすばやく変更できます。また、インポート時にパーティションの日付を指定したり、SQL クエリを使用してデータを効率的に変換したりできます。
Google Cloud Storage: Cloud Storage では、JSON などの特定の形式とファイル制限を遵守する必要があります。バケット構造、ファイルのチャンク化、インポートプロセスのその他の側面を管理する責任はユーザーが担います。また、Cloud Storage 内でカタログを直接編集するのは面倒な場合があります。費用対効果は高い可能性がありますが、他の方法ほどの柔軟性はありません。
インラインデータ: 大規模なカタログの場合、サイズ制限により、インラインインポートは最もスケーラブルなオプションではない可能性があります。マイナーアップデートや試験運用テストでの使用に限定してください。

短期間に大量の商品カタログの更新（数千件の商品変更、追加、削除）が定期的に発生するシナリオでは、一括インポートとリアルタイムストリーミングを組み合わせたアプローチが非常に効果的です。BigQuery または Cloud Storage で更新をステージングし、1 時間または 2 時間ごとに増分一括インポートを実行します。この方法では、大規模な更新を効率的に管理しながら、中断を最小限に抑えます。

更新頻度が低い場合や、カタログにすぐに反映する必要がある場合は、リアルタイムストリーミング API を使用します。ハイブリッドアプローチでは、リアルタイムストリーミングで一括インポート間のギャップを埋めることで、カタログを最新の状態に保つことができます。この戦略は、個々の REST API 呼び出し（商品のパッチ適用）と一括変更の実行のバランスを取り、Vertex AI Search for Commerce のカタログ管理の効率と応答性の両方を最適化します。

カタログ管理のブランチ戦略

複数のブランチに分散したカタログではなく、単一のブランチ内に統合されたカタログを維持します。この方法により、カタログの更新が効率化され、ブランチの切り替え中に不整合が発生するリスクが軽減されます。

カタログ管理には、次の一般的なブランチ戦略が効果的です。

単一ブランチの更新

ライブブランチをデフォルトとして指定し、カタログの変更が発生するたびに継続的に更新します。一括更新の場合は、トラフィックの少ない時間帯にインポート機能を使用して、中断を最小限に抑えます。ストリーミング API を使用して、小規模な増分更新を行うか、定期的なインポートのために大きなチャンクにバッチ処理します。

ブランチの切り替え

さまざまなブランチを管理するには、次の 2 つの方法があります。

ステージングと検証にブランチを使用します。
- 一部のコマースサイトエンジニアは、ブランチ切り替えアプローチを選択しています。このアプローチでは、カタログは非ライブブランチ内で更新され、本番環境の準備が整うとデフォルト（ライブ）ブランチになります。これにより、翌日のカタログを事前に準備できます。更新は、一括インポートまたは非ライブブランチへのストリーミングを使用して行うことができます。これにより、トラフィックの少ない時間帯にシームレスな移行が保証されます。
- これらの戦略のどちらを選択するかは、特定の要件、更新頻度、インフラストラクチャの設定によって異なります。ただし、選択した戦略に関係なく、Vertex AI Search for Commerce で最適なパフォーマンスと一貫した検索結果を得るには、単一のブランチ内で統合されたカタログを維持することが重要です。
バックアップにブランチを使用する:
- 単一のライブブランチは、商品の更新を継続的に取り込んで処理し、Vertex AI Search for Commerce のインデックスをほぼリアルタイムで最新の状態に保つことに重点を置いています。
- 別のブランチは、Retail Search で変換されたデータの毎日のスナップショットを作成することに重点を置いています。これは、データ破損やブランチ 0 の問題が発生した場合の堅牢なフォールバックメカニズムとして機能します。
- 3 つ目のブランチは、変換された日付の週単位のスナップショットを作成することに重点を置いています。これにより、お客様は 1 日前のバックアップと 1 週間前のバックアップを異なるブランチに保存できます。

カタログブランチをパージする

新しいカタログデータを既存のブランチにインポートする場合は、ブランチにインポートされるデータの整合性を保つために、カタログブランチが空であることが重要です。ブランチが空の場合、新しいカタログデータをインポートして、ブランチを販売者アカウントにリンクできます。

ライブ予測または検索トラフィックを提供していて、デフォルトのブランチを削除する予定の場合は、削除する前に別のブランチをデフォルトとして指定することを検討してください。デフォルトのブランチでは、削除後に空の結果が提供されるため、削除のデフォルトのブランチを削除すると、機能が停止する可能性があります。

カタログブランチからデータを削除するには、次の手順を行います。

Search for commerce コンソールの [データ] ページに移動します。

[データ] ページに移動
[ブランチ名] フィールドでカタログブランチを選択します。
[ブランチ名] フィールドの横にあるその他メニューから [ブランチを削除] を選択します。

ブランチ内のすべてのデータと、ブランチ用に作成された属性を削除しようとしていることを警告するメッセージが表示されます。

注: カタログブランチのデータの削除を取り消すことはできません。
ブランチを入力し、[確定] をクリックしてブランチからカタログデータを削除します。

カタログブランチからデータを削除するために、長時間実行オペレーションが開始されます。削除オペレーションが完了すると、[アクティビティのステータス] ウィンドウの [商品カタログ] リストに削除のステータスが表示されます。

注: 削除の完了後、ブランチのカタログデータのリストは自動更新されません。ブランチの更新されたリストを表示するには、ページを更新する必要があります。

Vertex AI Search for Commerce の在庫更新

このセクションでは、定期的な在庫更新を実行して Vertex AI Search for Commerce のパフォーマンスを最適化する方法について説明します。

リアルタイムストリーミング

在庫情報（価格、在庫状況）や、配送状況や店舗固有の価格設定などの店舗レベルの詳細などの動的データの場合、Vertex AI Search for commerce ではリアルタイムストリーミングのみがオプションとなります。
この違いが生じるのは、比較的静的な商品カタログデータと比較して、在庫の変動が頻繁に発生するためです。商品の在庫状況は 1 日に何度も変化する可能性がありますが、説明や属性は比較的変化しません。
店舗レベルの更新頻度は、小売店の数が増えるほど高くなります。

非同期更新

この急速な変化に対応するため、Vertex AI Search for Commerce では、ジョブ ID を返す API を使用して非同期の在庫更新を行っています。
ジョブのステータスがポーリングされて確認されるまで、更新プロセスは完了したと見なされません。これにより、数秒から数分の遅延が発生する可能性があります。

順序が異なる更新

このシステムの注目すべき機能は、対応する商品がカタログに取り込まれる前に在庫情報を更新できることです。これは、小売業者内で在庫データパイプラインと商品データパイプラインが個別に動作し、商品カタログが更新される前に在庫情報が利用可能になることがあるという一般的なシナリオに対応するものです。在庫を更新する際は、allowMissing オプションを使用して、在庫と商品の更新順序が異なる場合を処理します。
Vertex AI Search for Commerce では、在庫の更新をカタログの取り込みより先に行うことができるため、このようなパイプラインの不一致に対応し、新しく導入された商品についても正確な在庫データを利用できるようにします。
ただし、商品の在庫情報は 24 時間保持され、その期間内に一致する商品が取り込まれない場合は削除されます。このメカニズムにより、データの整合性が確保され、古い在庫情報がシステムに保持されるのを防ぐことができます。

Vertex AI Search for Commerce で堅牢な A/B テストを行うための商品カタログの事前チェック

このセクションでは、商品カタログデータに対して事前チェックを実行する方法について説明します。

カタログ更新のパリティの一貫性を確保する

Vertex AI Search for Commerce 内で A/B テストを実施する準備として、以前の（コントロール）カタログと Vertex AI Search for Commerce（テスト）カタログの厳密なパリティを維持することが重要です。この 2 つの間に不均衡があると、A/B テストに悪影響が及び、結果が偏ったり、無効になったりする可能性があります。たとえば、商品の在庫状況や価格の不一致、属性のわずかな違いでも、テストデータに意図しないバイアスが生じる可能性があります。
このリスクを軽減するには、コントロールカタログとテストカタログの両方で並行更新プロセスを設計し、可能な限り順次更新を避けることが不可欠です。目標は、両方のカタログが同期している時間を最大化することです。一方、シリアル更新では、一方のレーンで遅延が発生する可能性があります。このような遅延により、一時的にカタログの不一致が発生し、あるカタログでは商品が在庫ありでも、別のカタログでは在庫なしになることがあります。また、新しく追加された商品が一方のカタログにはすぐに表示されるが、もう一方のカタログには表示されない場合もあります。このような差異は、ユーザーの行動、クリック数、購入数に大きな影響を与え、最終的には不公平な比較や不正確な A/B テストの結果につながる可能性があります。
並列更新を優先し、カタログのパリティの一貫性を維持することで、小売業者は Vertex AI Search for Commerce 内で A/B テストの公平性を確保できます。このアプローチにより、テスト結果の公平で偏りのない分析が可能になり、信頼性の高い分析情報と情報に基づいた意思決定につながります。

カタログデータのパリティを実現する

e コマース検索モデルの商品理解の深さと精度は、基盤となる商品カタログ情報の豊富さと品質に左右されます。カタログ内の商品データが包括的であるほど、モデルは商品を効果的に理解して分類できるようになります。
そのため、A/B テストの準備として、従来の（コントロール）カタログと Vertex AI Search for Commerce（テスト）カタログの両方にアップロードされた商品データが同一であることを確認することが不可欠です。この 2 つの環境間で商品情報に不一致があると、A/B テストの結果に大きな偏りが生じる可能性があります。
たとえば、従来の検索エンジンが Vertex AI Search for Commerce よりも豊富なカタログを利用できる場合、不公平な優位性が生まれます。Vertex AI Search for Commerce カタログに情報がないと、商品の理解と分類に重大な影響を及ぼす可能性があります。その結果、検索結果が不正確になったり、パフォーマンスの比較が誤解を招く可能性があります。このような差異を外部ツールで検出することは難しく、多くの場合、両方のカタログを綿密に手動で検査する必要があります。
両方のカタログに同じ商品データが同じ詳細レベルで含まれていることを確認することで、小売業者は Vertex AI Search for Commerce で A/B テストを行うための公平な環境を構築できます。このアプローチにより、2 つの検索エンジンを公平かつ偏りなく比較し、それぞれのパフォーマンスと機能を正確に評価できます。

障害復旧計画

適切に準備された障害復旧計画により、コマース検索機能が運用可能で応答性を維持し、顧客体験と収益創出への影響を最小限に抑えることができます。このプランでは、根本原因に関係なく、カタログとユーザーイベントの取り込みパイプラインの潜在的な障害に対処するために、カタログを迅速に復元できるようにする必要があります。

BigQuery をデータステージングに使用すると、障害復旧において明確な利点があります。Vertex AI Search for Commerce 内の現在のカタログまたはユーザーイベントのデータが、BigQuery に保存されている最新のスナップショットと大幅に異なるものでない場合、インポート API を呼び出すことで迅速な復元を開始できます。このアプローチにより、ダウンタイムを最小限に抑え、検索機能の運用を維持できます。

逆に、BigQuery がデータパイプラインに統合されていない場合は、既知の良好な状態からカタログを迅速に再読み込みするための代替メカニズムを導入する必要があります。これらのメカニズムには、バックアップシステム、データレプリケーション、その他のフェイルオーバー戦略が含まれます。

これらの障害復旧の考慮事項を Vertex AI Search for Commerce アーキテクチャに組み込むことで、システムの堅牢性を強化し、予期しない中断が発生した場合でもビジネスの継続性を維持できます。

高可用性を計画する

商品カタログを Vertex AI Search にアップロードする際は、さまざまな Google Cloud サービスが地域性をどのように処理するかを考慮して、復元力のあるデータ取り込みパイプラインを設計することが重要です。

Dataflow を使用して障害復旧対応の取り込みパイプラインを構築するには、次のいずれかの設計を使用して、複数のリージョンにジョブをデプロイします。

アクティブ/アクティブ: 複数のリージョンの Dataflow インスタンスが、データを同時にアクティブに処理します。
アクティブ/パッシブ: 1 つのリージョンの Dataflow インスタンスがアクティブになり、他のリージョンのインスタンスはスタンバイ状態のままになります。

Pub/Sub と Dataflow を使用してこれらの設計を実装する方法は次のとおりです。

グローバルサービス: Pub/Sub などの一部のサービスはグローバルに動作します。 Google Cloud は、特定のサービスレベル契約（SLA）に従って可用性を管理します。
リージョンサービス: Dataflow など、データを変換して Vertex AI Search に取り込むために使用する可能性のある他のサービスはリージョンです。高可用性と障害復旧のためにこれらのコンポーネントを構成するのは、お客様の責任です。

たとえば、BigQuery を使用してデータを永続化する場合、マルチリージョンになるように構成できます。これにより、データの冗長性と可用性が Google Cloudによって自動的に処理されます。同様に、Cloud Storage を使用する場合も、マルチリージョンに構成できます。

アクティブ/アクティブ設計

アクティブ/アクティブ設計では、Pub/Sub メッセージ属性とサブスクリプションフィルタを使用して、特定のリージョンでアクティブな Dataflow ジョブによって各メッセージが 1 回だけ処理されるようにします。

メッセージ属性を追加する: 商品の更新などのメッセージを Pub/Sub トピックにパブリッシュするときに、対象地域を示す属性を含めます。次に例を示します。
- region: us-central1
- region: us-east1
サブスクリプションフィルタを構成する: 各リージョン Dataflow パイプラインで、メッセージフィルタを使用して、リージョンに一致するメッセージのみを pull するように Pub/Sub サブスクリプションを構成します。たとえば、us-central1 Dataflow ジョブのサブスクリプションには、attributes.region = "us-central1" などのフィルタが設定されます。
フェイルオーバー: リージョンが使用できなくなった場合は、アップストリームパブリッシングシステムを更新して、すべての新しいメッセージに正常なリージョンの属性をタグ付けします。これにより、メッセージ処理がフェイルオーバーリージョンの Dataflow インスタンスに再ルーティングされます。

アーキテクチャで使用される複数のコンポーネントは、デフォルトでマルチリージョンになるように構成できます。たとえば、BigQuery を使用してデータを永続化する場合、マルチリージョンとして構成することで、データの冗長性と可用性を Cloud Storage で自動的に処理できます。同様に、Cloud Storage を使用する場合も、マルチリージョンとして構成できます。

アクティブ/パッシブ設計

この設計では、常に 1 つのリージョン Dataflow パイプラインのみが Pub/Sub からメッセージをアクティブに pull します。

1 つのサブスクリプションを関連付ける: アクティブ リージョンの Dataflow ジョブの Pub/Sub サブスクリプションのみが関連付けられ、メッセージを pull していることを確認します。パッシブリージョンの Dataflow ジョブのサブスクリプションは作成されますが、切り離されたままになります。
フェイルオーバー: アクティブリージョンで障害が発生した場合、手動またはプログラムで次の操作を行います。
- 失敗したリージョンの Dataflow ジョブに関連付けられている Pub/Sub サブスクリプションを切り離します。
- パッシブ（スタンバイ）リージョンのいずれかで Dataflow ジョブに関連付けられた Pub/Sub サブスクリプションを関連付けます。

これにより、メッセージ処理の負荷が新しくアクティブ化されたリージョンに転送されます。

復元力とフォレンジック

データ取り込みの設計で BigQuery を使用すると、復元力を処理し、フォレンジックとデバッグの機能を作成できます。patch API と addLocalInventory API を使用して直接取り込まれた商品と在庫は、データが Vertex AI Search for Commerce に送信されるときに、商品と在庫の更新のトレイルが残らないことを意味します。お客様から、商品が想定どおりに表示されない理由についてお問い合わせを受けることがあります。BigQuery で構築されたステージングエリアにデータの完全な履歴があると、このような調査とデバッグが容易になります。

リファレンスアーキテクチャ

このアーキテクチャでは、通常、データ取り込みに、BigQuery 上に構築された未加工、キュレート、使用の各ステージがあります。システムは、Dataflow を使用してステージ間でデータを移動し、クラウドワークフローを使用してこれらすべてを自動化するようにオーケストレートします。

システムは生データをそのまま取得し、履歴を維持するためにタイムタグを付けます。このデータは変更されていないため、お客様は真のソースと見なします。
その後、システムはデータをキュレーションステージに変換し、再度タイムタグを付けます。これにより、変換されたタイミングと、失敗したかどうかをお客様が把握できるようになります。
最後に、システムは、システムが以前にデータにタグ付けした時間を使用して、キュレートされたデータの消費ステージでビューを作成します。これにより、最終的に Vertex AI Search for Commerce に取り込まれる変換済みデータを顧客が正確に把握できるようになります。

ブランチ 0、ブランチ 1、ブランチ 2 は、ライブバックアップ、1 日前のバックアップ、1 週間前のバックアップブランチとして機能します。ブランチ 0 に直接取り込まれたデータは、毎日ブランチ 1 に、毎週ブランチ 2 に集計されてインデックス登録されます。これにより、データの破損をロールバックして、ビジネスの継続性とシステムの復元力を高めることができます。

また、データの履歴とリネージ全体がグローバル BigQuery データセットに保持されるため、分析とデバッグを行うことができます。

カタログの取り込みでコーナーケースを計画する

Vertex AI Search for Commerce のカタログ取り込みのコアメカニズムが確立されたら、さまざまなコーナーケースに対する復元力を評価する積極的なアプローチを行います。これらのシナリオの一部は、特定のビジネス要件にすぐには関連しないかもしれませんが、バックエンド設計に組み込むことで、将来にわたって価値のある保護を提供できます。

この準備ステップでは、データパイプラインが予期しないシナリオやエッジケースのシナリオを処理できるかどうかを確認し、堅牢性と進化する要求への適応性を確保します。潜在的な課題を予測して事前に対処することで、将来の混乱を軽減し、商品データが小売検索システムにシームレスに流れ込むように維持できます。

これを実現するには、Dataflow ロジックを次のように構築する必要があります。

適切なスキーマに一致するように、生データの各項目を検証します。生データのコントラクトは事前に決定し、すべてのデータ要素を常にコントラクトと照合する必要があります。検証に失敗した場合、未加工のデータ要素にタイムタグを付け、フォレンジック用の実際のエラーとともに BigQuery の失敗した未加工テーブルに保存する必要があります。

このような障害の例としては、次のようなものがあります。
- 契約に含まれていない特定の属性が、突然生データ要素に表示される。
- 特定の必須属性が元データ要素に存在しません。
変換のために、未加工データの各項目を Vertex AI Search for Commerce 形式で検証します。Vertex AI Search for Commerce で商品の取り込みに必要な必須フィールドがいくつかあります。これで、生データのすべての要素が、Vertex AI Search for Commerce スキーマ形式に正常に変換できるかどうかを再度確認する必要があります。変換が失敗した場合は、未加工のデータ要素にタイムタグを付けて、BigQuery の失敗したキュレーションテーブルに保存する必要があります。このテーブルには、フォレンジックに役立つ実際のエラーメッセージが含まれます。

このような障害の例としては、次のようなものがあります。
- 価格などの特定の属性は、元のデータ要素が英数字であるため、数値にフォーマットできません。
- 商品名が完全に欠落している。

この例は、デバッグ用にすべての障害を保持する BigQuery テーブルスキーマのサンプルを示しています。

BigQuery テーブルスキーマのサンプルを表示する

[
    {
      "mode": "REQUIRED",
      "name": "ingestedTimestamp",
      "type": "TIMESTAMP"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadString",
      "type": "STRING"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadBytes",
      "type": "BYTES"
    },
    {
      "fields": [
        {
          "mode": "NULLABLE",
          "name": "key",
          "type": "STRING"
        },
        {
          "mode": "NULLABLE",
          "name": "value",
          "type": "STRING"
        }
      ],
      "mode": "REPEATED",
      "name": "attributes",
      "type": "RECORD"
    },
    {
      "mode": "NULLABLE",
      "name": "errorMessage",
      "type": "STRING"
    },
    {
      "mode": "NULLABLE",
      "name": "stacktrace",
      "type": "STRING"
    }
  ]

ストレステストとスケーラビリティ

ストレステストとスケーラビリティにより、大量のイベントと成長に備えます。

トラフィックの多いイベント

祝日などのトラフィックの多いイベントは、データ取り込みパイプラインにとって大きな課題となります。在庫状況（在庫レベルや価格など）の更新の急増や、商品属性の変更の可能性に対応するには、堅牢なインフラストラクチャが必要です。取り込みシステムがこの負荷の増加に対応できるかどうかを評価することが重要です。ピーク時のトラフィックパターンを再現した負荷テストをシミュレートすることで、ボトルネックを特定し、重要な期間中のスムーズな運用を確保します。

期間限定セール

期間限定セールは、期間が短く、在庫が急速に変動するため、独自の課題が生じます。検索結果と実際の在庫状況の不一致を防ぐには、リアルタイムの在庫同期を確保することが重要です。この設定を怠ると、人気商品が実際には売り切れているのに在庫ありと表示されたり、その逆のことが起こったりするなど、お客様に不快な思いをさせてしまう可能性があります。また、フラッシュセール中の価格変更は商品のランキングに大きな影響を与える可能性があるため、検索インデックスで正確かつタイムリーな価格更新を行う必要があります。

カタログの拡張

ビジネスの成長や商品ラインの拡大により、カタログ内の商品数が 5 倍や 10 倍に急増することがあります。取り込みアーキテクチャは、この増加にシームレスに対応できるようにスケーラブルである必要があります。新しいデータソースや商品情報の形式が導入された場合は、特に ETL（抽出、変換、読み込み）パイプライン全体を見直す必要が生じる可能性があります。

これらの潜在的なシナリオに事前に対処することで、トラフィックの急増、フラッシュセール、カタログの大幅な増加が発生した場合でも、Vertex AI Search for Commerce の取り込みパイプラインの堅牢性、スケーラビリティ、応答性を維持できます。この積極的なアプローチにより、検索結果の正確性と信頼性が確保され、ユーザーエクスペリエンスの向上とビジネスの成功につながります。

データ取り込みパイプラインのパフォーマンスを評価し、次の指標のベースラインを形成する必要があります。

カタログと在庫のデータ全体を公開して取り込むには、どのくらいの時間がかかりますか？BFCM 期間中は、カタログ全体の価格が大幅に変動する可能性があるため、必要に応じてこの設定が必要になることがあります。
1 つの商品の更新が反映されるまでにどれくらいの時間がかかりますか？
システムが処理できる商品と在庫の更新率の最大値はどれくらいですか？

ボトルネック

パイプラインが正しくスケールアップおよびスケールダウンできるかどうかを評価して確認します。
インスタンス数の最大上限が高すぎるか低すぎるかを判断します。
HTTP コード 429 を確認して、システムが Vertex AI Search for Commerce によってレート制限されているかどうかを判断します。
レート制限を減らすために特定の API 割り当てを増やす必要があるかどうかを確認します。

カタログの取り込み用の商品データ構造

このセクションでは、カタログの取り込み用に商品データを準備する方法について説明します。

プライマリ商品

メイン商品は、バリエーション商品をグループ化するためのコンテナとして、また検索グリッドのエントリとして機能します。バリエーション間で共有される共通の属性のみが、プライマリ商品に指定されている。たとえば、次のようなものが挙げられます。

メイン商品 ID
商品 ID（メイン商品 ID と同じ）
タイトル
説明

詳しくは、商品属性についてをご覧ください。

バリエーション商品

バリエーション商品は、プライマリ商品から共通の属性を継承しますが、固有の値を指定することもできます。

必須属性には以下が含まれます。

メイン商品に指定されたすべての属性（タイトル、商品説明）。価格、タイトル、説明はメインの商品と異なる場合があります。
特定のバリエーション属性（色、サイズ、その他の関連する商品のバリエーション）。

詳しくは、商品属性についてをご覧ください。

属性の取得

検索プロセスでは、メイン商品とバリエーション商品の両方の検索可能な属性がすべて考慮されます。

検索結果でのバリエーションの一致

バリエーション一致（「青いワンピース」など）では、色やサイズなどの事前定義されたバリエーション属性に基づいて結果がフィルタされます。検索結果では、各プライマリプロダクトに対して最大 5 つの一致するバリエーションが返されます。

Merchant Center を Vertex AI Search for Commerce に同期する

Merchant Center は、ショッピング広告やその他の Google サービスで店舗と商品データが利用できるようになるツールです。

Merchant Center と Vertex AI Search for Commerce 間の同期を継続的に実施するには、Merchant Center アカウントを Vertex AI Search for Commerce にリンクします。

Vertex AI Search for Commerce の Merchant Center 同期を設定する場合は、Merchant Center で 管理者 IAM ロールが割り当てられている必要があります。標準アクセスロールでは Merchant Center フィードの読み取りは許可されますが、Merchant Center を Vertex AI Search for Commerce に同期しようとすると、エラーメッセージが表示されます。そのため、Merchant Center を Vertex AI Search for Commerce と正常に同期するには、ロールをアップグレードする必要があります。

Merchant Center アカウントをリンクする

Vertex AI Search for Commerce は Merchant Center アカウントにリンクされていますが、Merchant Center アカウントの商品データへの変更は、Vertex AI Search for Commerce で数分以内に自動的に更新されます。Merchant Center の変更が Vertex AI Search for Commerce に同期されないようにするには、Merchant Center アカウントとのリンクを解除します。

Merchant Center アカウントのリンクを解除しても、Vertex AI Search for Commerce の商品は削除されません。インポートされた商品を削除するには、商品情報を削除するをご覧ください。

Merchant Center アカウントを同期するには、次の手順を行います。

Merchant Center アカウントを同期する

Cloud コンソール

Search for commerce コンソールの [データ] ページに移動します。

[データ] ページに移動
[Import] をクリックして [Import] パネルを開きます。
[商品カタログ] を選択します。
データソースとして [Merchant Center の同期] を選択します。
Merchant Center アカウントを選択します。アカウントが表示されない場合は、[ユーザーアクセス] をオンにします。
省略可: [Merchant Center フィードフィルタ] を選択して、選択したフィードからの商品のみをインポートします。

指定しない場合、すべてのフィード（今後のフィードを含む）から商品がインポートされます。
省略可: 特定の国または言語をターゲットとする商品のみをインポートするには、[詳細設定を表示] を展開して、フィルタする Merchant Center の販売先の国と言語を選択します。
カタログのアップロード先のブランチを選択します。
[インポート] をクリックします。

curl

ローカル環境のサービスアカウントが、Merchant Center アカウントと Vertex AI Search for commerce の両方にアクセスできることを確認します。Merchant Center アカウントにアクセスできるアカウントを確認するには、Merchant Center のユーザーアクセスをご覧ください。
MerchantCenterAccountLink.create メソッドを使用してリンクを確立します。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
  "merchantCenterAccountId": MERCHANT_CENTER_ID,
  "branchId": "BRANCH_ID",
  "feedFilters": [
    {"dataSourceId": DATA_SOURCE_ID_1}
    {"dataSourceId": DATA_SOURCE_ID_2}
  ],
  "languageCode": "LANGUAGE_CODE",
  "feedLabel": "FEED_LABEL",
 }' \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
```
- MERCHANT_CENTER_ID: Merchant Center アカウントの ID。
- BRANCH_ID: リンクを確立するブランチの ID。指定できる値は「0」、「1」、「2」です。
- LANGUAGE_CODE: （省略可）インポートする商品の 2 文字の言語コード。Merchant Center の商品の Language 列に表示されます。設定しない場合、すべての言語がインポートされます。
- FEED_LABEL: （省略可）インポートする商品のフィードラベル。フィードラベルは、Merchant Center の商品の [フィードラベル] 列で確認できます。設定しない場合、すべてのフィードラベルがインポートされます。
- FEED_FILTERS: （省略可）商品をインポートするメインフィードのリスト。フィードを選択しないと、すべての Merchant Center アカウントのフィードが共有されます。この ID は Content API データフィードリソース、または、Merchant Center にアクセスして、フィードを選択し、サイト URL の afmDataSourceId パラメータからフィード ID を取得することで確認できます。例: mc/products/sources/detail?a=MERCHANT_CENTER_ID&afmDataSourceId=DATA_SOURCE_ID。

リンクされた Merchant Center を表示するには、Search for commerce コンソールの [データ] ページに移動し、ページの右上にある [Merchant Center] ボタンをクリックします。[リンクされている Merchant Center アカウント] パネルが開きます。このパネルから Merchant Center アカウントを追加することもできます。

インポートされた商品を表示する手順については、カタログの集計情報を表示するをご覧ください。

Merchant Center アカウントのリンクの一覧を取得する

Cloud コンソール

Search for commerce コンソールの [データ] ページに移動します。

[データ] ページに移動
ページの右上にある [Merchant Center] ボタンをクリックして、リンクされた Merchant Center アカウントのリストを開きます。

curl

MerchantCenterAccountLink.list メソッドを使用して、リンクリソースを一覧取得します。

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

Merchant Center アカウントのリンクを解除する

Merchant Center アカウントをリンク解除すると、そのアカウントでは、カタログデータの Vertex AI Search for Commerce との同期が停止されます。この手順では、すでにアップロード済みの Vertex AI Search for Commerce 内の商品は削除されません。

Cloud コンソール

Search for commerce コンソールの [データ] ページに移動します。

[データ] ページに移動
ページの右上にある [Merchant Center] ボタンをクリックして、リンクされた Merchant Center アカウントのリストを開きます。
リンクを解除する Merchant Center アカウントの横にある [Unlink] をクリックし、表示されるダイアログで選択を確定します。

curl

MerchantCenterAccountLink.delete メソッドを使用して、MerchantCenterAccountLink リソースを削除します。

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

Merchant Center へのリンクに関する制限事項

Merchant Center アカウントは、任意の数のカタログブランチにリンクできますが、1 つのカタログブランチは 1 つの Merchant Center アカウントにのみリンクできます。
Merchant Center アカウントはマルチクライアントアカウント（MCA）にすることはできません。ただし、個々のサブアカウントをリンクすることはできます。
Merchant Center アカウントをリンクした後、最初のインポートの完了には数時間かかる場合があります。かかる時間は、Merchant Center アカウントのオファーの数によって異なります。
API メソッドで、Merchant Center アカウントにリンクされたブランチの商品は変更できません。そうしたブランチ内の商品カタログデータの変更は、Merchant Center を使用して行う必要があります。そうすると、その変更は、Vertex AI Search for Commerce に自動的に同期されます。
コレクション商品タイプは、Merchant Center リンクを使用するブランチではサポートされていません。
データの精度を確保するため、Merchant Center アカウントは空のカタログブランチにのみリンクできます。カタログブランチから商品を削除するには、商品情報を削除するをご覧ください。

BigQuery からカタログデータをインポート

カタログデータを BigQuery から正しい形式でインポートするには、コマース向け Vertex AI Searchl のスキーマを使用して、正しい形式で BigQuery テーブルを作成し、カタログデータで空のテーブルを読み込みます。次に、データを Vertex AI Search for Commerce にアップロードします。

BigQuery テーブルの詳細については、テーブルの概要をご覧ください。BigQuery クエリについては、BigQuery データのクエリの概要をご覧ください。

このタスクを Cloud Shell エディタで直接行う際の順を追ったガイダンスについては、[ガイドを表示] をクリックしてください。

ガイドを表示

カタログをインポートするには、次のようにします。

BigQuery データセットが別のプロジェクトにある場合は、Vertex AI Search for commerce が BigQuery データセットにアクセスできるように、必要な権限を構成します。詳細
カタログデータを Vertex AI Search for Commerce にインポートします。
Cloud コンソール
1. Search for commerce コンソールの [データ] ページに移動します。
  
  [データ] ページに移動
2. [Import] をクリックして [Import] パネルを開きます。
3. [商品カタログ] を選択します。
4. データソースとして BigQuery を選択します。
5. カタログのアップロード先のブランチを選択します。
6. [Retail 商品カタログスキーマ] を選択します。これは、Vertex AI Search for Commerce の商品スキーマです。
7. データが配置される BigQuery テーブルを入力します。
8. 省略可: [詳細設定を表示] で、データの一時的なロケーションとして、プロジェクト内の Cloud Storage バケットのロケーションを入力します。
  
  指定しないと、デフォルトのロケーションが使用されます。指定する場合、BigQuery と Cloud Storage バケットは同じリージョン内に存在する必要があります。
9. 検索が有効ではなく、Merchant Center スキーマを使用している場合は、商品レベルを選択します。
  
  初めてカタログをインポートする場合や、またはカタログを完全に削除した後、カタログを再インポートする場合は、商品レベルを選択する必要があります。商品レベルの詳細をご覧ください。データをインポートした後に商品レベルを変更するには、かなりの手間がかかります。
  
  重要: バージョンとして取り込まれた商品カタログを含むプロジェクトに対して検索を有効にすることはできません。
10. [インポート] をクリックします。
curl
1. カタログをはじめてアップロードする場合や、カタログを消去した後にカタログを再インポートする場合は、Catalog.patch メソッドを使用してプロダクトレベルを設定します。この操作を行うには、販売店管理者のロールが必要です。
  - ingestionProductType: primary（デフォルト）と variant の値をサポートします。
  - merchantCenterProductIdField: offerId と itemGroupId の値をサポートします。Merchant Center を使用しない場合は、このフィールドを設定する必要はありません。
  curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data '{ "productLevelConfig": { "ingestionProductType": "PRODUCT_TYPE", "merchantCenterProductIdField": "PRODUCT_ID_FIELD" } }' \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"
2. インポートの入力パラメータのデータファイルを作成します。
  
  BigQuery データセットを指定するには、BigQuerySource オブジェクトを使用します。
  - DATASET_ID: BigQuery データセットの ID。
  - TABLE_ID: データを保持する BigQuery テーブルの ID。
  - PROJECT_ID: BigQuery ソースが存在するプロジェクト ID。指定しない場合、プロジェクト ID は親リクエストから継承されます。
  - STAGING_DIRECTORY: 省略可。データが Cloud Storage にインポートされる前にデータの暫定的な保存場所として使用される Cloud Storage ディレクトリ。一時ディレクトリを自動的に作成するには、このフィールドを空のままにします（推奨）。
  - ERROR_DIRECTORY: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ。一時ディレクトリを自動的に作成するには、このフィールドを空のままにします（推奨）。
  - dataSchema: For the dataSchema プロパティには、値 product（デフォルト）を使用します。Vertex AI Search for Commerce スキーマを使用します。
  新しいステージングディレクトリとエラーディレクトリを含む Cloud Storage バケットを自動的に作成できるように、ステージングディレクトリまたはエラーディレクトリを指定しないことをおすすめします。これらのディレクトリは BigQuery データセットと同じリージョンに作成され、インポートごとに一意になります（これにより、複数のインポートジョブでデータを同じディレクトリにステージングしないようにでき、同じデータを再インポートしなくてすむ可能性があります）。3 日後に、バケットとディレクトリは自動的に削除され、ストレージの費用を削減できます。
  
  自動的に作成されるバケット名には、プロジェクト ID、バケットリージョン、およびデータスキーマ名が含まれ、アンダースコアで区切られます（例: 4321_us_catalog_retail）。自動的に作成されるディレクトリは、staging または errors と呼ばれ、番号が付加されます（例: staging2345、errors5678）。
  
  ディレクトリを指定する場合は、Cloud Storage バケットが BigQuery データセットと同じリージョン内にあることが必要です。それ以外の場合は、インポートが失敗します。ステージングディレクトリとエラーディレクトリを gs://<bucket>/<folder>/ という形式で指定します。これらのディレクトリは異なっている必要があります。
  { "inputConfig":{ "bigQuerySource": { "projectId":"PROJECT_ID", "datasetId":"DATASET_ID", "tableId":"TABLE_ID", "dataSchema":"product"} } }
3. カタログ情報をインポートするには、Products:import REST メソッドに対して POST リクエストを実行し、データファイルの名前を指定します（ここでは、input.json）。
  curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" -d @./input.json \ "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"
  API を使用して、プログラムでステータスを確認できます。次のようなレスポンスオブジェクトが返されます。
  { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456", "done": false }
  名前の項目は、オペレーションオブジェクトの ID です。このオブジェクトのステータスをリクエストするには、done 項目が true として返されるまで、名前の項目を import メソッドで返される値に置き換えます。
  curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456"
  オペレーションが完了すると、返されたオブジェクトは true の done 値を持ち、次の例のような Status オブジェクトが含まれます。
  { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456", "metadata": { "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata", "createTime": "2020-01-01T03:33:33.000001Z", "updateTime": "2020-01-01T03:34:33.000001Z", "successCount": "2", "failureCount": "1" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse", }, "errorsConfig": { "gcsPrefix": "gs://error-bucket/error-directory" } }
  Cloud Storage のエラーディレクトリ内のファイルを調べて、インポート中にエラーが発生したかどうかを確認できます。

BigQuery データセットへのアクセス権を設定する

BigQuery データセットが Vertex AI Search for Commerce サービスとは異なるプロジェクトにある場合にアクセスを設定するには、次の手順を行います。

Google Cloud コンソールで [IAM] ページを開きます。

[IAM] ページを開く
Vertex AI Search for Commerce プロジェクトを選択します。
Retail サービスアカウント という名前のサービスアカウントを探します。

以前にインポートオペレーションを開始していない場合、このサービスアカウントは表示されない可能性があります。このサービスアカウントが表示されない場合は、インポートタスクに戻ってインポートを開始します。権限エラーで失敗した場合は、ここに戻ってこのタスクを完了してください。
メールアドレスのようなサービスアカウントの ID（例: service-525@gcp-sa-retail.iam.gserviceaccount.com）をコピーします。
（同じ [IAM と管理] ページで）BigQuery プロジェクトに切り替え、 [アクセスを許可] をクリックします。
[新しいプリンシパル] で、Vertex AI Search for Commerce サービスアカウントの ID を入力し、[BigQuery] > [BigQuery ユーザー] ロールを選択します。
[別のロールを追加] をクリックし、[BigQuery] > [BigQuery データ編集者] を選択します。

プロジェクト全体でデータ編集者のロールを指定したくない場合は、このロールをデータセットに直接追加できます。詳細
[保存] をクリックします。

商品スキーマ

BigQuery からカタログをインポートするときは、次のコマース向け Vertex AI Search 商品スキーマを使用して、正しい形式の BigQuery テーブルを作成し、カタログデータとともに読み込みます。それから、カタログをインポートします。

Vertex AI Search for Commerce の商品スキーマを表示する

[
  {
    "name": "name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "id",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "type",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "primaryProductId",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "collectionMemberIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "gtin",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "categories",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "title",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "brands",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "description",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "languageCode",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "key",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "value",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          },
          {
            "name": "numbers",
            "type": "FLOAT",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "tags",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "priceInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "currencyCode",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "price",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "originalPrice",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "cost",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "priceEffectiveTime",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "priceExpireTime",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "rating",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "ratingCount",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "averageRating",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "ratingHistogram",
        "type": "INTEGER",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "expireTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "ttl",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "seconds",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "availableTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availability",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availableQuantity",
    "type": "INTEGER",
    "mode": "NULLABLE"
  },
  {
    "name": "fulfillmentInfo",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "type",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "placeIds",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "uri",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "images",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "uri",
        "type": "STRING",
        "mode": "REQUIRED"
      },
      {
        "name": "height",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "width",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "audience",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "genders",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "ageGroups",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "colorInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "colorFamilies",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "colors",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "sizes",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "materials",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "patterns",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "conditions",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "publishTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "promotions",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "promotionId",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

Cloud Storage からカタログデータをインポートする

JSON 形式でカタログデータをインポートするには、インポートするカタログデータを含む 1 つ以上の JSON ファイルを作成し、Cloud Storage にアップロードします。そこから、Vertex AI Search for Commerce にインポートできます。

JSON 商品アイテム形式の例については、商品アイテム JSON データ形式をご覧ください。

Cloud Storage へのファイルのアップロードについては、オブジェクトをアップロードするをご覧ください。

Vertex AI Search for Commerce サービスアカウントにバケットに対する読み取りと書き込みの権限があることを確認します。

コマース向け Vertex AI Search サービスアカウントは、 Google Cloud コンソールの [IAM] ページに Retail サービスアカウントという名前で表示されます。バケットの権限にアカウントを追加するときは、そのメールアドレスのようなサービスアカウントの ID（たとえば、service-525@gcp-sa-retail.iam.gserviceaccount.com）を使用します。
カタログデータをインポートします。
Cloud コンソール
1. Search for commerce コンソールの [データ] ページに移動します。
  
  [データ] ページに移動
2. [Import] をクリックして [Import] パネルを開きます。
3. データソースとして 商品カタログ を選択します。
4. カタログのアップロード先のブランチを選択します。
5. スキーマとして [Retail 商品カタログスキーマ] を選択します。
6. データの Cloud Storage のロケーションを入力します。
7. 検索が有効ではない場合は、商品レベルを選択します。
  
  初めてカタログをインポートする場合や、またはカタログを完全に削除した後、カタログを再インポートする場合は、商品レベルを選択する必要があります。商品レベルの詳細をご覧ください。データをインポートした後に商品レベルを変更するには、かなりの手間がかかります。
  
  重要: バージョンとして取り込まれた商品カタログを含むプロジェクトに対して検索を有効にすることはできません。
8. [インポート] をクリックします。
curl
1. カタログをはじめてアップロードする場合、またはカタログを消去した後にカタログを再インポートする場合は、Catalog.patch メソッドを使用して商品レベルを設定します。商品レベルの詳細をご覧ください。
  - ingestionProductType: primary（デフォルト）と variant の値をサポートします。
  - merchantCenterProductIdField: offerId と itemGroupId の値をサポートします。Merchant Center を使用しない場合は、このフィールドを設定する必要はありません。
  curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data '{ "productLevelConfig": { "ingestionProductType": "PRODUCT_TYPE", "merchantCenterProductIdField": "PRODUCT_ID_FIELD" } }' \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"
2. インポートの入力パラメータのデータファイルを作成します。GcsSource オブジェクトを使用して、Cloud Storage バケットを指定します。
  
  複数のファイルを指定することも、1 つを指定することもできます。この例では、2 つのファイルを使用します。
  - INPUT_FILE: カタログデータを含む Cloud Storage 内の 1 つまたは複数のファイル。
  - ERROR_DIRECTORY: インポートに関するエラー情報用の Cloud Storage ディレクトリ。
  入力ファイルのフィールドは gs://<bucket>/<path-to-file>/ の形式にする必要があります。エラーディレクトリは、gs://<bucket>/<folder>/ の形式にする必要があります。エラーディレクトリが存在しない場合は作成されます。バケットはすでに存在している必要があります。
  { "inputConfig":{ "gcsSource": { "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"] } }, "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"} }
3. カタログ情報をインポートするには、Products:import REST メソッドに対して POST リクエストを実行し、データファイルの名前を指定します（ここでは input.json として表示）。
  curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" -d @./input.json \ "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"
  インポートオペレーションのステータスを確認する最も簡単な方法は、 Google Cloud コンソールを使用することです。詳細については、特定の統合オペレーションのステータスを確認するをご覧ください。
  
  API を使用して、プログラムでステータスを確認できます。次のようなレスポンスオブジェクトが返されます。
  { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456", "done": false }
  名前の項目は、オペレーションオブジェクトの ID です。名前の項目を import メソッドによって返された値に置き換えて、done 項目が true として返されるまで、このオブジェクトのステータスをリクエストします。
  curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/[OPERATION_NAME]"
  オペレーションが完了すると、返されたオブジェクトは true の done 値を持ち、次の例のような Status オブジェクトが含まれます。
  { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456", "metadata": { "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata", "createTime": "2020-01-01T03:33:33.000001Z", "updateTime": "2020-01-01T03:34:33.000001Z", "successCount": "2", "failureCount": "1" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse" }, "errorsConfig": { "gcsPrefix": "gs://error-bucket/error-directory" } }
  Cloud Storage のエラーディレクトリにあるファイルを調べると、インポート中に発生したエラーの種類を確認できます。

インラインでカタログデータをインポートする

curl

カタログ情報をインラインでインポートするには、productInlineSource オブジェクトを使用して Products:import REST メソッドに対して POST リクエストを実行してカタログデータを指定します。

商品全体を 1 行で指定します。各候補は 1 行にまとめる必要があります。

JSON 商品アイテム形式の例については、商品アイテム JSON データ形式をご覧ください。

プロダクトの JSON ファイルを作成し、./data.json という名前を付けます。

{
"inputConfig": {
"productInlineSource": {
    "products": [
      { PRODUCT_1 }
      { PRODUCT_2 }
    ]
  }
}
}

POST メソッドを呼び出します。

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 --data @./data.json \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

Java

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

商品アイテム JSON データ形式

JSON ファイルの Product エントリは、次の例のようになります。

商品全体を 1 行で指定します。各候補は 1 行にまとめる必要があります。

最低限必要な項目:

      {
        "id": "1234",
        "categories": "Apparel & Accessories > Shoes",
        "title": "ABC sneakers"
      }
      {
        "id": "5839",
        "categories": "casual attire > t-shirts",
        "title": "Crew t-shirt"
      }

オブジェクト全体を表示する

      {
        "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
        "id": "1234",
        "categories": "Apparel & Accessories > Shoes",
        "title": "ABC sneakers",
        "description": "Sneakers for the rest of us",
        "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
        "language_code": "en",
        "tags": [ "black-friday" ],
        "priceInfo": {
          "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
        },
        "availableTime": "2020-01-01T03:33:33.000001Z",
        "availableQuantity": "1",
        "uri":"http://example.com",
        "images": [
          {"uri": "http://example.com/img1", "height": 320, "width": 320 }
        ]
      }
      {
        "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
        "id": "4567",
        "categories": "casual attire > t-shirts",
        "title": "Crew t-shirt",
        "description": "A casual shirt for a casual day",
        "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
        "language_code": "en",
        "tags": [ "black-friday" ],
        "priceInfo": {
          "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
        },
        "availableTime": "2020-02-01T04:44:44.000001Z",
        "availableQuantity": "2",
        "uri":"http://example.com",
        "images": [
          {"uri": "http://example.com/img2", "height": 320, "width": 320 }
        ]
      }

過去のカタログデータ

Vertex AI Search for Commerce は、過去のカタログデータのインポートと管理をサポートしています。過去のカタログデータは、モデルのトレーニングに過去のユーザーイベントを使用する場合に役立ちます。過去の商品情報を使用して、過去のユーザーイベントデータを拡充し、モデルの精度を向上させることができます。

過去のアイテムは期限切れのアイテムとして保存されます。検索レスポンスでは返されませんが、Update、List、Delete の API 呼び出しでは表示されます。

過去のカタログデータをインポートする

商品の expireTime フィールドが過去のタイムスタンプに設定されている場合、この商品は過去の商品と見なされます。おすすめに影響を与えないように、商品の在庫状況を OUT_OF_STOCK に設定します。

履歴カタログデータのインポートには、次の方法を使用することをおすすめします。

`Product.Create` メソッドを呼び出す

Product.Create メソッドを使用して、expireTime フィールドが過去のタイムスタンプに設定された Product エントリを作成します。

期限切れの商品をインラインでインポートする

手順はインラインインポートと同じですが、商品の expireTime フィールドを過去のタイムスタンプに設定する必要があります。

商品全体を 1 行で指定します。各候補は 1 行にまとめる必要があります。

インラインインポートリクエストで使用される ./data.json の例:

インラインインポートリクエストで使用されているこの例を表示する

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

BigQuery または Cloud Storage から期限切れの商品をインポートする

BigQuery からカタログデータをインポートするまたは Cloud Storage からカタログデータをインポートするで説明されている手順と同じ手順を使用します。ただし、expireTime フィールドは過去のタイムスタンプに設定してください。

カタログを最新の状態に保つ

最適な結果を得るには、カタログに最新の情報が含まれている必要があります。カタログを毎日インポートして、カタログが最新の状態であることを確認するようおすすめします。Google Cloud Scheduler を使用して、インポートをスケジュールできます。また、Google Cloud コンソールを使用してデータをインポートする場合は、自動スケジュールオプションを選択することもできます。

新しい、または変更された商品アイテムのみを更新する、あるいはカタログ全体をインポートすることができます。すでにカタログに掲載されている商品をインポートした場合、再び追加されることはありません。変更されたアイテムは更新されます。

単一の商品アイテムを更新するには、商品情報を更新するをご覧ください。

バッチアップデート

import メソッドを使用して、カタログを一括更新できます。これは初期インポートと同じです。カタログデータをインポートするの手順に従ってください。

インポート状態をモニタリングする

カタログの取り込みと健全性をモニタリングするには:

Search for commerce の [データ] ページの [カタログ] タブで、カタログの集計情報を表示して、アップロードされた商品をプレビューします。

[データ] ページに移動
[データ品質] ページで、検索結果の品質を改善し、検索パフォーマンス階層のロックを解除するために、カタログデータを更新する必要があるかどうかを評価します。

検索データの品質を確認して、検索パフォーマンス階層を表示する方法については、検索パフォーマンス階層をロック解除するをご覧ください。このページで使用可能なカタログ指標の概要については、カタログ品質指標をご覧ください。

[データ品質] ページに移動
データのアップロードで問題が発生した場合に通知されるアラートを作成するには、Cloud Monitoring アラートを設定するの手順に従ってください。

高品質の結果を得るには、カタログを最新の状態に保つことが重要です。アラートを使用してインポートのエラー率をモニタリングし、必要に応じて対処します。

カタログ情報をインポートする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

カタログのインポートに関する考慮事項

チュートリアル

動画チュートリアル

BigQuery からカタログをインポートするチュートリアル

Cloud Storage からカタログをインポートするチュートリアル

インラインでカタログデータをインポートするチュートリアル

カタログのインポートに関するベスト プラクティス

一括インポート、リアルタイム ストリーミング、またはその両方か？

カタログ管理のブランチ戦略

単一ブランチの更新

ブランチの切り替え

カタログ ブランチをパージする

Vertex AI Search for Commerce の在庫更新

リアルタイム ストリーミング

非同期更新

順序が異なる更新

Vertex AI Search for Commerce で堅牢な A/B テストを行うための商品カタログの事前チェック

カタログ更新のパリティの一貫性を確保する

カタログデータのパリティを実現する

障害復旧計画

高可用性を計画する

アクティブ/アクティブ設計

アクティブ/パッシブ設計

復元力とフォレンジック

リファレンス アーキテクチャ

カタログの取り込みでコーナー ケースを計画する

ストレステストとスケーラビリティ

トラフィックの多いイベント

期間限定セール

カタログの拡張

ボトルネック

カタログの取り込み用の商品データ構造

プライマリ商品

バリエーション商品

属性の取得

関連性スコア

検索結果でのバリエーションの一致

Merchant Center を Vertex AI Search for Commerce に同期する

Merchant Center アカウントをリンクする

Merchant Center アカウントを同期する

Cloud コンソール

curl

Merchant Center アカウントのリンクの一覧を取得する

Cloud コンソール

curl

Merchant Center アカウントのリンクを解除する

Cloud コンソール

curl

Merchant Center へのリンクに関する制限事項

BigQuery からカタログデータをインポート

Cloud コンソール

curl

BigQuery データセットへのアクセス権を設定する

商品スキーマ

Vertex AI Search for Commerce の商品スキーマを表示する

Cloud Storage からカタログデータをインポートする

Cloud コンソール

curl

インラインでカタログデータをインポートする

curl

Java

商品アイテム JSON データ形式

過去のカタログ データ

過去のカタログ データをインポートする

Product.Create メソッドを呼び出す

期限切れの商品をインラインでインポートする

BigQuery または Cloud Storage から期限切れの商品をインポートする

カタログを最新の状態に保つ

バッチ アップデート

インポート状態をモニタリングする

次のステップ

カタログ情報をインポートする

カタログのインポートに関するベストプラクティス

一括インポート、リアルタイムストリーミング、またはその両方か？

カタログブランチをパージする

リアルタイムストリーミング

リファレンスアーキテクチャ

カタログの取り込みでコーナーケースを計画する

過去のカタログデータ

過去のカタログデータをインポートする

`Product.Create` メソッドを呼び出す

バッチアップデート