これは Recommendations AI のみに関するドキュメントです。制限付き一般提供フェーズで Retail Search と統合された Retail コンソールを試すには、Cloud 営業担当者にお問い合わせくださいRetail Search を使用する予定がない場合は、通知があるまで引き続き Recommendations コンソールを使用してください。

Recommendations AI の v1beta バージョンを使用している場合は、Retail API バージョンに移行してください。

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

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

始める前に

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

カタログをインポートする前に商品レベルを選択する必要があります。また、インポートを実行するには、販売店管理者の IAM ロールが必要です。

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

Recommendations AI で高品質の予測を行うには、高品質のデータが必要です。データに項目がないか、実際の値ではなくプレースホルダ値が含まれている場合、予測の品質に悪影響が出ます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

カタログデータのインポート

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

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

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

Cloud Console と Retail API のいずれかを使用して、Merchant Center からカタログデータをインポートできます。

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

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

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

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

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

    コンソール

    1. Google Cloud Console の [Recommendations AI データページ] に移動します。
      Recommendations AI データページに移動
    2. [インポート] をクリックして [カタログのインポート] パネルを開きます。
    3. データが保存されている BigQuery データセットとテーブルの ID を入力します。
    4. プロジェクト内の Cloud Storage バケットの場所を入力します。

      このバケットは、データの一時的な保存場所として使用されます。

    5. カタログをはじめてインポートする場合や、カタログを消去した後にカタログを再インポートする場合は、アップロード(ユーザー イベントの記録)と予測の商品レベルを選択します。

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

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

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

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

      自動的に作成されるバケット名には、プロジェクト ID、バケット リージョン、およびデータスキーマ名が含まれ、アンダースコアで区切られます(例: 4321_us_catalog_recommendations_ai)。自動的に作成されるディレクトリは、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 から正しい形式でカタログデータをインポートするには、Recommendations AI スキーマを使用して正しい形式で BigQuery テーブルを作成して、カタログデータで空のテーブルの読み込みを行います。それから、データを Recommendations AI にアップロードします。

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

curl

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

  2. カタログをはじめてアップロードする場合や、カタログを消去した後にカタログを再インポートする場合は、Catalog.patch メソッドを使用して商品レベルを設定します。このオペレーションには、Recommendations AI 管理者のロールが必要です。

    • 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"
    
  3. インポートの入力パラメータのデータファイルを作成します。入力パラメータ値は、Cloud Storage または BigQuery のどちらからインポートするかによって異なります。

    BigQuery データセットを指定するには、BigQuerySource オブジェクトを使用します。

    • dataset-id: BigQuery データセットの ID。
    • table-id: データを保持する BigQuery テーブルの ID。
    • project-id: BigQuery ソースが含まれているプロジェクト ID。指定しない場合、プロジェクト ID は親リクエストから継承されます。
    • staging-directory: 省略可。データが Cloud Storage にインポートされる前にデータの暫定的な保存場所として使用される Cloud Storage ディレクトリ。Recommendations AI に一時ディレクトリを自動的に作成させるには、この項目を空のままにします(推奨)。
    • error-directory: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ。Recommendations AI に一時ディレクトリを自動的に作成させるには、この項目を空のままにします(推奨)。
    • dataSchema: dataSchema プロパティには、product(デフォルト)の値を使用します。Recommendations AI スキーマを使用します。

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

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

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

    {
    "inputConfig":{
     "bigQuerySource": {
       "projectId": "project-id",
       "datasetId":"dataset-id",
       "tableId":"table-id",
       "dataSchema":"product"}
      }
    }
    
  4. カタログ情報を Recommendations AI にインポートするには、データファイルの名前(ここでは、input.json と表示)を指定して、Products:import REST メソッドに対して POST リクエストを実行します。

    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 です。このオブジェクトのステータスをリクエストするには、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 データセットが Recommendations AI サービスとは異なるプロジェクトにある場合にアクセスを設定するには、次の手順を行います。

  1. Cloud Console で IAM ページを開きます。

    [IAM] ページを開く

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

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

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

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

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

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

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

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

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

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

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

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

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

curl

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

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

  2. カタログをはじめてアップロードする場合や、カタログを消去した後にカタログを再インポートする場合は、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"
    
  3. インポートの入力パラメータのデータファイルを作成します。GcsSource オブジェクトを使用して、Cloud Storage バケットを指定します。

    複数のファイルを指定することも、1 つを指定することもできます。この例では、2 つのファイルを使用します。

    • input-file: カタログデータを含む Cloud Storage 内の 1 つまたは複数のファイル。
    • error-directory: インポートに関するエラー情報用の Cloud Storage ディレクトリ。

    入力ファイルのフィールドは、gs://<bucket>/<path-to-file>/ の形式にする必要があります。エラー ディレクトリは、gs://<bucket>/<folder>/ の形式にする必要があります。エラー ディレクトリが存在しない場合は、Recommendations AI によって作成されます。バケットはすでに存在している必要があります。

    {
    "inputConfig":{
     "gcsSource": {
       "inputUris": ["input-file1", "input-file2"]
     }
    },
    "errorsConfig":{"gcsPrefix":"error-directory"}
    }
    
  4. カタログ情報を Recommendations AI にインポートするには、データファイルの名前(ここでは、input.json と表示)を指定して、Products:import REST メソッドに対して POST リクエストを実行します。

    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

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

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"
    

商品アイテム 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://foobar",
  "images": [{"uri": "http://foobar/img1", "height": 320, "width": 320 }]
}

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

Recommendations AI は、最適なレコメンデーションを提示するために最新の商品情報を使用します。カタログを毎日インポートして、カタログが最新の状態であることを確認するようおすすめします。Google Cloud Scheduler を使用してインポートのスケジュールを設定できます。

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

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

一括更新

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

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

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

次のステップ