過去のユーザー イベントをインポートする

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

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

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

次のことが可能です。

• Cloud Storage からイベントをインポートする。
• BigQuery からイベントをインポートする。
• BigQuery から Google アナリティクス 360 のイベントをインポートする。
• BigQuery から Google アナリティクス 4 のイベントをインポートする。
• userEvents.import メソッドを使って、インラインでイベントをインポートする。

Cloud Storage チュートリアルからイベントをインポートする

このチュートリアルでは、Cloud Storage からユーザー イベントをインポートする方法を説明します。

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

ガイドを表示

BigQuery チュートリアルからイベントをインポートする

このチュートリアルでは、BigQuery からユーザー イベントをインポートする方法を説明します。

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

ガイドを表示

イベントのインライン チュートリアルをインポートする

このチュートリアルでは、ユーザー イベントデータをインラインでインポートする方法を説明します。

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

ガイドを表示

始める前に

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

• ユーザー イベントの記録に関するベスト プラクティスを確認します。

• ユーザー イベントの形式は、ユーザー イベント タイプによって異なります。各イベントタイプの表を作成するときに指定する形式については、ユーザー イベント タイプとサンプル スキーマをご覧ください。

• レコメンデーションと検索では、最小データ要件が異なります。ユーザー イベントが、使用するサービスの要件を満たしていることを確認してください。

  • 検索とレコメンデーションの要件については、ユーザー イベントの要件とベスト プラクティスをご覧ください。

  • また、レコメンデーション モデルを使用する場合は、ユーザー イベント データの要件もご覧ください。使用する予定のレコメンデーション モデルのタイプと最適化目標に応じた追加の要件を示しています。

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

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

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

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

BigQuery からデータをインポートする

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

BigQuery アクセスを設定する

BigQuery データセットへのアクセスの設定の手順に沿って、小売業向け Vertex AI Serach のサービス アカウントに、BigQuery データセットに対する BigQuery データオーナーロールを付与します。

BigQuery からユーザー イベントをインポートする

360 件のイベントは、Search for Retail コンソールまたは userEvents.import メソッドを使用してインポートできます。

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": "SCHEMA_TYPE"
  }
}
}'

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

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

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

始める前に

次の手順を開始する前に、以下の点をご確認ください。

• 拡張 e コマースを使用している。
• BigQuery がアナリティクス 360 にリンクされている。

データソースを確認する

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

   テーブルが project_id:ga360_export_dataset.ga_sessions_YYYYMMDD という名前であることを確認してください。

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

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

   以下を確認します。

   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 でネイティブにサポートされていないためです。インポートの際、search イベントは、検索クエリからの情報と、存在する場合は商品のインプレッションを組み合わせることによって、アナリティクス 360 から作成されます。

      検索クエリは hits.page.searchKeyword から派生します。hits.customVariables.customVarName が searchQuery の場合は hits.customVariables.customVarValue から派生します。hits.product.isImpressions が TRUE の場合、商品のインプレッションは 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"

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

Search for Retail コンソールまたは userEvents.import メソッドを使用して、Google アナリティクス 360 のイベントをインポートできます。

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"
    }
  }
}'

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 でアナリティクス 360 のホームページ ビューをインポートする

アナリティクス 360 では、ホームページ ビュー イベントは他のページビュー イベントと区別されません。つまり、アナリティクス 360 のイベントをインポートするでは、ホームページ ビュー イベントは、他のイベントタイプ（詳細ページビューなど）のイベントとしてインポートされません。

次の手順では、アナリティクス 360 のデータからホームページ ビュー イベントを抽出し、小売業向け Vertex AI Search にインポートする方法について説明します。これを行うには、ホームページのユーザーのビュー（ホームページのパスで識別）を新しい BigQuery テーブルに抽出してから、その新しいテーブルから小売業向け Vertex AI Search にデータをインポートします。

アナリティクス 360 から小売業向け Vertex AI Search のホームページ ビュー イベントをインポートするには:

1. BigQuery データセットを作成するか、テーブルを追加できる BigQuery データセットがあることを確認します。

   このデータセットは、小売業向け Vertex AI Search のプロジェクトまたはアナリティクス 360 のデータが存在するプロジェクトに配置できます。これは、アナリティクス 360 のホームページ ビュー イベントをコピーするターゲット データセットです。

2. 次のように、データセットに BigQuery テーブルを作成します。

   1. 次の SQL コードの変数を次のように置き換えます。

      • target_project_id: ステップ 1 のデータセットが配置されているプロジェクト。

      • target_dataset: ステップ 1 のデータセット名。

      CREATE TABLE TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage (
       eventType STRING NOT NULL,
       visitorId STRING NOT NULL,
       userId STRING,
       eventTime STRING NOT NULL
      );

   2. SQL コードサンプルをコピーします。

   3. Google Cloud コンソールで [BigQuery] ページを開きます。

      [BigQuery] ページに移動

   4. まだ選択していない場合は、ターゲット プロジェクトを選択します。

   5. [エディタ] ペインに、SQL コードサンプルを貼り付けます。

   6. [play_circle 実行] をクリックし、クエリの実行が完了するまで待ちます。

   このコードを実行すると、target_project_id:target_dataset.ga_homepage_YYYYMMDD 形式のテーブルが作成されます（例、my-project:view_events.ga_homepage_20230115）。

3. アナリティクス 360 のデータテーブルから、前のステップ 2 で作成したテーブルにアナリティクス 360 のホームページ ビュー イベントをコピーします。

   1. 次の SQL サンプルコードの変数を次のように置き換えます。

      • source_project_id: BigQuery テーブルにアナリティクス 360 データを含むプロジェクトの ID。

      • source_dataset: BigQuery テーブルにアナリティクス 360 データを含むソース プロジェクトのデータセット。

      • source_table: アナリティクス 360 のデータを含むソース プロジェクトのテーブル。

      • target_project_id: 前のステップ 2 と同じターゲット プロジェクト ID。

      • target_dataset: 前のステップ 2 と同じターゲット データセット。

      • path: ホームページへのパスです。通常、これは / です。たとえば、ホームページが example.com/ の場合、ただし、ホームページが examplepetstore.com/index.html の場合、パスは /index.html です。

      INSERT INTO `TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage(eventType,visitorId,userID,eventTime)`
      
      SELECT
        "home-page-view" as eventType,
        clientId as visitorId,
        userId,
        CAST(FORMAT_TIMESTAMP("%Y-%m-%dT%H:%M:%SZ",TIMESTAMP_SECONDS(visitStartTime)) as STRING) AS eventTime
      
      FROM
        `SOURCE_PROJECT_ID.SOURCE_DATASET.SOURCE_TABLE`, UNNEST(hits) as hits
      
      WHERE hits.page.pagePath = "PATH" AND visitorId is NOT NULL;

   2. SQL コードサンプルをコピーします。

   3. Google Cloud コンソールで [BigQuery] ページを開きます。

      [BigQuery] ページに移動

   4. まだ選択していない場合は、ターゲット プロジェクトを選択します。

   5. [エディタ] ペインに、SQL コードサンプルを貼り付けます。

   6. [play_circle 実行] をクリックし、クエリの実行が完了するまで待ちます。

4. BigQuery からユーザー イベントをインポートするの手順に沿って、ターゲット テーブルからホームページ ビューのイベントをインポートします。スキーマの選択中に、コンソールを使用してインポートする場合は、[小売ユーザー イベント スキーマ] を選択します。userEvents.import を使用してインポートする場合は、dataSchema 値に user_event を指定します。

5. 手順 1 と 2 で作成したテーブルとデータセットを削除します。

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

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

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

始める前に

次の手順を開始する前に、以下の点をご確認ください。

• Google アナリティクスの e コマース を使用している。
• Google アナリティクス 4 に BigQuery がリンクされています。

データソースを確認する

ユーザー イベントデータがインポート用に準備されていることを確認するには、次の手順を行います。

小売業向け Vertex AI Search が使用する Google アナリティクス 4 フィールドと、それらがマッピングされる小売業向け Vertex AI Search のフィールドの表については、Google アナリティクス 4 のユーザー イベント フィールドをご覧ください。

すべての Google アナリティクス イベント パラメータについては、Google アナリティクス イベントのリファレンス ドキュメントをご覧ください。

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

   • データセットは analytics_PROPERTY_ID という名前である必要があります。
   • テーブルは events_YYYYMMDD という名前である必要があります。

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

2. BigQuery Google Cloud コンソールで、[エクスプローラ] パネルからデータセットを選択し、インポートするユーザー イベントのテーブルを見つけます。

   以下を確認します。

   1. event_params.key 列に currency キーがあり、関連付けられた文字列値が有効な通貨コードである。

   2. search イベントをインポートする予定の場合は、event.event_params.key 列に search_term キーおよび関連する値があることを確認します。

      search イベントのインポートはサポートされますが、search イベントは他のイベントタイプと同様に Google アナリティクス 4 からマッピングされません。これは、小売向け Vertex AI Search の search イベントタイプが Google アナリティクス 4 でネイティブにサポートされていないためです。インポートの際、view_item_list パラメータと search_term パラメータからの情報を組み合わせることにより、Google アナリティクス 4 から search イベントが構築されます。

      Google アナリティクス 4 での search についての詳細は、Google アナリティクス ドキュメントの search をご覧ください。

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

   Google アナリティクス 4 のユーザー テーブルのプロダクトがアップロードされたカタログにも含まれるようにするには、BigQuery テーブル プレビューの event.items.item_id 列からプロダクト ID をコピーし、product.get メソッドを使用して、アップロードしたカタログに商品 ID があるかどうかを確認します。

   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"

BigQuery アクセスを設定する

BigQuery データセットへのアクセスの設定の手順に沿って、小売業向け Vertex AI Serach のサービス アカウントに、BigQuery データセットに対する BigQuery データオーナーロールを付与します。

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

Search for Retail コンソールまたは userEvents.import メソッドを使用して、Google アナリティクス 4 のイベントをインポートできます。

コンソールを使用して Google アナリティクス 4 のイベントをインポートする

1. Search for Retail コンソールの [データ] ページに移動します。
   
   [データ] ページに移動
2. [インポート] をクリックして [インポート データ] パネルを開きます。
3. [User events] を選択します。
4. データソースとして [BigQuery] を選択します。

5. データスキーマを選択します。

   • Google アナリティクス 4: Google アナリティクス 4 のイベントに使用します。
   • Google アナリティクス 360: Google アナリティクス 360 のイベントに使用します。ただし、Google アナリティクス 360 のホームページ ビューのみをインポートする場合は除きます。その場合は、Retail ユーザー イベント スキーマを使用します。
   • Retail ユーザー イベント スキーマ: Google アナリティクス以外のソースからイベントをインポートする場合と、Google アナリティクス 360 のホームページ ビューのみをインポートする場合に使用します。
6. データが配置される BigQuery テーブルを入力します。
7. 省略可: データの一時的なロケーションとして、プロジェクト内の Cloud Storage バケットのロケーションを入力します。
   指定されていない場合、デフォルトのロケーションが使用されます。指定されている場合、BigQuery と Cloud Storage バケットは同じリージョン内に存在する必要があります。
8. 省略可: [詳細設定を表示] で、データの一時的なロケーションとして、プロジェクト内の Cloud Storage バケットのロケーションを入力します。
   
   指定しない場合、デフォルトのロケーションが使用されます。指定する場合、BigQuery と Cloud Storage バケットは同じリージョン内に存在する必要があります。
9. [インポート] をクリックします。

API を使用して Google アナリティクス 4 のイベントをインポートする

ユーザー イベントをインポートするには、userEvents.import メソッドの呼び出しにイベントのデータを含めます。userEvents.import API リファレンスをご覧ください。

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

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": {
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event_ga4"
    }
  }
}'

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

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

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

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

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;
}

過去のカタログ データ

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

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

インポートしたイベントを表示する

Search for Retail コンソールの [データ] ページの [イベント] タブでイベント統合指標を表示します。このページには、去年に書き込みまたはインポートされたすべてのイベントが表示されます。データの取り込みが成功した後、指標が表示されるまでには、最長で 24 時間かかることがあります。

[データ] ページに移動

次のステップ

• ユーザー イベントの記録を開始する。
• ユーザー イベントを管理する。