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

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

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

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

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

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

ガイドを表示

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

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

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

ガイドを表示

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

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

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

ガイドを表示

始める前に

カタログ情報を読み込むには、事前に始める前にの手順、特にプロジェクトの設定、サービス アカウントの作成、ローカル環境へのサービス アカウントの追加を完了しておく必要があります。

インポートを実行するには、販売店管理者の IAM ロールが必要です。

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

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

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

  • どの商品または商品グループがプライマリで、どの商品がバリアントであるかを決定する際は、慎重に検討してください。データをアップロードする前に、商品レベルをご覧ください。

    データをインポートした後に商品レベルの構成を変更するには、かなりの労力が必要です。

    プライマリ アイテムは、検索結果またはレコメンデーションとして返されます。バリエーション アイテムは含まれません。

    たとえば、プライマリの SKU グループが「V ネックシャツ」の場合、レコメンデーション モデルは 1 つの V ネックシャツのアイテム、そしておそらくクルーネックのシャツとスクープネックのシャツを返します。ただし、バリアントは使用されず、各 SKU がプライマリの場合は、V ネックシャツのすべての色とサイズの組み合わせが、レコメンデーション パネルに個別のアイテムとして返されます: 「ブラウン V ネックシャツ、サイズ XL」「ブラウン V ネックシャツ、サイズ L」、「ホワイト V ネックシャツ、サイズ M」「ホワイト V ネックシャツ、サイズ S」

  • 商品アイテム インポートの上限を確認します。

    Cloud Storage からの一括インポートの場合、各ファイルのサイズは 2 GB 以下でなければなりません。1 回の一括インポート リクエストで一度に最大 100 個のファイルを含めることができます。

    インライン インポートの場合、一度にインポートできる商品アイテムは 5,000 個までです。

  • 必要なカタログ情報がすべて含まれていて、正しいことを確認します。

    プレースホルダの値は使用しないでください。

  • 可能な限り多くのオプションのカタログ情報を格納してください。

  • 特に Google Cloud コンソールを使用して収益指標を取得する予定がある場合は、すべてのイベントで単一の通貨が使用されていることを確認してください。小売業向け Vertex AI Search API では、カタログごとに複数の通貨を使用することはできません。

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

    理想的には、カタログは毎日更新する必要があります。定期的なカタログのインポートをスケジュール設定すると、時間の経過とともにモデルの品質が低下することを回避できます。Search for Retail コンソールを使用してカタログをインポートするときに、定期的な自動インポートをスケジュール設定できます。または、Google Cloud Scheduler を使用して、インポートを自動化することもできます。

  • まだインポートされていない商品アイテムのユーザー イベントを記録しないでください。

  • カタログ情報をインポートしたら、プロジェクトの Error Reporting とロギング情報を確認します。

    いくつかのエラーが予想されますが、エラーの数が多い場合は、確認して、エラーの原因となったプロセス上の問題を修正する必要があります。

カタログデータのインポートについて

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

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

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

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

Merchant Center の同期 説明 アカウントを小売業向け Vertex AI Search にリンクして、Merchant Center からカタログデータをインポートします。リンク後、Merchant Center のカタログデータの更新は小売業向け Vertex AI Search にリアルタイムで同期されます。
使うタイミング Merchant Center との統合がすでにある場合。
制限事項 スキーマのサポートが制限される。たとえば、商品コレクションは Merchant Center でサポートされていません。リンクが解除されるまで Merchant Center がデータの信頼できる情報源になるため、カスタム属性が必要な場合は Merchant Center のデータに追加する必要があります。

限定的な管理。Merchant Center からインポートする特定のフィールドまたは項目のセットを指定することはできません。Merchant Center に存在するすべての項目とフィールドがインポートされます。
BigQuery 説明 小売業向け Vertex AI Search スキーマまたは Merchant Center スキーマを使用する、以前に読み込まれた BigQuery テーブルからデータをインポートします。Google Cloud コンソールまたは curl を使用して実行できます。
使うタイミング 多数の属性を含む商品カタログがある場合 BigQuery のインポートでは、小売業向け Vertex AI Search スキーマが使用されます。このスキーマは、Key-Value カスタム属性など、他のインポート オプションよりも多くの商品属性を備えています。

大量のデータがある場合。BigQuery のインポートにはデータの上限はありません。

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

カタログ ブランチを削除する

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

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

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

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

    [データ] ページに移動

  2. [ブランチ名] フィールドでカタログ ブランチを選択します。

  3. [ブランチ名] フィールドの横にあるその他メニューから [ブランチを削除] を選択します。

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

  4. ブランチを入力し、[確定] をクリックしてブランチからカタログデータを削除します。

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

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

Merchant Center と Vertex AI Search for Retail の同期を継続的に実施するには、Merchant Center アカウントを Vertex AI Search for Retail にリンクします。リンクすると、Merchant Center アカウントのカタログ情報が直ちに小売業向け Vertex AI Search にインポートされます。

小売業向け Vertex AI Search の Merchant Center の同期を設定するときに、Merchant Center で管理者のロールが割り当てられている必要があります。標準アクセスロールでは、UI で Merchant Center フィードを読み取ることができますが、Merchant Center を小売業向け Vertex AI Search と同期しようとすると、エラー メッセージが表示されます。したがって、Merchant Center を小売業向け Vertex AI Search に正常に同期するには、それに応じてロールをアップグレードする必要があります。

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

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

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

コンソール

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

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

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

curl

  1. ローカル環境のサービス アカウントに、Merchant Center アカウントと Vertex AI Search for Retail の両方へのアクセス権があることを確認します。Merchant Center アカウントにアクセスできるアカウントを確認するには、Merchant Center のユーザー アクセスをご覧ください。

  2. 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": [
    {"primaryFeedId": PRIMARY_FEED_ID_1}
    {"primaryFeedId": PRIMARY_FEED_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 の dataSourceId パラメータからフィード ID を取得することで確認できます。例: mc/products/sources/detail?a=MERCHANT_CENTER_ID&dataSourceId=PRIMARY_FEED_ID。

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

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

Merchant Center アカウントのリンクを一覧表示します。

コンソール

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

    [データ] ページに移動

  2. ページの右上にある [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 アカウントをリンク解除すると、そのアカウントでは、カタログデータの小売業向け Vertex AI Search への同期が停止されます。この手順では、すでにアップロード済みの小売業向け Vertex AI Search の商品は削除されません。

コンソール

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

    [データ] ページに移動

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

  3. リンクを解除する 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 に自動的に同期されます。

  • コレクション商品タイプは、Merchant Center リンクを使用するブランチではサポートされていません。

  • Merchant Center アカウントは、データの正確性を確保するために、空のカタログ ブランチにのみリンクできます。カタログ ブランチから商品を削除するには、商品情報を削除するをご覧ください。

Merchant Center からカタログデータをインポートする

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

Merchant Center スキーマを使用すると、BigQuery から 1 回限りの手順として、Merchant Center からカタログデータを一括インポートできます（レコメンデーションのみ）。

Merchant Center からの一括インポート

Merchant Center からカタログデータをインポートするには、Search for Retail コンソールまたは products.import メソッドを使用します。一括インポートは 1 回限りの手順であり、レコメンデーションでのみサポートされています。

Merchant Center からカタログをインポートするには、次の手順を行います。

  1. Merchant Center の転送の手順を使用すると、Merchant Center から BigQuery への転送を設定できます。

    Google Merchant Center の商品テーブル スキーマを使用します。転送を毎日繰り返すように構成しますが、データセットの有効期限は 2 日にします。

  2. BigQuery データセットが別のプロジェクトにある場合、小売業向け Vertex AI Search が BigQuery データセットにアクセスできるように、必要な権限を構成します。詳細

  3. カタログデータを BigQuery から小売業向け Vertex AI Search にインポートします。

    コンソール

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

      [データ] ページに移動

    2. [Import] をクリックして [Import] パネルを開きます。

    3. [Product catalog] を選択します。

    4. データソースとして [BigQuery] を選択します。

    5. カタログのアップロード先のブランチを選択します。

    6. データスキーマとして [Merchant Center] を選択します。

    7. データが配置される BigQuery テーブルを入力します。

    8. 省略可: データの一時的なロケーションとしてプロジェクト内の Cloud Storage バケットのロケーションを入力します。

      指定しないと、デフォルトのロケーション‏が使用されます。指定する場合、BigQuery と Cloud Storage バケットは同じリージョン内に存在する必要があります。

    9. カタログデータの定期的なアップロードをスケジュール設定するかどうかを選択します。

    10. カタログをはじめてインポートする場合や、カタログを完全に削除した後にカタログを再インポートする場合は、商品レベルを選択します。商品レベルの詳細をご覧ください。

      データをインポートした後に商品レベルの構成を変更するには、かなりの労力が必要です。

    11. [インポート] をクリックします。

    curl

    1. カタログをはじめてアップロードする場合や、カタログを消去した後にカタログを再インポートする場合は、Catalog.patch メソッドを使用してプロダクト レベルを設定します。この操作を行うには、販売店管理者のロールが必要です。商品レベルの詳細をご覧ください。

      • ingestionProductType: primary（デフォルト）と variant の値をサポートします。
      • merchantCenterProductIdField: offerId（デフォルト）と itemGroupId の値をサポートします。Merchant Center を使用しない場合は、デフォルト値の offerId に設定します。
      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. Products.import メソッドを使用してカタログをインポートします。

      • DATASET_ID: BigQuery データセットの ID。
      • TABLE_ID: データを保持する BigQuery テーブルの ID。
      • STAGING_DIRECTORY: 省略可。データが Cloud Storage にインポートされる前にデータの暫定的な保存場所として使用される Cloud Storage ディレクトリ。一時ディレクトリを自動的に作成するには、このフィールドを空のままにします（推奨）。
      • ERROR_DIRECTORY: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ。一時ディレクトリを自動的に作成するには、このフィールドを空のままにします（推奨）。
      • dataSchema: dataSchema プロパティには、値 product_merchant_center を使用します。Merchant Center の商品テーブル スキーマをご覧ください。

      ステージング ディレクトリやエラー ディレクトリを指定しないことをおすすめします。これにより、新しいステージング ディレクトリとエラー ディレクトリを含む Cloud Storage バケットが自動的に作成できるようになります。これらのディレクトリは BigQuery データセットと同じリージョンに作成され、インポートごとに一意になります（これにより、複数のインポート ジョブでデータを同じディレクトリにステージングしないようにでき、同じデータを再インポートしなくてすむ可能性があります）。3 日後に、バケットとディレクトリは自動的に削除され、ストレージの費用を削減できます。

      自動的に作成されるバケット名には、プロジェクト ID、バケット リージョン、およびデータスキーマ名が含まれ、アンダースコアで区切られます（例: 4321_us_catalog_retail）。自動的に作成されるディレクトリは、staging または errors と呼ばれ、番号が付加されます（例: staging2345、errors5678）。

      ディレクトリを指定する場合は、Cloud Storage バケットが BigQuery データセットと同じリージョン内にあることが必要です。それ以外の場合は、インポートが失敗します。ステージング ディレクトリとエラー ディレクトリを gs://<bucket>/<folder>/ という形式で指定します。これらのディレクトリは異なっている必要があります。

      curl -X POST \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "inputConfig":{
            "bigQuerySource": {
              "datasetId":"DATASET_ID",
              "tableId":"TABLE_ID",
              "dataSchema":"product_merchant_center"
            }
          }
      }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

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

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

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

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

ガイドを表示

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

  1. BigQuery データセットが別のプロジェクトにある場合、小売業向け Vertex AI Search が BigQuery データセットにアクセスできるように、必要な権限を構成します。詳細

  2. カタログデータを小売業向け Vertex AI Search にインポートします。

    コンソール

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

      [データ] ページに移動
    2. [Import] をクリックして [Import] パネルを開きます。
    3. [Product catalog] を選択します。
    4. データソースとして [BigQuery] を選択します。
    5. カタログのアップロード先のブランチを選択します。
    6. [Retail 商品カタログ スキーマ] を選択します。これは、小売業向け Vertex AI Search の商品スキーマです。
    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 スキーマを使用します。

      ステージング ディレクトリまたはエラー ディレクトリを指定しないことをおすすめします。そうすることで、新しいステージング ディレクトリとエラー ディレクトリを含む 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 サービスとは異なるプロジェクトにある場合にアクセスを設定するには、次の手順を行います。

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

    [IAM] ページを開く

  2. 小売業向け Vertex AI Search プロジェクトを選択します。

  3. Retail サービスアカウント という名前のサービス アカウントを探します。

    以前にインポート オペレーションを開始していない場合、このサービス アカウントは表示されない可能性があります。このサービス アカウントが表示されない場合は、インポート タスクに戻ってインポートを開始します。権限エラーで失敗した場合は、ここに戻ってこのタスクを完了してください。

  4. メールアドレスのようなサービス アカウントの ID（例: service-525@gcp-sa-retail.iam.gserviceaccount.com）をコピーします。

  5. （同じ [IAM と管理] ページで）BigQuery プロジェクトに切り替え、 [アクセスを許可] をクリックします。

  6. [新しいプリンシパル] に、小売業向け Vertex AI Search サービス アカウントの ID を入力し、[BigQuery] > [BigQuery ユーザー] ロールを選択します。

  7. [別のロールを追加] をクリックし、[BigQuery] > [BigQuery データ編集者] を選択します。

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

  8. [保存] をクリックします。

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

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

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

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

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

    Vertex AI Search for Retail サービス アカウントは、Google Cloud コンソールの [IAM] ページに Retail サービス アカウントという名前で表示されます。バケットの権限にアカウントを追加するときは、そのメールアドレスのようなサービス アカウントの ID（たとえば、service-525@gcp-sa-retail.iam.gserviceaccount.com）を使用します。

  2. カタログデータをインポートします。

    コンソール

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

      [データ] ページに移動
    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 データ形式をご覧ください。

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

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

  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 は、履歴カタログデータのインポートと管理をサポートしています。過去のカタログ データは、モデルのトレーニングに過去のユーザー イベントを使用する場合に役立ちます。過去の商品情報は、過去のユーザー イベント データを充実させ、モデルの精度を向上させるために使用できます。

過去の商品は期限切れの商品として保存されます。検索レスポンスでは返されませんが、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 メソッドを使用して、カタログを一括更新できます。これは初期インポートと同じです。カタログデータをインポートするの手順に従ってください。

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

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

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

    [データ] ページに移動

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

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

    [データ品質] ページに移動

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

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

次のステップ