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

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

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

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

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

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

ガイドを表示

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

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

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

ガイドを表示

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

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

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

ガイドを表示

始める前に

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

商品データは、Merchant Center、Cloud Storage、BigQuery からインポートでき、またはリクエスト内でデータをインラインで指定できます。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 Description Retail スキーマまたは Merchant Center スキーマを使用する、あらかじめ読み込まれた BigQuery テーブルからデータをインポートします。Google Cloud コンソールまたは curl を使用して実行できます。
使うタイミング 多数の属性を含む商品カタログがある場合。BigQuery のインポートでは Retail スキーマが使用されます。このスキーマは、Key-Value カスタム属性など、他のインポート オプションよりも多くの商品属性を備えています。

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

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

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

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

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

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

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

    [データ] ページに移動

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

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

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

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

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

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 コンソールの　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 アカウントと Retail API の両方へのアクセス権があることを確認します。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 を表示するには、Google Cloud コンソールの [データ] ページに移動し、ページの右上にある [Merchant Center] ボタンをクリックします。[リンクされている Merchant Center アカウント] パネルが開きます。このパネルから Merchant Center アカウントを追加することもできます。

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

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

コンソール

  1. Google Cloud コンソールの　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 アカウントをリンク解除すると、そのアカウントでは、カタログデータの Retail API との同期が停止されます。この手順では、すでにアップロード済みの Retail API 内の商品は削除されません。

コンソール

  1. Google Cloud コンソールの　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 アカウントのオファーの数によって異なります。

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

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

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

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

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

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

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

Merchant Center からカタログデータをインポートするには、Retail Google Cloud コンソールまたは 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 コンソールの　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 ディレクトリ。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 と呼ばれ、番号が付加されます（例: 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 から正しい形式でカタログデータをインポートするには、Retail スキーマを使用して、正しい形式で BigQuery テーブルを作成し、カタログデータで空のテーブルの読み込みを行います。その後、データを Retail API にアップロードします。

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

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

ガイドを表示

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

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

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

    コンソール

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

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

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

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

      重要: バリアントとして取り込まれた商品カタログを含むプロジェクトに大して Retail Search を有効にすることはできません。
    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 ディレクトリ。Retail API に一時ディレクトリを自動的に作成させるには、この項目を空のままにします（推奨）。
      • ERROR_DIRECTORY: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ。Retail API に一時ディレクトリを自動的に作成させるには、この項目を空のままにします（推奨）。
      • dataSchema: For the dataSchema プロパティには、値 product（デフォルト）を使用します。Retail スキーマを使用します。

      Retail API が新しいステージング ディレクトリとエラー ディレクトリで 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. カタログ情報を 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"

      オペレーションが完了すると、返されたオブジェクトは 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 データセットが 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 コンソールの [IAM] ページに Retail サービス アカウントという名前で表示されます。バケットの権限にアカウントを追加するときは、そのメールアドレスのようなサービス アカウントの ID（たとえば、service-525@gcp-sa-retail.iam.gserviceaccount.com）を使用します。

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

    コンソール

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

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

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

      重要: バリアントとして取り込まれた商品カタログを含むプロジェクトに大して Retail Search を有効にすることはできません。
    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>/ の形式にする必要があります。エラー ディレクトリが存在しない場合は、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 コンソールを使用することです。詳しくは、特定の統合オペレーションのステータスを確認するをご覧ください。

      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

カタログ情報を 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 は、過去の商品情報を使用して過去のユーザー イベントデータを拡充し、モデルの精度を向上させることができます。

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

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

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

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

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 コンソールを使用してデータをインポートする場合は、自動スケジュール オプションを選択することもできます。

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

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

バッチ アップデート

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

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

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

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

    [データ] ページに移動

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

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

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

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

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

次のステップ