ユーザー イベントを管理する

このページでは、ユーザー イベントを表示、削除する方法について説明します。ユーザー イベントが発生した際の記録については、リアルタイムのユーザー イベントの記録をご覧ください。過去のイベントからユーザー イベントデータをインポートするには、過去のユーザー イベントのインポートをご覧ください。

ユーザー イベントの再結合のチュートリアル

このチュートリアルでは、userEvents:rejoin エンドポイントに POST リクエストを送信してユーザー イベントを再結合する方法を説明します。

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

ガイドを表示

ユーザー イベント チュートリアルを削除する

このチュートリアルでは、ユーザー イベントを完全に削除する方法を説明します。

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

ガイドを表示

集計されたユーザー イベント情報を表示する

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

[データ] ページに移動

Vertex AI Search for Retail のユーザー イベントの統計情報

ユーザー イベントに再結合する

カタログ イベントを再結合するには、POST リクエストを userEvents:rejoin エンドポイントに送信します。

再結合オペレーションによって、指定されたイベントと最新バージョンの商品カタログが結合されます。

ユーザー イベントが取り込まれるときに、関連付けられている商品がカタログに存在しない場合、そのユーザー イベントは未結合とみなされます。未結合のイベントは詳細な商品情報がないため、モデルのトレーニングや結果の提供には役立ちません。

結合されていないイベントへの対応に加えて、再結合オペレーションを使用して、誤った商品カタログに結合されたイベントを修正できます。

このメソッドを呼び出すには、Retail AI 管理者 IAM ロールが必要です。再結合オペレーションが完了するまでに、数時間から数日かかることがあります。

curl

再結合するイベントの種類に応じて userEventRejoinScope を設定します。

  • USER_EVENT_REJOIN_SCOPE_UNSPECIFIED: デフォルト。結合イベントと結合されていないイベントの両方の再結合をトリガーします。
  • JOINED_EVENTS: 結合されたイベントにのみ再結合をトリガーします。
  • UNJOINED_EVENTS: 結合されていないイベントにのみ再結合をトリガーします。

次の例は、結合されていないイベントのみの再結合をトリガーします。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
     'userEventRejoinScope': 'UNJOINED_EVENTS'
     }" \
    "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:rejoin"

次のようなレスポンス オブジェクトが返されます。

{
  "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/OPERATION_ID"
}

再結合のステータスを確認できます。OPERATION_ID を、再結合メソッドによって返されたオペレーション ID に置き換えます。

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/OPERATION_ID"

オペレーションが完了すると、オペレーションのステータスは done として返されます。

{
  "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/OPERATION_ID",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2.RejoinUserEventsResponse",
    "rejoinedUserEventsCount": "1"
  }
}

Java

public static String rejoinUserEvents(UserEventRejoinScope scope)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  RejoinUserEventsRequest request = RejoinUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEventRejoinScope(scope)
      .build();

  String operationName = userEventsClient
      .rejoinUserEventsAsync(request).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

ユーザー イベントを削除する

通常、ユーザー イベントは記録後、所定の保存場所にそのままにしておく必要があります。イベントを完全に削除することはおすすめしません。

イベントの削除が完了するまで数日かかる可能性があります。ユーザー イベントを完全にリセットする予定の場合は、代わりに新しいプロジェクトの作成を検討してください。

正しく記録されていないユーザー イベントがある場合に、このイベントを削除するには、userEvents.purge メソッドを使用します。

フィルタ文字列を使用して、削除するイベントを指定します。これにより、eventTime、eventType、visitorID、userID の各フィールドでフィルタリングし、ユーザー イベントを選択的に削除します。

削除を取り消すことはできないため、ユーザー イベントを削除する前に、ドライランを実行してフィルタ文字列をテストしてください。force フィールドは、デフォルトで false に設定されています。この設定の場合、ユーザー イベントは実際に削除されず、削除されるイベントの数が返されます。ユーザー イベントを実際に削除する準備ができたら、force フィールドを true に設定します。

curl

この例では、期間でフィルタリングをします。期間は、Zulu 時間日付形式を使用する必要があります。force フィールドは false に設定されています。

curl -X POST \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data '{
    "filter":"eventTime > \"2019-12-23T18:25:43.511Z\" eventTime < \"2019-12-23T18:30:43.511Z\"",
    "force":"false"
  }' \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:purge"

次のようなレスポンス オブジェクトを受け取ります。purge-user-events-54321 はオペレーション ID です。

{
  "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/purge-user-events-54321"
}

この例では、オペレーションのステータスをリクエストします。

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/OPERATION_ID"

オペレーションのステータスの例:

{
  "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/OPERATION_ID",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2.PurgeUserEventsResponse",
    "purgedEventsCount": "1"
  }
}

force フィールドを true に設定すると、強制的に削除されます。

curl -X POST \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data '{
    "filter":"eventTime > \"2019-12-23T18:25:43.511Z\" eventTime < \"2019-12-23T18:30:43.511Z\"",
    "force":"true"
  }' \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:purge"

Java

public static String purgeUserEvents(
    String filter)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  PurgeUserEventsRequest request = PurgeUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setFilter(filter)
      .setForce(true)
      .build();

  String operationName = userEventsClient
      .purgeUserEventsAsync(request).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

ユーザー イベント フィルタを使用する

削除するユーザー イベントをフィルタできます。

フィルタは、次の条件の 1 つ以上を含む文字列です。

  • eventTime

    削除するイベントに結びつけるタイムスタンプを指定します。このフィルタは、大なり記号（>）または小なり記号（<）とともに、1 回または 2 回指定できます。結びつける時間は、連続する単一のブロックにする必要があります。

  • eventType

    削除するイベントを単一のイベントタイプに限定します。

  • visitorID

    削除するイベントを単一の訪問者 ID に限定します。

  • userID

    削除するイベントを単一のユーザー ID に限定します。

すべての条件を満たすユーザー イベントのみが削除されます。

2019 年 2 月 1 日以降に記録された add-to-cart タイプのすべてのユーザー イベントを削除するには、次のフィルタ文字列を指定します。

eventTime > "2019-02-01T00:00:00Z" eventType = add-to-cart