これは、Recommendations AI、Retail Search、新しい Retail コンソールに関するドキュメントです。

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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

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

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


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

ガイドを表示


以降のセクションでは、[ガイドを表示] をクリックした場合と同じ手順について説明します。

Cloud Storage からのカタログデータのインポート

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


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

ガイドを表示


以降のセクションでは、[ガイドを表示] をクリックした場合と同じ手順について説明します。

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

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


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

ガイドを表示


以降のセクションでは、[ガイドを表示] をクリックした場合と同じ手順について説明します。

始める前に

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

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

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

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

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

  • メインの商品または商品グループをどれにし、どのバリエーションをメインのものにするかを慎重に検討してください。データをアップロードする前に、プロダクト レベルをご覧ください。

    データをインポートした後、プロダクト レベルの構成を変更すると、多大な労力が必要になります。

    メインアイテムは、検索結果またはレコメンデーションとして返されます。バリアント アイテムは対象外です。

    たとえば、メインの SKU グループが「V ネックシャツ」の場合、レコメンデーション モデルは V ネックのシャツ 1 商品とクルー ネックのシャツとスクープのネックのシャツを返します。ただし、バリエーションが使用されず、各 SKU がプライマリである場合、V ネックのシャツの色とサイズの組み合わせはすべて、推奨事項のパネルに個別の項目として返されます。「ブラウンの V ネックのシャツ、サイズ L の洋服」、「サイズの V ネックのシャツ」、「白い M ネックのシャツ」、「サイズ M サイズのネック シャツ」、「サイズ M サイズ」です。

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

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

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

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

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

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

  • 特に Google Cloud Console を使用して収益指標を取得する場合は、すべてのイベントで単一の通貨を使用するようにしてください。Retail API では、単一のカタログに複数の通貨を使用することはできません。

  • カタログを最新の状態に保ちます。

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

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

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

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

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

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

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

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

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

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

限定的なコントロール。Merchant Center からインポートする特定のフィールドやアイテムセットは指定できません。Merchant Center 内に存在するすべてのアイテムとフィールドがインポートされます。
BigQuery 説明 Retail スキーマまたは Merchant Center スキーマを使用する、あらかじめ読み込まれた BigQuery テーブルからデータをインポートします。Google Cloud Console または curl を使用して実行できます。
使うタイミング 多数の属性を持つ商品カタログがある場合。BigQuery のインポートでは、Retail スキーマを使用します。Retail スキーマには、Key-Value カスタム属性など、他のインポート オプションよりも多くの商品属性があります。

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

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

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

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

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

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

  1. Google Cloud Console で [小売データ] ページに移動します。

    [データ] ページに移動

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

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

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

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

    カタログ ブランチからデータをパージするための長時間実行オペレーションが開始されます。パージ処理が完了すると、パージのステータスは [Activity status] ウィンドウの [Product catalog] リストに表示されます。

Merchant Center を Retail API に同期する

Merchant Center と Retail API 間の同期を継続的に実施するには、Merchant Center アカウントを Retail API にリンクします。リンクされると、Merchant Center アカウントのカタログ情報が直ちに Retail API にインポートされます。

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

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

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

Console

  1. Google Cloud Console で [小売データ] ページに移動します。

    [データ] ページに移動
  2. [Import] をクリックして [Import] パネルを開きます。
  3. [Product catalog] を選択します。
  4. データソースとして [Merchant Center の同期] を選択します。
  5. Merchant Center アカウントを選択します。
  6. カタログのアップロード先のブランチを選択します。
  7. [インポート] をクリックします。

curl

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

  2. Catalog.patch メソッドを使用してリンクを確立します。

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
     --data '{
        "merchantCenterLinkingConfig": {
          "links": [{
             merchantCenterAccountId: MERCHANT_CENTER_ID,
             destinations: ["DESTINATION_1", "DESTINATION_2"]
             branchId: "BRANCH_ID"
             languageCode: "LANGUAGE_CODE"
             regionCode: "REGION_CODE"
          }]
        }
     }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog?updateMask=merchantCenterLinkingConfig"
    
    • MERCHANT_CENTER_ID: Merchant Center アカウントの ID。
    • BRANCH_ID: リンクを確立するブランチの ID。値 '0'、'1'、'2' を指定します。
    • DESTINATION: Merchant Center の掲載先。少なくとも 1 つのリンク先値が必要です。Merchant Center デスティネーション ドキュメントに記載されているサポートされている値を自由に組み合わせることができます。
    • LANGUAGE_CODE: (省略可)インポートする商品の 2 文字の言語コード。Merchant Center で商品の [Language] 列に表示します。設定しない場合は、すべての言語がインポートされます。
    • REGION_CODE: (省略可)インポートする商品の大文字の 2 文字の地域コード。Merchant Center で商品の [Country Of Sale] 列に表示します。設定しない場合、すべてのリージョンがインポートされます。

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

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

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

Console

  1. Google Cloud Console で [小売データ] ページに移動します。

    [データ] ページに移動

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

  3. リンクを解除する Merchant Center アカウントの横にある [Unlink] をクリックし、表示されるダイアログで選択を確定します。

curl

Catalog.patch メソッドを使用して、Catalog リソースからリンク構成を削除します。

curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 --data '{
    "merchantCenterLinkingConfig": {}
 }' \
 "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog?updateMask=merchantCenterLinkingConfig"

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

  • Merchant Center アカウントは、任意の数のカタログ ブランチにリンクできますが、1 つのカタログ ブランチは 1 つの Merchant Center アカウントにのみリンクできます。

  • Merchant Center アカウントをリンクした後、最初のインポートの完了には数時間かかる場合があります。かかる時間は、Merchant Center アカウントのオファーの数によって異なります。

  • Retail API メソッドで、Merchant Center アカウントにリンクされたブランチの商品は変更できません。そうしたブランチ内の商品カタログデータの変更は、Merchant Center を使用して行う必要があります。そうすると、その変更は、Retail API に自動的に同期されます。

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

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

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

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

Merchant Center スキーマは、Merchant Center スキーマを使用して、Merchant Center からの 1 回限りの手順として BigQuery から一括でインポートできます(Recommendations AI のみ)。

Merchant Center から一括インポート

Retail の Google Cloud Console または products.import メソッドを使用して、Merchant Center からカタログデータをインポートできます。一括インポートは 1 回限りの手順であり、Recommendations AI でのみサポートされています。

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

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

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

  2. BigQuery データセットが別のプロジェクトにある場合、Retail API が BigQuery データセットにアクセスできるように、必要な権限を設定します。詳細

  3. カタログデータを BigQuery から Retail API にインポートします。

    Console

    1. Google Cloud Console で [小売データ] ページに移動します。

      [データ] ページに移動

    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 ディレクトリ。Retail API に一時ディレクトリを自動的に作成させるには、この項目を空のままにします(推奨)。
      • ERROR_DIRECTORY: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ。Retail API に一時ディレクトリを自動的に作成させるには、この項目を空のままにします(推奨)。
      • dataSchema: dataSchema プロパティには、値 product_merchant_center を使用します。Merchant Center 商品のテーブル スキーマをご覧ください。

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

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

      ディレクトリを指定する場合は、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 から正しい形式でカタログデータをインポートするには、Retail スキーマを使用して、正しい形式で BigQuery テーブルを作成し、カタログデータで空のテーブルの読み込みを行います。その後、データを Retail API にアップロードします。

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


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

ガイドを表示


以降のセクションでは、[ガイドを表示] をクリックした場合と同じ手順について説明します。

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

  1. BigQuery データセットが別のプロジェクトにある場合、Retail API が BigQuery データセットにアクセスできるように、必要な権限を設定します。詳細

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

    Console

    1. Google Cloud Console で [小売データ] ページに移動します。

      [データ] ページに移動
    2. [Import] をクリックして [Import] パネルを開きます。
    3. [Product catalog] を選択します。
    4. データソースとして [BigQuery] を選択します。
    5. カタログのアップロード先のブランチを選択します。
    6. [Retail Product Catalogs Schema] を選択します。これは Retail API スキーマです。
    7. データが配置される BigQuery テーブルを入力します。
    8. (省略可)[詳細オプションを表示] で、プロジェクト内の Cloud Storage バケットのロケーションをデータの一時的なロケーションとして入力します。

      指定しないと、デフォルトのロケーションが使用されます。指定する場合、BigQuery と Cloud Storage バケットは同じリージョン内に存在する必要があります。
    9. Retail Search が有効ではなく、Merchant Center スキーマを使用している場合は、商品レベルを選択します。

      初めてカタログをインポートする場合や、またはカタログを完全に削除した後、カタログを再インポートする場合は、商品レベルを選択する必要があります。商品レベルの詳細をご覧ください。データをインポートした後に商品レベルを変更するには、かなりの手間がかかります。

      重要: バリアントとして取り込まれた商品カタログを含むプロジェクトに大して Retail Search を有効にすることはできません。
    10. [Import(インポート)] をクリックします。

    curl

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

      • ingestionProductType: primary(デフォルト)と variant の値をサポートします。
      • merchantCenterProductIdField: offerIditemGroupId の値をサポートします。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 ディレクトリ。Retail API に一時ディレクトリを自動的に作成させるには、この項目を空のままにします(推奨)。
      • ERROR_DIRECTORY: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ。Retail API に一時ディレクトリを自動的に作成させるには、この項目を空のままにします(推奨)。
      • dataSchema: dataSchema プロパティには、値 product(デフォルト)を使用します。Retail スキーマを使用します。

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

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

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

      {
         "inputConfig":{
           "bigQuerySource": {
             "projectId":"PROJECT_ID",
             "datasetId":"DATASET_ID",
             "tableId":"TABLE_ID",
             "dataSchema":"product"}
            }
      }
      
    3. カタログ情報を Retail API にインポートするには、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"
      

      オペレーションが完了すると、返されたオブジェクトは truedone 値を持ち、次の例のような 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 データセットが Retail サービスとは異なるプロジェクトにある場合にアクセスを設定するには、次の手順を行います。

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

    [IAM] ページを開く

  2. Retail プロジェクトを選択します。

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

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

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

  5. (同じ [IAM と管理] ページで)BigQuery プロジェクトに切り替え、[追加] をクリックします。

  6. Retail サービス アカウントの ID を入力し、[BigQuery] > [BigQuery ユーザー] ロールを選択します。

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

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

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

Cloud Storage からのカタログデータのインポート

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

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

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

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

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

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

    Console

    1. Google Cloud Console で [小売データ] ページに移動します。

      [データ] ページに移動
    2. [Import] をクリックして [Import] パネルを開きます。
    3. データソースとして [商品カタログ] を選択します。
    4. カタログのアップロード先のブランチを選択します。
    5. スキーマとして [Retail 商品カタログ スキーマ] を選択します。
    6. データの Cloud Storage のロケーションを入力します。
    7. Retail Search が有効ではない場合は、商品レベルを選択します。

      初めてカタログをインポートする場合や、またはカタログを完全に削除した後、カタログを再インポートする場合は、商品レベルを選択する必要があります。商品レベルの詳細をご覧ください。データをインポートした後に商品レベルを変更するには、かなりの手間がかかります。

      重要: バリアントとして取り込まれた商品カタログを含むプロジェクトに大して Retail Search を有効にすることはできません。
    8. [Import(インポート)] をクリックします。

    curl

    1. カタログをはじめてアップロードする場合、またはカタログを消去した後にカタログを再インポートする場合は、Catalog.patch メソッドを使用して商品レベルを設定します。商品レベルの詳細をご覧ください。

      • ingestionProductType: primary(デフォルト)と variant の値をサポートします。
      • merchantCenterProductIdField: offerIditemGroupId の値をサポートします。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>/ の形式にする必要があります。エラー ディレクトリが存在しない場合は、Retail API によって作成されます。バケットはすでに存在している必要があります。

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }
      
    3. カタログ情報を Retail API にインポートするには、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 Console を使用することです。詳細については、特定の統合オペレーションのステータスの確認をご覧ください。

      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]"
      

      オペレーションが完了すると、返されたオブジェクトは truedone 値を持ち、次の例のような 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

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

商品全体を 1 行で入力します。各プロダクトは 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 行に 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 }
    ]
  }

過去のカタログ データ

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

過去の商品は期限切れの商品として保存されます。検索レスポンスでは返されませんが、UpdateListDelete の API 呼び出しで表示されます。

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

商品の expireTime フィールドが過去のタイムスタンプに設定されている場合、この商品は過去の商品とみなされます。商品の在庫状況OUT_OF_STOCK に設定して、Recommendations AI への影響を防ぎます。

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

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

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

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

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

商品全体を 1 行で入力します。各プロダクトは 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 フィールドに過去のタイムスタンプを必ず設定してください。

カタログを最新の状態に保ちます

Retail API は、最適な結果を提示するために最新の商品情報を使用します。カタログを毎日インポートして、カタログが最新の状態であることを確認するようおすすめします。Google Cloud Scheduler を使用してインポートをスケジュールしたり、Google Cloud Console を使用してデータをインポートする際に自動スケジュール オプションを選択したりできます。

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

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

バッチ アップデート

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

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

インポートしたデータにエラーがないかどうかを確認するには、[Retail Data] ページでカタログのデータ読み込み指標を確認します。[Retail Data] ページには、カタログ内の商品データの品質指標も表示されます。

質の高い検索結果を得るには、カタログを最新の状態に保つことが重要です。インポート エラー率をモニタリングし、必要に応じて対処してください。詳細については、アラートの設定をご覧ください。

次のステップ