このページでは、過去のイベントからユーザー イベントデータを一括インポートする方法について説明します。 ユーザー イベントはメディアアプリに必要です。メディアアプリを使用していない場合は、ユーザー イベントのインポートは必要ありません。ただし、カスタム検索アプリとおすすめアプリでは、ユーザー イベントを記録することをおすすめします。
インポートできるユーザー イベントのタイプについては、eventType オブジェクトの
userEvents フィールドをご覧ください。ユーザー イベントをインポートすると、結果の品質を改善できます。たとえば、ユーザー イベントは検索結果のランキングに影響します。クリック率が高い結果はブーストされ、クリック率が低い結果は非表示になります。データストアにすでにインポートされているドキュメントのユーザー
イベントのみをインポートします。
userEvents.Documents にあるドキュメントがイベントに含まれている場合、Agent Search
はイベントをそのドキュメントに自動的に結合します。結合により、Agent Search
は、クリックやビューなどのイベントを検索結果や推奨事項の正しいドキュメントに関連付けることができます。カスタム検索アプリとおすすめアプリの場合、結合は非同期で行われます。つまり、バッチインポートの完了後にユーザーイベントがドキュメントに結合されます（通常は数分以内に完了します）。メディアアプリの場合、結合は同期的に行われます。
Agent Search はバッチ インポートの進行中にユーザー イベントのドキュメントへの結合を開始します。
コンソールで結合されていないイベント指標を表示する方法については、
集計されたユーザーイベント情報を表示するをご覧ください。
複数のデータストアが接続された検索アプリを使用している場合は、データストア レベルではなく、ロケーション レベルでユーザー
イベントをインポートします。これにより、特定のユーザー イベントを関連付けられているデータストアに送信できます。ロケーション
レベルでユーザー イベントをインポートする場合は、イベントを正しいアプリに関連付けるために、ユーザー イベントに engine
フィールドを含めます。engine フィールドを含むユーザー イベントの例については、以下をご覧ください。
インポート方法の詳細については、
userEvents.import をご覧ください。
ユーザー イベントをリアルタイムでインポートするには、 リアルタイム ユーザー イベントを記録するをご覧ください。
過去のイベントは、次の方法でインポートできます。
ユーザー イベントの JSON 表現については、API リファレンスの userEvents をご覧ください。
始める前に
ユーザー イベントをインポートする前に:
- データストアと検索アプリを作成します。
- ユーザー イベントの要件については、 メディア ユーザー イベントについてまたは カスタムアプリのユーザー イベントについて をご覧ください。
Cloud Storage から過去のユーザー イベントをインポートする
メディアアプリがある場合は、ユーザー イベントを Google Cloud コンソールまたは API を使用してインポートできます。他のアプリタイプの場合は、API を使用してのみインポートできます。コンソール
コンソールを使用してメディアアプリのユーザー イベントをインポートするには、次の操作を行います。
コンソールで、[AI アプリケーション] ページに移動します。 Google Cloud
[アプリ] ページで、メディアアプリをクリックします。
[データ] ページに移動します。
メディア レコメンデーション アプリの場合、[要件] タブに、インポートする必要があるメディア ドキュメントとユーザー イベントが表示されます。
[イベント] タブをクリックします。すでにイベントをインポートしている場合は、その情報がこのタブに表示されます。
[イベントをインポート] をクリックします。
データソースとして [Cloud Storage] を選択します。
ユーザー イベントの Cloud Storage のロケーションを入力または選択します。
[インポート] をクリックします。
[アクティビティ] タブにインポートのステータスが表示されます。
インポート エラーが発生した場合は、[アクティビティ] タブで次の操作を行います。
[詳細] 列でエラーを展開し、[詳細を表示] をクリックして、[アクティビティ ログの詳細] ペインで詳細を確認します。
[アクティビティ ログの詳細] ペインで [完全なエラーログを表示] をクリックして、ログ エクスプローラでエラーを確認します。
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）。Agent Search に一時ディレクトリを自動的に作成させるには、この項目を空のままにすることをおすすめします。
データファイルの名前を指定して
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 へのアクセスを設定します。
- 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 コンソールまたは API を使用してユーザー イベントをインポートできます。他のアプリタイプの場合は、API を使用してのみインポートできます。コンソール
コンソールを使用してメディアアプリのユーザー イベントをインポートするには、次の操作を行います。
コンソールで、[AI アプリケーション] ページに移動します。 Google Cloud
[アプリ] ページで、メディアアプリをクリックします。
[データ] ページに移動します。
メディア レコメンデーション アプリの場合、[要件] タブに、インポートする必要があるメディア ドキュメントとユーザー イベントが表示されます。
[イベント] タブをクリックします。すでにイベントをインポートしている場合は、その情報がこのタブに表示されます。
[イベントをインポート] をクリックします。
データソースとして BigQuery を選択します。
ユーザー イベントの BigQuery パスを入力または選択します。
[インポート] をクリックします。
[アクティビティ] タブにインポートのステータスが表示されます。
インポート エラーが発生した場合は、[アクティビティ] タブで次の操作を行います。
[詳細] 列でエラーを展開し、[詳細を表示] をクリックして、[アクティビティ ログの詳細] ペインで詳細を確認します。
[アクティビティ ログの詳細] ペインで [完全なエラーログを表示] をクリックして、ログ エクスプローラでエラーを確認します。
REST
BigQuery から過去のユーザー イベントを一括でインポートするには、次の操作を行います。
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 リクエストでファイルを指定するには、次の操作を行います。
ユーザー イベントデータを含む 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/v1/projects/PROJECT_NUMBER/locations/global/userEvents:import"