This page describes how to import, view, update, and delete user events. For information about recording user events as they happen, see Recording user events.
Listing user events
You can list user events that you have previously recorded. You use a filter string to specify which user events you want returned.
curl
This example lists user events with a type of purchase-complete
for a specific
time period that are missing corresponding catalog items.
curl -X GET -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \ "https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/catalogs/default_catalog/eventStores/default_event_store/userEvents?filter=eventType%3Dpurchase-complete%20eventTime%20%3E%20%222018-04-23T18%3A25%3A43.511Z%22%20eventTime%20%3C%20%222019-02-12T18%3A30%3A43.511Z%22%20eventsMissingCatalogItems"
The decoded filter string looks like this:
filter= eventType=purchase-complete eventTime > "2018-04-23T18:25:43.511Z" eventTime < "2019-02-12T18:30:43.511Z" eventsMissingCatalogItems
Rejoining user events
You can rejoin user events by making a POST
request to the
userEvents:rejoin
endpoint.
The rejoin operation joins specified events with the latest version of the product catalog.
A user event is considered unjoined if the item it is associated with isn't present in the catalog at the time that the user event is ingested. Unjoined events lack detailed product information and are not as useful to training models and serving results.
In addition to addressing unjoined events, the rejoin operation can be used to correct events that have been joined with the wrong product catalog.
You must have the Recommendations AI Admin IAM role to call this method.
curl
Set user_event_rejoin_scope
according to the types of events you're rejoining:
0
: Trigger rejoin for both joined and unjoined events.JOINED_EVENTS
: Trigger rejoin for only joined events.UNJOINED_EVENTS
: Trigger rejoin for only unjoined events.
The following example triggers a rejoin for only unjoined events:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ 'user_event_rejoin_scope': 'UNJOINED_EVENTS' }" \ "https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/catalogs/default_catalog/eventStores/default_event_store/userEvents:rejoin"
Removing user events
Generally, you should leave user events in place after they have been recorded.
However, if you have user events that were not recorded properly, you can
remove them from your event store using the
eventStores.userEvents.purge
method.
Specify the events you want to remove by using a filter string. This
supports selectively deleting user events by filtering on the eventTime
,
eventType
, visitorID
, and userID
fields.
Because you cannot undo the delete, test your filter string by using it to list
events before using it to delete them. The force
field is set to false
by
default; this setting will return the list of events without deleting them. When
you are ready to actually delete the user events, set the force
field to
true
.
curl
This example filters for a time range, which must use the Zulu Time date format.
Setting the force
field to true
forces the delete to occur. To view the list
of events instead of deleting them, set force
to 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":"true" }' \ "https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/catalogs/default_catalog/eventStores/default_event_store/userEvents:purge"
Viewing aggregated user event information
You can view the number of recorded user events for your project in the Event tab on the Recommendations AI Data page. Metrics will appear about 24 hours after you first upload events to Recommendations AI.
Using the user event filter
You can filter the results for listing user events.
The filter is a string that contains one or more of the following restrictions:
eventTime
Provides a timestamp to bound the events listed or deleted. This filter can be specified once or twice, with a greater-than (>) or less-than (<) symbol. The bounded time must be a single, contiguous block.
eventType
Restrict the events listed or deleted to a single event type.
eventsMissingCatalogItems
By default, only events for which a catalog item was found are listed or deleted. If you specify this flag, only events for which a catalog item was not found are listed or deleted.
visitorID
Restrict the events listed or deleted to a single visitor ID.
userID
Restrict the events listed or deleted to a single user ID.
Only items that satisfy all of the restrictions are listed or deleted.
To list all user events of type add-to-cart
that were logged
on or after February 1, 2019, you would provide the following filter string:
eventTime > "2019-02-01T00:00:00Z" eventType = add-to-cart
To list all user events with catalog items that are not found in the catalog (unjoined events), you would provide the following filter string:
eventsMissingCatalogItems