この Recommendations AI ドキュメントでは、Recommendations コンソールについて説明します。Retail コンソールに切り替え、Retail ドキュメントを使用することをおすすめします。このドキュメントでは、Recommendations AI、Retail コンソール、Retail Search について説明しています。

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 Center、Cloud Storage、BigQueryから、またはリクエストでインラインのデータを指定することによりインポートできます。これらの各手順は 1 回限りのインポートです。カタログを毎日インポートして、カタログが最新の状態であることを確認するようおすすめします。カタログを最新の状態に保つをご覧ください。

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

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

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

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

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

Google Merchant Center の商品テーブルスキーマを使用します。転送を毎日繰り返すように構成しますが、データセットの有効期限は 2 日にします。
BigQuery データセットが別のプロジェクトにある場合、Recommendations AI が BigQuery データセットにアクセスできるように、必要な権限を設定します。詳細
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 と呼ばれ、番号が付加されます（例: 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 から正しい形式でカタログデータをインポートするには、Recommendations AI スキーマを使用して正しい形式で BigQuery テーブルを作成して、カタログデータで空のテーブルの読み込みを行います。それから、データを Recommendations AI にアップロードします。

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

curl

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

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

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

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

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

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

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

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

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

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

curl

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

curl

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

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

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

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

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

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

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

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

商品全体を 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 }]
  }

過去のカタログデータ

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

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

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

商品の [expireTime][product-expire-time] フィールドが過去のタイムスタンプに設定されている場合、この商品は過去の商品とみなされます。Recommendations AI に影響しないようにするには、商品 [availability][product-availability] を [OUT_OF_STOCK][product-out-of-stock] に設定します。

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

[Product.Create メソッドを呼び出す][create-expired]。
[期限切れの商品をインラインでインポートする][inline-import-expired]。
[BigQuery から期限切れの商品をインポートする][import-expired]。

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

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

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

手順は [inline import][inline] と同じですが、商品の[expireTime][product-expire-time] フィールドを過去のタイムスタンプに設定する必要があります。

商品全体を 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][product-expire-time] フィールドには過去のタイムスタンプを設定してください。

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

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

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

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

一括更新

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

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

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

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

始める前に

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

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

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

コンソール

cURL

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

curl

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

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

curl

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

curl

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

過去のカタログ データ

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

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

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

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

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

一括更新

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

次のステップ

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

過去のカタログデータ

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

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