これは、Recommendations AI、Retail Search、新しい Retail コンソールに関するドキュメントです。制限付き一般提供フェーズで Retail Search を使用するには、Cloud 営業担当者にお問い合わせください

Recommendations AI のみを使用している場合は、Recommendations コンソールを引き続き使用し、Recommendations AI のドキュメントをご覧ください。

カタログ情報のインポート

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

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

始める前に

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

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

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

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

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

  • データをアップロードする前に、商品レベルの情報をご確認ください。

    データをインポートした後に商品レベルを変更するには、かなりの手間がかかります。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Cloud Storage Description Cloud Storage バケットに読み込まれたファイルから JSON 形式のデータをインポートします。各ファイルのサイズは 2 GB 以下である必要があります。そして、一度にインポートできるファイル数は最大で 100 個です。インポートは Cloud Console または curl を使用して行うことができます。カスタム属性を許可する Product JSON データ形式を使用します。
使うタイミング 1 回で大量のデータを読み込む必要がある場合。
制限事項 変更がすぐに反映されないため、棚卸しと価格の更新が頻繁にあるカタログには適していません。
BigQuery Description Retail スキーマを使用する、あらかじめ読み込まれた BigQuery テーブルからデータをインポートします。Cloud Console または curl を使用して実行できます。
使うタイミング 多数の属性を含む商品カタログがある場合。BigQuery のインポートでは Retail スキーマが使用されます。このスキーマは、Key-Value カスタム属性など、他のインポート オプションよりも多くの商品属性を備えています。

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

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

限定的な管理。Merchant Center からインポートする特定のフィールドまたはアイテムのセットを指定することはできません。Merchant Center に存在するすべてのアイテムとフィールドがインポートされます。
インライン インポート Description Product.import メソッドの呼び出しを使用してインポートします。このオブジェクトは、Retail スキーマよりも商品カタログ属性が少ない ProductInlineSource オブジェクトを使用しますが、カスタム属性をサポートしています。
使うタイミング フラットで非リレーショナル カタログデータがある場合や、数量や価格の更新頻度が高い場合。
制限事項 一度にインポートできるカタログ アイテムは最大 100 個です。ただし、多くの読み込みステップを実行できます。アイテム数の上限はありません。

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

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

カタログデータは、Merchant Center から次の方法でインポートできます。

  • 1 回限りの手順としての一括インポート(Recommendations AI のみ)。

  • Merchant Center アカウントを Retail API にリンクする。リンクされると、Merchant Center アカウントの変更が継続的に Retail API に同期されます。

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

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

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

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

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

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

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

    コンソール

    1. Google Cloud Console の [Retail Data] ページに移動します。

      [データ] ページに移動

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

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

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

    5. データソースとして [Merchant Center] を選択し、アップロード方法として [BigQuery] を選択します。

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

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

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

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

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

      データをインポートした後に商品レベルを変更するには、かなりの手間がかかります。

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

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 アカウントを同期するには、次の手順を行います。

コンソール

  1. Google Cloud Console の [Retail Data] ページに移動します。

    [データ] ページに移動

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

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

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

  5. Merchant Center アカウントを選択します。

  6. インポート元の Merchant Center の宛先を選択します。

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

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

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"
          }]
        }
     }' \
     "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 の宛先のドキュメントに記載されているサポートされている値を自由に組み合わせることができます。

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

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

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

コンソール

  1. Google Cloud Console の [Retail Data] ページに移動します。

    [データ] ページに移動

  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 アカウントは空のカタログ ブランチにのみリンクできます。カタログ ブランチから商品を削除するには、商品情報の削除をご覧ください。

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

BigQuery から正しい形式でカタログデータをインポートするには、Retail スキーマを使用して、正しい形式で BigQuery テーブルを作成し、カタログデータで空のテーブルの読み込みを行います。その後、データを Retail API にアップロードします。

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

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

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

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

    コンソール

    1. Google Cloud Console の [Retail Data] ページに移動します。

      [データ] ページに移動

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

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

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

    5. データソースとして [BigQuery] を選択し、スキーマとして [Retail Product Catalogs Schema] を選択します。

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

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

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

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

      このオプションは、以前に少なくとも 1 回、Retail API にカタログ正常にインポートされている場合にのみ使用できます。

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

      データをインポートした後に商品レベルを変更するには、かなりの手間がかかります。

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

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

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

    コンソール

    1. Google Cloud Console の [Retail Data] ページに移動します。

      [データ] ページに移動

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

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

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

    5. データソースとして [Cloud Storage] を選択し、スキーマとして [Retail Product Catalogs Schema] を選択します。

    6. データの Cloud Storage のロケーションを入力します。

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

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

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

      このオプションは、以前に少なくとも 1 回、Retail API にカタログ正常にインポートされている場合にのみ使用できます。

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

      データをインポートした後に商品レベルを変更するには、かなりの手間がかかります。

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

    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"
      

      インポート オペレーションのステータスを確認する最も簡単な方法は、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 オブジェクトを使用してカタログデータを指定します。

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

  1. 商品の JSON ファイルを作成し、./data.json という名前を付けます。

    {
    "inputConfig": {
    "productInlineSource": {
      "products": [
        {
          <product1>
        },
        {
          <product2>
        },
        ....
      ]
    }
    }
    }
    
  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 }]
}

履歴カタログ データ

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

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

履歴カタログ データをインポートする

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

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

  • Product.Create メソッドを呼び出す。(詳細
  • 期限切れの商品のインライン インポート。(詳細
  • BigQuery または Cloud Storage から期限切れの商品をインポートする。(詳細

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

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

期限切れの商品のインライン インポート

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

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

{
"inputConfig": {
  "productInlineSource": {
      "products": [
        {
          "name": "historical product 001"
          "id": "historical_product_001"
          "name": "A historical product"
          "expire_time": {
            "second": 1000000000  // a past timestamp
          }
        },
        {
          <Another product>
        },
        ....
      ]
    }
  }
}

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

この手順は、BigQueryCloud Storage から通常の商品をインポートする場合と似ています。ただし、expireTime フィールドを過去のタイムスタンプに設定してください。

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

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

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

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

一括更新

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

インポート状態のモニタリング

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

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

次のステップ