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

このページでは、過去のイベントからユーザー イベントデータを一括インポートする方法について説明します。

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

userEvents.Documents にあるドキュメントがイベントに含まれている場合、Gemini Enterprise はイベントをそのドキュメントに自動的に結合します。結合により、Gemini Enterprise は、クリックやビューなどのイベントを検索結果や推奨事項の正しいドキュメントに関連付けることができます。カスタム検索アプリとおすすめアプリの場合、結合は非同期で行われます。つまり、バッチ インポートの完了後にユーザー イベントがドキュメントに結合されます（通常は数分以内に完了します）。

複数のデータストアが接続された検索アプリを使用している場合は、データストア レベルではなく、ロケーション レベルでユーザー イベントをインポートします。これにより、特定のユーザー イベントを関連付けられているデータストアに送信できます。ロケーション レベルでユーザー イベントをインポートする場合は、イベントを正しいアプリに関連付けるために、ユーザー イベントに engine フィールドを含めます。engine フィールドを含むユーザー イベントの例については、以下をご覧ください。

インポート方法の詳細については、userEvents.import をご覧ください。

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

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

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

始める前に

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

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

REST

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

  1. インポートの入力パラメータのデータファイルを 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）。Gemini Enterprise に一時ディレクトリを自動的に作成させるには、このフィールドを空のままにすることをおすすめします。

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

    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/v1/projects/PROJECT_NUMBER/locations/global/userEvents:import"

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

BigQuery でユーザー イベントのテーブルを作成する場合は、カスタムアプリのユーザー イベントについてで説明されているスキーマを使用します。各 search ユーザー イベントには、イベントをアプリに関連付ける engine フィールドを含める必要があります。詳しくは、engine をご覧ください。

BigQuery アクセスを設定する

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

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

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

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

REST

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

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

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

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

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

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

ユーザー イベントデータを JSON ファイルに追加し、API リクエストでファイルを指定するには、次の操作を行います。

  1. ユーザー イベントデータを含む JSON ファイルを作成します。ユーザー イベントの JSON 表現については、API リファレンス ドキュメントの userEvents をご覧ください。

    {
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}

  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/v1/projects/PROJECT_NUMBER/locations/global/userEvents:import"