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

このページでは、過去のイベントからユーザーイベントデータを一括インポートする方法について説明します。メディアレコメンデーションにはユーザーイベントが必要です。メディアレコメンデーションを使用していない場合は、ユーザーイベントのインポートは必要ありません。ただし、メディア検索アプリの場合は推奨されます。

インポートできるユーザーイベントのタイプについては、userEvents オブジェクトの eventType フィールドをご覧ください。ユーザーイベントをインポートすると、レコメンデーションの品質と検索結果のランキングを改善できます。クリック率が高い検索結果はブーストされ、クリック率が低い検索結果は非表示になります。まだインポートしていないドキュメントのユーザーイベントはインポートしないでください。

userEvents.Documents にあるドキュメントがイベントに含まれている場合、Vertex AI Search はイベントをそのドキュメントに自動的に結合します。結合により、Vertex AI Search はクリックやビューなどのイベントを、検索結果またはレコメンデーション内の正しいドキュメントに関連付けることができます。一般的なユースケースのアプリでは、結合は非同期で行われます。つまり、バッチインポートの完了後にユーザーイベントがドキュメントに結合されます（通常は数分以内に完了します）。メディアアプリの場合、結合は同期的に行われます。Vertex AI Search はバッチインポートの進行中にユーザーイベントのドキュメントへの結合を開始します。コンソールで結合されていないイベント指標を表示する方法については、集計されたユーザーイベント情報を表示するをご覧ください。

ユーザーイベントをリアルタイムでインポートするには、リアルタイムのユーザーイベントを記録するをご覧ください。

過去のイベントは、次の方法でインポートできます。

Cloud Storage から
BigQuery から
ローカル JSON データとして

ユーザーイベントの JSON 表現については、API リファレンスの userEvents をご覧ください。

始める前に

ユーザーイベントをインポートする前に:

データストアとアプリを作成します。
ユーザーイベントの要件については、ユーザーイベントについてをご覧ください。

Cloud Storage から過去のユーザーイベントをインポートする

メディアアプリがある場合は、Google Cloud コンソールまたは API を使用してユーザーイベントをインポートできます。他のアプリタイプの場合は、API を使用してのみインポートできます。

コンソール

コンソールを使用してメディアアプリのユーザーイベントをインポートする手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
[アプリ] ページで、メディアアプリをクリックします。
[データ] ページに移動します。

メディアレコメンデーションアプリの場合、[要件] タブに、インポートする必要があるメディアドキュメントとユーザーイベントが表示されます。
[イベント] タブをクリックします。イベントをすでにインポートしている場合は、そのイベントに関する情報がこのタブに表示されます。
[イベントをインポート] をクリックします。
データソースとして [Cloud Storage] を選択します。
ユーザーイベントの Cloud Storage のロケーションを入力または選択します。
[インポート] をクリックします。
[アクティビティ] タブにインポートのステータスが表示されます。
インポートエラーが発生した場合は、[アクティビティ] タブで次の操作を行います。
1. [詳細] 列でエラーを開き、[詳細を表示] をクリックして、[アクティビティログの詳細] ペインで詳細を確認します。
2. [アクティビティログの詳細] ペインで [エラーログ全体を表示] をクリックして、ログエクスプローラでエラーを確認します。

REST

過去のユーザーイベントを Cloud Storage から一括インポートするには、次の操作を行います。

インポートの入力パラメータ用に 1 つ以上のデータファイルを作成します。gcsSource オブジェクトを使用して、Cloud Storage バケットを参照します。
```
{
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}
```
- INPUT_FILE: ユーザーイベントデータが格納されている Cloud Storage 内のファイル。各ユーザーイベントは、改行がないそれ自体の単一の行であることを確認してください。ユーザーイベントの JSON 表現については、API リファレンスの userEvents をご覧ください。入力ファイルのフィールドは gs://<bucket>/<path-to-file>/ の形式にする必要があります。
- ERROR_DIRECTORY: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ（例: gs://<your-gcs-bucket>/directory/import_errors）。Vertex AI Agent Builder に一時ディレクトリを自動的に作成させるには、このフィールドを空のままにすることをおすすめします。

データファイルの名前を指定して userEvents:import メソッドに対して 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 print-access-token)"" \
    --data @DATA_FILE.json \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

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

BigQuery でユーザーイベントのテーブルを作成する場合は、ユーザーイベントについてで説明されているスキーマを使用します。

BigQuery アクセスを設定する

BigQuery データセットがデータストアとは異なるプロジェクトにある場合は、次の手順で BigQuery へのアクセスを設定します。

Google Cloud コンソールで [IAM と管理] ページを開きます。
ユーザーイベントをインポートするデータストアを含むプロジェクトを選択します。
[Google 提供のロール付与を含める] チェックボックスをオンにします。
Discovery Engine サービスアカウントという名前のサービスアカウントを探します。
以前に Discovery Engine でインポートオペレーションを開始していない場合、このサービスアカウントが表示されない可能性があります。このサービスアカウントが表示されない場合は、インポートタスクに戻ってインポートを開始します。権限エラーで失敗した場合は、ここに戻ってこのタスクを完了してください。Discovery Engine サービスアカウントが表示されます。
メールアドレスのようなサービスアカウントの ID（例: service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com）をコピーします。
（同じ [IAM と管理] ページで）BigQuery プロジェクトに切り替え、[アクセスを許可] をクリックします。
[新しいプリンシパル] で、サービスアカウントの ID を入力し、[BigQuery] > [BigQuery データ閲覧者] ロールを選択します。
[保存] をクリックします。

BigQuery へのアクセスの詳細については、BigQuery ドキュメントのデータセットへのアクセスの制御をご覧ください。

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

コンソール

コンソールを使用してメディアアプリのユーザーイベントをインポートする手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
[アプリ] ページで、メディアアプリをクリックします。
[データ] ページに移動します。

メディアレコメンデーションアプリの場合、[要件] タブに、インポートする必要があるメディアドキュメントとユーザーイベントが表示されます。
[イベント] タブをクリックします。イベントをすでにインポートしている場合は、そのイベントに関する情報がこのタブに表示されます。
[イベントをインポート] をクリックします。
データソースとして BigQuery を選択します。
ユーザーイベントの BigQuery パスを入力または選択します。
[インポート] をクリックします。
[アクティビティ] タブにインポートのステータスが表示されます。
インポートエラーが発生した場合は、[アクティビティ] タブで次の操作を行います。
1. [詳細] 列でエラーを開き、[詳細を表示] をクリックして、[アクティビティログの詳細] ペインで詳細を確認します。
2. [アクティビティログの詳細] ペインで [エラーログ全体を表示] をクリックして、ログエクスプローラでエラーを確認します。

REST

過去のユーザーイベントを Cloud Storage から一括インポートするには、次の操作を行います。

BigQuery プロジェクトの名前、データセット ID、テーブル ID を指定して userEvents:import メソッドに対して POST リクエストを実行し、ユーザーイベントをインポートします。

イベントをインポートする際は、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 print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1beta/projects/[PROJECT_NUMBER]/locations/global/dataStores/DATA_STORE_ID/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

過去のユーザーイベントをローカル JSON データとしてインポートする

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

ユーザーイベントデータを JSON ファイルに保存し、API リクエストでファイルを指定する手順は次のとおりです。

ユーザーイベントデータを含む JSON ファイルを作成します。ユーザーイベントの JSON 表現については、API リファレンスドキュメントの userEvents をご覧ください。
```
{
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}
```

データファイルの名前を指定して userEvents:import メソッドに対して POST リクエストを実行し、イベントをインポートします。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @[JSON_FILE] \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

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

始める前に

Cloud Storage から過去のユーザー イベントをインポートする

コンソール

REST

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

BigQuery アクセスを設定する

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

コンソール

REST

過去のユーザー イベントをローカル JSON データとしてインポートする

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

Cloud Storage から過去のユーザーイベントをインポートする

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

過去のユーザーイベントをローカル JSON データとしてインポートする