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

このページでは、過去のイベントからユーザーイベントデータを Vertex AI Search for Commerce に一括インポートする方法について説明します。モデルのトレーニングにはユーザーイベントデータが必要です。イベントの記録の設定後、モデルのトレーニングに十分なユーザーイベントデータが記録されるまでに、かなりの時間がかかる場合があります。過去のデータをインポートすると、プロセスを加速できます。

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

次の場所から予定をインポートできます。

Cloud Storage。
（BigQuery など）へのレプリケーションを円滑にします。
Google アナリティクス 360 イベントの BigQuery。
Google アナリティクス 4 のイベントの BigQuery。
userEvents.import メソッドを使用して、インラインでイベントをインポートします。

始める前に

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

ユーザーイベントの記録に関するベストプラクティスを確認します。
ユーザーイベントの形式は、ユーザーイベントタイプによって異なります。各イベントタイプの表を作成するときに指定する形式については、ユーザーイベントタイプとサンプルスキーマをご覧ください。
レコメンデーションと検索では、最小データ要件が異なります。ユーザーイベントが、使用するサービスの要件を満たしていることを確認してください。
- 検索とレコメンデーションの要件については、ユーザーイベントの要件とベストプラクティスをご覧ください。
- また、レコメンデーションモデルを使用する場合は、ユーザーイベントデータの要件もご覧ください。使用する予定のレコメンデーションモデルのタイプと最適化目標に応じた追加の要件を示しています。

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

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

インポートソース	説明	使用する状況	制限事項
Cloud Storage	Google Cloud コンソールまたは `curl` を使用して、ファイルから JSON データをインポートします（≤ 2 GB、最大 100 個）。カスタム属性をサポートします。	1 回のステップで大量のデータを読み込む。	GA データは、Cloud Storage に移動する前に BigQuery に別途エクスポートする必要があります。
BigQuery	Google Cloud コンソールまたは `curl` を使用して、Vertex AI Search for Commerce スキーマを使用する BigQuery テーブルからインポートします。	インポート前にイベントデータを前処理または分析する。	スキーマの手動マッピングが必要。イベント量が多い場合、リソース費用が高くなる。
BigQuery + Google アナリティクス 360	既存の Google アナリティクス 360 データを Vertex AI Search for Commerce に直接インポートします。	既存の GA360 コンバージョントラッキング。スキーマを手動でマッピングする必要はありません。	利用可能な属性のサブセットは限定的です。検索には GA インプレッショントラッキングが必要です。
BigQuery + Google アナリティクス 4	既存の Google アナリティクス 4 データを Vertex AI Search for Commerce に直接インポートします。	既存の GA4 コンバージョントラッキング。スキーマを手動でマッピングする必要はありません。	利用可能な属性のサブセットは限定的です。検索には `search_query` イベントパラメータキーが必要です。
インラインインポート	直接 `userEvents.import` メソッド呼び出しを使用してインポートします。	プライバシー保護レベルの高いバックエンドの認証要件。	標準のウェブベースのインポートよりも実装が複雑です。

サイズの制限

システムの上限は、ユーザーイベントの合計で 400 億件です。取り込みプラットフォームごとのデータインポートのサイズ制限は次のとおりです。

Cloud Storage からの一括インポートの場合、各ファイルは 2 GB 以下である必要があります。1 回の一括インポートリクエストに含めることができるファイル数は最大 100 個です。
BigQuery のインポートの場合、サイズの上限は 128 GB です。
インラインインポートの場合、リクエストごとに推奨されるユーザーイベントの最大数は 10,000 件です。
モデルのトレーニングと検索の最適化のために、ライブユーザーイベントを記録するか、過去のユーザーイベントをインポートする最小日数を設定します。最初のモデルのトレーニングとチューニングには 2 ～ 5 日かかりますが、大規模なデータセットの場合はさらに時間がかかることがあります。

検索イベントをユーザー操作にリンクする

収益最適化ランキング（階層 3）とパーソナライズ（階層 4）を有効にするには、一般的な search イベントをアップロードするだけでは不十分です。Vertex AI Search モデルでは、特定のクエリに対してどの商品がパフォーマンスを発揮しているかを学習するために、ユーザーの意図と満足度を示す強力なシグナルが必要です。このシグナルは、アトリビューション可能なユーザー操作によって提供されます。後続のイベント（具体的には detail-page-view、add-to-cart、purchase-complete）をアップロードする必要があります。

ユーザーの操作が重要な理由

関連性シグナル: search イベントは、ユーザーが何を求めていたかをモデルに伝えます。detail-page-view（クリック）は、どの結果が関連性があったかをモデルに伝えます。
収益シグナル: add-to-cart イベントと purchase-complete イベントは、実際のビジネス価値を高める結果をモデルに伝えます。

最適化のデータ品質のしきい値

収益最適化モデルを有効にするには、データが特定の量と品質の基準を満たしている必要があります。

次の指標は必須です。

指標	要件	コンテキスト
アトリビューション可能なクリック数	過去 30 日間の `detail-page-view` イベント数: 250,000	これらは、検索結果にリンクする有効なユーザー操作が必要です。
検索イベントのボリューム	過去 90 日間に 2,000,000 件のイベントが発生している	統計的有意性を確立するには、過去の検索トラフィックの大きなベースラインが必要です。
クリック密度	プロダクトごとに平均 10 件の `detail-page-view` イベント	モデルがカタログ全体で十分なシグナルカバレッジを確保します（過去 30 日間）。
コンバージョンシグナル	プロダクトあたりの平均 `add-to-cart` イベント数が 0.5	収益を最大化する目標を最大限に活用することをおすすめします。
料金マッチ率	検索された商品の 95% に価格が表示されている	返品される商品の価格がわからない場合、モデルは収益を最適化できません。

詳細については、データ品質のページをご覧ください。

BigQuery または Cloud Storage を使用した一括インポート

Vertex AI Search for Commerce でユーザーイベントデータのステージングエリアとして BigQuery または Cloud Storage を使用すると、次のようなメリットがあります。

復元性の強化: BigQuery または Cloud Storage にイベントを保存すると、信頼性の高いバックアップメカニズムが提供され、必要に応じてパージと再取り込みが可能になります。この復元力により、エラーや不整合が発生した場合のデータ損失を防ぎ、復元を簡素化できます。インポート方法には、取り込まれなかったイベントがエラーの詳細とともにエラーバケットに保存される組み込みの復元力もあります。
インプレースカスタム分析: BigQuery でイベントに簡単にアクセスできるため、追加のデータエクスポートや転送プロセスを必要とせずに、ユーザーイベントデータに対してカスタム分析を直接実行できます。これにより、分析ワークフローとリアルタイムの分析情報が可能になります。
既存のイベントを使用する: 一括インポートでは、さまざまな形式で収集された既存のユーザーイベントデータを使用できます。簡単な抽出、変換、読み込み（ETL）プロセスで、このデータを Vertex AI Search for Commerce 形式に変換できるため、大規模なフロントエンドの変更や複雑な統合は不要です。

一括インポートの潜在的なデメリットは次のとおりです。

リアルタイムのパーソナライズの制限: リアルタイムのパーソナライズ機能は、一括インポートの頻度によって制約されます。イベントの生成と取り込みの間の時間差は、パーソナライズされた検索結果の応答性に影響する可能性があります。
KPI の測定とエラー報告の遅延: リアルタイムストリーミングと比較して、一括インポートでは、プロセスのバッチ指向の性質により、KPI の測定とエラー報告に遅延が生じます。これにより、新たなトレンドや問題に迅速に対応できなくなる可能性があります。
ETL パイプラインインフラストラクチャ: リアルタイムストリーミングと比較して、ETL パイプラインは構築して障害をモニタリングする必要があります。失敗したイベントのインポートを再試行するメカニズム（修正後）も実装する必要があります。これを実装するには、初期の開発作業が必要になる場合があります。

これらのトレードオフを理解することで、Vertex AI Search for Commerce 内の特定のユースケースと優先事項に最適なユーザーイベント取り込みアプローチを選択できます。

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

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

コンソール

Search for commerce コンソールの [データ] ページに移動します。

[データ] ページに移動
[インポート] をクリックして [インポートデータ] パネルを開きます。
[User events] を選択します。
データソースとして [Google Cloud Storage] を選択します。
スキーマとして [Retail ユーザーイベントスキーマ] を選択します。
データの Cloud Storage のロケーションを入力します。
[インポート] をクリックします。

curl

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

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

複数のファイルを指定することも、1 つを指定することもできます。
- INPUT_FILE: ユーザーイベントデータが格納されている Cloud Storage 内の 1 つまたは複数のファイル。各ユーザーイベントタイプのフォーマットの例については、ユーザーイベントについてをご覧ください。各ユーザーイベントは、改行がないそれ自体の単一の行であることを確認してください。
- ERROR_DIRECTORY: インポートに関するエラー情報用の Cloud Storage ディレクトリ。
入力ファイルフィールドは gs://<bucket>/<path-to-file>/ の形式にする必要があります。エラーディレクトリは、gs://<bucket>/<folder>/ の形式にする必要があります。エラーディレクトリが存在しない場合は、Vertex AI Search for Commerce によって作成されます。バケットはすでに存在している必要があります。
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  },
  "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```

カタログ情報をインポートするには、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 からユーザーイベントは、 Google Cloud コンソールか userEvents.import メソッドを使用してインポートします。

BigQuery アクセスを設定する

BigQuery データセットへのアクセスの設定の手順に沿って、Vertex AI Search for commerce のサービスアカウントに、インポートを成功させるために必要な最小限の BigQuery ユーザーロールと、BigQuery データセットに対する追加の BigQuery データ編集者ロールを付与します。BigQuery データオーナーのロールは不要です。

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

ユーザーイベントをインポートするには、コマースコンソールまたは userEvents.import メソッドを使用します。

コンソール

Search for commerce コンソールの [データ] ページに移動します。

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

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

curl

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

dataSchema に指定する値は、インポートする内容によって異なります。

user_event_ga4: Google アナリティクス 4 のイベントに使用します。
user_event_ga360: Google アナリティクス 360 のイベントに使用します。ただし、Google アナリティクス 360 からホームページビューのみをインポートする場合は除きます。その場合は、user_event を使用します。
user_event: Google アナリティクス以外のソースからイベントをインポートする場合と、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": "DATASET_ID",
      "tableId": "TABLE_ID",
      "dataSchema": "SCHEMA_TYPE"
  }
}
}'

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

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

始める前に

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

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

データソースを確認する

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

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

テーブルの形式と命名の詳細については、Google アナリティクスのドキュメントをご覧ください。
BigQuery Google Cloud コンソールで、[エクスプローラ] パネルからテーブルを選択してテーブルをプレビューします。

以下を確認します。
1. clientId 列に有効な値（たとえば、123456789.123456789）がある。
  
  この値は、完全な _ga Cookie 値（GA1.3.123456789.123456789 のような形式）とは異なります。
2. hits.transaction.currencyCode 列に有効な通貨コードがある。
  
  注: Vertex AI Search for Commerce の purchase-complete イベントタイプには通貨コードが必要です。一部の Vertex AI Search for Commerce モデルで必要となる購入イベントをインポートする場合は、拡張 e コマースレポートを更新して通貨コードを含めます。
3. search イベントをインポートする予定の場合は、hits.page.searchKeyword 列または hits.customVariable.searchQuery 列が存在することを確認します。
  
  Vertex AI Search for Commerce では、searchQuery と productDetails の両方で検索結果のリストを返す必要がありますが、アナリティクス 360 では、検索クエリと商品のインプレッションの両方が 1 つのイベントに保存されることはありません。Vertex AI Search for Commerce を機能させるには、データレイヤーでタグを作成するか、JavaScript ピクセルを作成して、Google アナリティクスのソースから両方のタイプのユーザーイベントをインポートできるようにする必要があります。
  - searchQuery（search_term パラメータまたは view_search_results イベントから読み取られる）は、hits.page.searchKeyword から、または hits.customVariables.customVarName が searchQuery の場合は hits.customVariables.customVarValue から派生します。
  - productDetails: view_item_list イベントの items パラメータから読み取られる商品インプレッションは、hits.product.isImpressions が TRUE の場合、hits.product から取得されます。

アップロードされたカタログとアナリティクス 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"

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

コンソール

Search for commerce コンソールの [データ] ページに移動します。

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

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

REST

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

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

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

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

BigQuery でアナリティクス 360 のホームページビューをインポートする

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

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

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

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

このデータセットは、Vertex AI Search for Commerce のプロジェクトまたはアナリティクス 360 のデータが存在するプロジェクトに配置できます。これは、アナリティクス 360 のホームページビューイベントをコピーするターゲットデータセットです。
データセットに次のように 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. [ 実行] をクリックし、クエリの実行が完了するまで待ちます。
このコードを実行すると、target_project_id:target_dataset.ga_homepage_YYYYMMDD 形式のテーブルが作成されます（例、my-project:view_events.ga_homepage_20230115）。
アナリティクス 360 のデータテーブルから、アナリティクス 360 のホームページ表示イベントを、前のステップ 2 で作成したテーブルにコピーします。
1. 次の SQL サンプルコードの変数を次のように置き換えます。
  - source_project_id: BigQuery テーブルにアナリティクス 360 データを含むプロジェクトの ID。
  - source_dataset: BigQuery テーブルにアナリティクス 360 データを含むソースプロジェクトのデータセット。
  - source_table: アナリティクス 360 のデータを含むソースプロジェクトのテーブル。
  - target_project_id: 前の手順 2 と同じターゲットプロジェクト ID。
  - target_dataset: 前の手順と同じターゲットデータセット。
  - 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. [ 実行] をクリックし、クエリの実行が完了するまで待ちます。
BigQuery からユーザーイベントをインポートするの手順に沿って、ターゲットテーブルからホームページビューのイベントをインポートします。スキーマの選択中に、コンソールを使用してインポートする場合は、[小売ユーザーイベントスキーマ] を選択します。userEvents.import を使用してインポートする場合は、dataSchema 値に user_event を指定します。
ステップ 1 と 2 で作成したテーブルとデータセットを削除します。

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

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

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

始める前に

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

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

データソースを確認する

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

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

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

インポートするユーザーイベントデータが、アクセス権のある BigQuery テーブルで正しくフォーマットされていることを確認してください。
- データセットは analytics_PROPERTY_ID という名前である必要があります。
- テーブルは events_YYYYMMDD という名前である必要があります。
テーブルの名前と形式の詳細については、Google アナリティクスのドキュメントをご覧ください。
BigQuery Google Cloud コンソールで、[エクスプローラ] パネルからデータセットを選択し、インポートするユーザーイベントのテーブルを見つけます。

以下を確認します。
1. event_params.key 列に currency キーがあり、関連付けられた文字列値が有効な通貨コードである。
  
  注: Vertex AI Search for Commerce の purchase-complete イベントタイプには通貨コードが必要です。一部の Vertex AI Search for Commerce モデルで必要となる購入イベントをインポートする場合は、イベントレポートを更新して通貨コードを含めます。
2. search イベントをインポートする予定の場合は、event.event_params.key 列に search_term キーおよび関連する値があることを確認します。
  
  Vertex AI Search for Commerce では、searchQuery と productDetails の両方が検索結果のリストを返す必要がありますが、Google アナリティクス 4 では、検索クエリと商品インプレッションの両方が 1 つのイベントに保存されません。Vertex AI Search for Commerce を機能させるには、データレイヤまたは JavaScript ピクセルでタグを作成して、Google アナリティクスソースから両方のタイプのユーザーイベントをインポートできるようにする必要があります。
  - searchQuery（search_term パラメータまたは view_search_results イベントから読み取られます）。
  - productDetails: view_item_list イベントの items パラメータから読み取られる商品インプレッション。
  Google アナリティクス 4 での search についての詳細は、Google アナリティクスドキュメントの search をご覧ください。
アップロードされたカタログと 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"
```

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

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

コンソールを使用する

Search for commerce コンソールの [データ] ページに移動します。

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

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

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 に提供することです。

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

curl

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

{
  "inputConfig": {
    "userEventInlineSource": {
      "userEvents": [
        \{
          "<userEvent1>"
        \},
        \{
          "<userEvent2>"
        \},
        \....
      \]
    \}
  }
}

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

過去のカタログデータ

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

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

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

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

[データ] ページに移動

A/B テストの評価

テストの目標に応じて、A/B テストには次のパラメータが適用されます。

クリック率（CTR）目標の場合は、少なくとも 21 日間のユーザーイベントまたは特定のイベント数が必要です。たとえば、検索イベントが 200 万件以上、検索クリック数が 50 万件以上の場合です。
コンバージョン率（CVR）または収益の目標を設定する場合は、28 日以上のユーザーイベントまたは特定のイベント数が必要です。たとえば、検索イベント数が 400 万件超、検索クリック数が 100 万件超、検索可能な商品あたりの購入イベント数が 0.5 超などです。

A/B テストとベストプラクティスの詳細については、A/B テストのページをご覧ください。

次のステップ

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

過去のユーザー イベントをインポートする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

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

サイズの制限

検索イベントをユーザー操作にリンクする

ユーザーの操作が重要な理由

最適化のデータ品質のしきい値

BigQuery または Cloud Storage を使用した一括インポート

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

コンソール

curl

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

BigQuery アクセスを設定する

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

コンソール

curl

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

始める前に

データソースを確認する

コンソール

REST

Java

BigQuery でアナリティクス 360 のホームページ ビューをインポートする

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

始める前に

データソースを確認する

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

コンソールを使用する

API を使用する

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

curl

Java

過去のカタログ データ

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

A/B テストの評価

次のステップ

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

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

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

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

BigQuery でアナリティクス 360 のホームページビューをインポートする

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

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

過去のカタログデータ