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

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

過去のユーザー イベントのインポート

このページでは、過去のイベントからユーザー イベントデータを一括インポートする方法について説明します。Retail API モデルでは、トレーニングにユーザー イベント データが必要です。

イベントの記録の設定後、モデルのトレーニングに十分なユーザー イベント データが記録されるまでに、かなりの時間がかかる場合があります。過去のイベントからユーザー イベントデータを一括インポートすることで、初期のモデル トレーニングを高速化できます。操作を行う前に、ユーザー イベントの記録に関するおすすめの方法と、このページの始める前にをご覧ください。

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

例を挙げてみます。

始める前に

インポート エラーを回避し、適切な結果を生成するのに十分なデータが Retail API にあることを確認するには、ユーザー イベントをインポートする前に次の情報を確認します。

イベントのインポートに関する考慮事項

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

Cloud Storage Description Cloud Storage バケットに読み込まれたファイルから JSON 形式のデータをインポートします。各ファイルのサイズは 2 GB 以下である必要があります。一度にインポートできるファイル数は最大で 100 個です。インポートは Cloud Console または cURL を使用して行うことができます。カスタム属性を許可する Product JSON データ形式を使用します。
使うタイミング 1 回のステップで大量のデータを読み取る必要がある場合。
制限事項 データが Google アナリティクスや Merchant Center にある場合、データは BigQuery にのみエクスポートでき、Cloud Storage にインポートする追加の手順が必要になります。
BigQuery Description Retail スキーマを使用する、あらかじめ読み込まれた BigQuery テーブルからデータをインポートします。Cloud Console または cURL を使用して実行できます。
使うタイミング インポートする前に分析やイベントデータの前処理も使用している場合。
制限事項 Retail スキーマにマッピングされる BigQuery テーブルを作成する追加のステップが必要です。ユーザー イベント数が多い場合は、BigQuery が Cloud Storage より費用の高いリソースとなることも考慮してください。
BigQuery と Google アナリティクス 360 Description 既存のデータを Google アナリティクスから Retail にインポートします。
使うタイミング Google アナリティクスを使用しており、レコメンデーションや検索のコンバージョンを追跡する場合。追加のスキーマ マッピングは必要ありません。
制限事項 一部の属性のみが使用可能で、いくつかの高度な Retail 機能は使用できません。Retail Search を使用する場合は、Google アナリティクスでインプレッションを追跡する必要があります。
インライン インポート Description userEvents.import メソッドの呼び出しを使用してインポートします。
使うタイミング すべての認証をバックエンドで行ってプライバシーを強化し、バックエンドのインポートを実行できる場合。
制限事項 通常、ウェブ インポートよりも複雑です。

Cloud Storage からのユーザー イベントのインポート

Cloud Storage からユーザー イベントは、Cloud Console または userEvents.import メソッドを使用してインポートします。

コンソール

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

    [データ] ページに移動

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

  3. [User events] を選択します。

  4. イベントをアップロードするブランチを選択します。

  5. データソースとして [Cloud Storage] を選択します。

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

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

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

  8. (省略可)ユーザー イベントの繰り返しアップロードを設定するかどうかを選択します。

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

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

cURL

ユーザー イベントは、userEvents.import メソッドを使用してインポートします。

  1. インポートの入力パラメータのデータファイルを作成します。GcsSource オブジェクトを使用して、Cloud Storage バケットを指定します。

    複数のファイルを指定することも、1 つを指定することもできます。

    • 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"}
    }
    
  2. カタログ情報を Retail API にインポートするには、userEvents:import REST メソッドに対して POST リクエストを実行し、データファイルの名前を指定します。

    export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
    
    curl -X POST \
         -v \
         -H "Content-Type: application/json; charset=utf-8" \
         -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
         --data @./DATA_FILE.json \
      "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:import"
      }
    }'
    

BigQuery からのユーザー イベントのインポート

BigQuery からユーザー イベントは、Cloud Console か userEvents.import メソッドを使用してインポートします。

コンソール

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

    [データ] ページに移動

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

  3. [User events] を選択します。

  4. イベントをアップロードするブランチを選択します。

  5. データソースとして [BigQuery] を選択します。

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

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

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

  8. (省略可)ユーザー イベントの繰り返しアップロードを設定するかどうかを選択します。

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

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

cURL

ユーザー イベントは、userEvents.import メソッドを使用してインポートします。

イベントをインポートする際は、dataSchema に値 user_event を使用します。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
  "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:import" \
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event"
    }
  }
}'

BigQuery データセットが Retail API プロジェクトとは異なるプロジェクトに属している場合は、BigQuery データセットへのアクセスの設定の手順に従って、Retail サービス アカウントに BigQuery プロジェクトに対する BigQuery データ編集者のロールを付与します。BigQuery プロジェクト ID を指定するために、インポート リクエストを変更します。

"bigQuerySource": {
     "projectId": "BQ_PROJECT_ID",
   }

BigQuery で Google アナリティクス 360 のユーザー イベントをインポートする

Google アナリティクス 360 を BigQuery と統合して拡張 e コマースを使用している場合は、Google アナリティクス 360 のユーザー イベントをインポートできます。

以下の手順は、BigQuery と Google アナリティクス 360 の使用に精通していることを前提とします。

始める前に

データソースを確認する

  1. インポートするユーザー イベントデータが、アクセス権のある BigQuery テーブルで正しくフォーマットされていることを確認してください。

    テーブルの形式は project_id:ga360_export_dataset.ga_sessions_YYYYMMDD である必要があります。

    テーブルの形式の詳細については、Google アナリティクスのドキュメントをご覧ください。

  2. BigQuery Google Cloud Console で、[エクスプローラ] パネルからテーブルを選択してテーブルをプレビューします。

    以下を確認します。

    1. clientId 列に有効な値(たとえば、123456789.123456789)がある。

      この値は、完全な _ga Cookie 値(GA1.3.123456789.123456789 のような形式)とは異なります。

    2. hits.transaction.currencyCode 列に有効な通貨コードがある。

    3. search イベントをインポートする予定の場合は、hits.page.searchKeyword 列または hits.customVariable.searchQuery 列が存在することを確認します。

      search イベントのインポートはサポートされますが、アナリティクス 360 から他のイベントタイプと同様にはマッピングされません。これは、search イベントタイプがアナリティクス 360 でネイティブにサポートされていないためです。インポートの際、Retail API は、検索クエリからの情報と、存在する場合は製品のインプレッションを組み合わせることによって、アナリティクス 360 から search イベントを作成します。

      検索クエリは、hits.page.searchKeyword から、または hits.customVariables.customVarNamesearchQuery の場合は hits.customVariables.customVarValue から派生します。hits.product.isImpressionsTRUE の場合、商品のインプレッションは hits.product から取得されます。

  3. アップロードされたカタログとアナリティクス 360 のユーザー イベント テーブルとのアイテム ID の整合性を確認します。

    BigQuery テーブル プレビューの hits.product.productSKU 列の任意の商品 ID を使用して、アップロードしたカタログに同じ商品が含まれていることを確認するために、product.get メソッドを使用します。

    export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
    
       curl \
         -v \
         -X GET \
         -H "Content-Type: application/json; charset=utf-8" \
         -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
         "https://retail.googleapis.com/v2/projects/[PROJECT_NUMBER]/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"
    

Google アナリティクス 360 のイベントをインポートする

ユーザー イベントをインポートするには、userEvents.import メソッドの呼び出しにイベントのデータを含めます。

dataSchema の場合は、値 user_event_ga360 を使用します。

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
  "https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog/userEvents:import" \
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

Java

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

BigQuery データセットが Retail プロジェクトとは異なるプロジェクトに属している場合は、BigQuery データセットへのアクセスの設定の手順に従って、Retail サービス アカウントに BigQuery プロジェクトに対する BigQuery データ編集者のロールを付与します。BigQuery プロジェクト ID を指定するために、インポート リクエストを変更します。

"bigQuerySource": {
     "projectId": "GA360_BQ_PROJECT_ID",
   }

インラインでユーザー イベントをインポートする

curl

ユーザー イベントをインラインでインポートするには、userEvents.import メソッドの呼び出しにイベントのデータを含めます。

最も簡単な方法は、ユーザー イベントデータを JSON ファイルに追加し、ファイルを cURL に提供することです。

ユーザー イベント タイプのフォーマットについては、ユーザー イベントをご覧ください。

  1. JSON ファイルを作成します。

    {
    "inputConfig": {
      "userEventInlineSource": {
          "userEvents": [
            {
              <userEvent1>>
            },
            {
              <userEvent2>
            },
            ....
          ]
        }
      }
    }
    
  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_ID]/locations/global/catalogs/default_catalog/userEvents:import"
    

Java

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

履歴カタログ データ

過去のユーザー イベントに表示される履歴カタログ データをインポートすることもできます。この履歴カタログデータは、Retail API が過去の商品情報を利用してユーザー イベントを強化し、モデルの精度を向上させることができるために役立ちます。

詳しくは、カタログの過去のデータをインポートするをご覧ください。

次のステップ