Uso de la PutEvents operación

Después de crear un conjunto de datos de interacciones de elementos y un rastreador de eventos para su grupo de conjuntos de datos, estará listo para registrar los eventos de interacción de elementos. Para registrar eventos de interacción de elementos, use la operación de la API PutEvents. En las siguientes secciones se muestra cómo registrar un solo evento, cómo registrar varios eventos con datos sobre el valor del evento y cómo incluir datos de impresiones en un evento.

Para obtener información sobre cómo registrar eventos para usuarios anónimos, consulte Registro de eventos para usuarios anónimos.

Registro de un solo evento de interacción de elementos

En el ejemplo siguiente se muestra una operación PutEvents que pasa un evento de interacción de elementos. Se muestra el esquema correspondiente, junto con una fila de ejemplo del conjunto de datos de interacciones de elementos.

La aplicación genera un sessionId único cuando un usuario visita por primera vez su sitio web o utiliza su aplicación. Debe usar el mismo sessionId en todos los eventos de la sesión. Amazon Personalize usa sessionId para asociar eventos con el usuario antes de que inicie sesión (es anónimo). Para obtener más información, consulte Registro de eventos para usuarios anónimos.

La lista de eventos es una matriz de objetos Event. eventTypeSe requiere una para cada evento. Si no tienes datos sobre el tipo de evento, puedes proporcionar un valor de marcador de posición para cumplir con el requisito.

trackingId proviene del rastreador de eventos que creó en Creación de un rastreador de eventos de interacción de elementos. Los parámetros userId, itemId y sentAt se asignan a los campos USER_ID, ITEM_ID y TIMESTAMP de un conjunto de datos Interactions histórico correspondiente. Para obtener más información, consulte Schemas.

Columnas del conjunto de datos correspondientes

Dataset columns: USER_ID, ITEM_ID, TIMESTAMP, EVENT_TYPE
Example data: user123, item-xyz, 1543631760, click

Ejemplo de código

SDK for Python (Boto3)

import boto3

personalize_events = boto3.client(service_name='personalize-events')

personalize_events.put_events(
    trackingId = 'tracking_id',
    userId= 'USER_ID',
    sessionId = 'session_id',
    eventList = [{
        'sentAt': 1719511760,
        'eventType': 'click',
        'itemId': 'ITEM_ID'
        }]
)

SDK for JavaScript v3

// Get service clients module and commands using ES6 syntax.
import { PutEventsCommand } from "@aws-sdk/client-personalize-events";
import { personalizeEventsClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeEventsClient = new PersonalizeEventsClient({ region: "REGION"});

// Convert your UNIX timestamp to a Date.
const sentAtDate = new Date(1613443801 * 1000); // 1613443801 is a testing value. Replace it with your sentAt timestamp in UNIX format.

// Set put events parameters.
var putEventsParam = {
  eventList: [
    /* required */
    {
      eventType: "EVENT_TYPE" /* required */,
      sentAt: sentAtDate /* required, must be a Date with js */,
      eventId: "EVENT_ID" /* optional */,
      itemId: "ITEM_ID" /* optional */,
    },
  ],
  sessionId: "SESSION_ID" /* required */,
  trackingId: "TRACKING_ID" /* required */,
  userId: "USER_ID" /* required */,
};
export const run = async () => {
  try {
    const response = await personalizeEventsClient.send(
      new PutEventsCommand(putEventsParam),
    );
    console.log("Success!", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();

AWS CLI

aws personalize-events put-events \
    --tracking-id tracking_id \
    --user-id USER_ID \
    --session-id session_id \
    --event-list '[{
        "sentAt": 1719511760,
        "eventType": "click",
        "itemId": "ITEM_ID"
      }]'

SDK for Java 2.x

public static void putEvents(PersonalizeEventsClient personalizeEventsClient, 
                            String trackingId, 
                            String sessionId, 
                            String userId, 
                            String itemId,
                            String eventType) {
    
    try { 
        Event event = Event.builder()
            .sentAt(Instant.ofEpochMilli(System.currentTimeMillis() + 10 * 60 * 1000))
            .itemId(itemId)
            .eventType(eventType)
            .build();

        PutEventsRequest putEventsRequest = PutEventsRequest.builder()
            .trackingId(trackingId)
            .userId(userId)
            .sessionId(sessionId)
            .eventList(event)
            .build();

        int responseCode = personalizeEventsClient.putEvents(putEventsRequest)
            .sdkHttpResponse()
            .statusCode();
        System.out.println("Response code: " + responseCode);

        } catch (PersonalizeEventsException e) {
            System.out.println(e.awsErrorDetails().errorMessage());
        }
}

Registro de varios eventos de interacción de elementos con datos de valores de eventos

En el ejemplo siguiente se muestra cómo registrar varios eventos de interacción de elementos con diferentes tipos y valores de eventos.

Al configurar una solución, si su conjunto de datos de interacciones de elementos incluye los campos EVENT_TYPE y EVENT_VALUE, puede establecer un valor específico como umbral para excluir registros del entrenamiento. Para obtener más información, consulte Elección de los datos de interacciones de elementos utilizados para el entrenamiento.

El ejemplo también muestra la grabación de una propiedad adicional, numRatings, que utilizan como metadatos determinadas recetas.

Dataset columns: USER_ID, ITEM_ID, TIMESTAMP, EVENT_TYPE, EVENT_VALUE, NUM_RATINGS
Item interactions dataset: user123, movie_xyz, 1543531139, rating, 5, 12
                      user321, choc-ghana, 1543531760, like, 4
                      user111, choc-fake, 1543557118, like, 3

Python

import boto3
import json

personalize_events = boto3.client(service_name='personalize-events')

personalize_events.put_events(
    trackingId = 'tracking_id',
    userId= 'user555',
    sessionId = 'session1',
    eventList = [{
        'eventId': 'event1',
        'sentAt': 1553631760,
        'eventType': 'like',
        'properties': json.dumps({
            'itemId': 'choc-panama',
            'eventValue': 4,
            'numRatings': 0    
            })
        }, {
        'eventId': 'event2',
        'sentAt': 1553631782,
        'eventType': 'rating',
        'properties': json.dumps({
            'itemId': 'movie_ten',
            'eventValue': 3,
            'numRatings': 13
            })
        }]
)

AWS CLI

aws personalize-events put-events \
    --tracking-id tracking_id \
    --user-id user555 \
    --session-id session1 \
    --event-list '[{
        "eventId": "event1",
        "sentAt": 1553631760,
        "eventType": "like",
        "properties": "{\"itemId\": \"choc-panama\", \"eventValue\": \"true\"}"
      }, {
        "eventId": "event2",
        "sentAt": 1553631782,
        "eventType": "rating",
        "properties": "{\"itemId\": \"movie_ten\", \"eventValue\": \"4\", \"numRatings\": \"13\"}"
      }]'

SDK for Java 2.x

public static void putMultipleEvents(PersonalizeEventsClient personalizeEventsClient, 
                            String trackingId, 
                            String sessionId, 
                            String userId, 
                            String event1Type, 
                            Float event1Value, 
                            String event1ItemId,
                            int event1NumRatings,
                            String event2Type, 
                            Float event2Value, 
                            String event2ItemId,
                            int event2NumRatings) {  
                                                    
    ArrayList<Event> eventList = new ArrayList<Event>();
                        
    try {
        Event event1 = Event.builder()
            .eventType(event1Type)
            .sentAt(Instant.ofEpochMilli(System.currentTimeMillis() + 10 * 60 * 1000))
            .itemId(event1ItemId)
            .eventValue(event1Value)
            .properties("{\"numRatings\": "+ event1NumRatings +"}")
            .build(); 

        eventList.add(event1); 

        Event event2 = Event.builder()
            .eventType(event2Type)
            .sentAt(Instant.ofEpochMilli(System.currentTimeMillis() + 10 * 60 * 1000))
            .itemId(event2ItemId)
            .eventValue(event2Value)
            .properties("{\"numRatings\": "+ event2NumRatings +"}")
            .build();

        eventList.add(event2);

        PutEventsRequest putEventsRequest = PutEventsRequest.builder()
            .trackingId(trackingId)
            .userId(userId)
            .sessionId(sessionId)
            .eventList(eventList)
            .build();

        int responseCode = personalizeEventsClient.putEvents(putEventsRequest)
            .sdkHttpResponse()
            .statusCode();
            
        System.out.println("Response code: " + responseCode);

    } catch (PersonalizeEventsException e) {
        System.out.println(e.awsErrorDetails().errorMessage());
    }
}

nota

Las claves de propiedades utilizan nombres con la inicial en minúsculas que coinciden con los campos del esquema Interactions. Por ejemplo, si el campo “NUM_RATINGS” está definido en el esquema de interacciones, la clave de la propiedad debería ser numRatings.

Registro de datos de impresiones

Si usa la User-Personalization receta o agrega el campo IMPRESSIONS a su esquema para un conjunto de datos de un grupo de conjuntos de datos de dominio, puede registrar los datos de impresiones en su PutEvents operación. Las impresiones son listas de elementos que estaban visibles para un usuario cuando interactuaba con un elemento concreto (por ejemplo, al hacer clic o verlo). Amazon Personalize utiliza los datos de impresiones para guiar la exploración, donde las recomendaciones incluyen elementos con menos interacciones, datos o relevancia. Para obtener información sobre las impresiones implícitas y explícitas que Amazon Personalize puede modelar, consulte Datos de impresiones.

importante

Si proporciona datos de impresiones implícitas y explícitas contradictorios en sus solicitudes de PutEvents. Amazon Personalize utiliza las impresiones explícitas de forma predeterminada.

Para registrar las recomendaciones de Amazon Personalize que muestra a sus usuarios como datos de impresiones, incluya recommendationId en su solicitud PutEvents y Amazon Personalize obtiene las impresiones implícitas en función de los datos de sus recomendaciones.

Para registrar manualmente los datos de impresiones de un evento, enumere las impresiones en el parámetro de entrada impression del comando PutEvents. En el siguiente ejemplo de código se muestra cómo incluir un recommendationId y un impression en una PutEvents operación con el SDK para Python (Boto3) o el SDK para Java 2.x. Si incluyes ambos, Amazon Personalize utiliza las impresiones explícitas de forma predeterminada.

SDK for Python (Boto3)

import boto3

personalize_events = boto3.client(service_name='personalize-events')

personalize_events.put_events(
    trackingId = 'tracking_id',
    userId= 'userId',
    sessionId = 'sessionId',
    eventList = [{
        'eventId': 'event1',
        'eventType': 'rating',
        'sentAt': 1553631760,
        'itemId': 'item id',
        'recommendationId': 'recommendation id',
        'impression': ['itemId1', 'itemId2', 'itemId3']
        }]
)

SDK for Java 2.x

Utilice el siguiente método putEvents para registrar un evento con datos de impresiones y un recommendationId. Para el parámetro de impresiones, pasa la lista de ItemIDs como. ArrayList

public static void putEvents(PersonalizeEventsClient personalizeEventsClient, 
                                String trackingId, 
                                String sessionId, 
                                String userId, 
                                String eventType, 
                                Float eventValue, 
                                String itemId,
                                ArrayList<String> impressions,
                                String recommendationId) {

    try { 
        Event event = Event.builder()
            .eventType(eventType)
            .sentAt(Instant.ofEpochMilli(System.currentTimeMillis() + 10 * 60 * 1000))
            .itemId(itemId)
            .eventValue(eventValue)
            .impression(impressions)
            .recommendationId(recommendationId)
            .build();

        PutEventsRequest putEventsRequest = PutEventsRequest.builder()
            .trackingId(trackingId)
            .userId(userId)
            .sessionId(sessionId)
            .eventList(event)
            .build();

        int responseCode = personalizeEventsClient.putEvents(putEventsRequest)
            .sdkHttpResponse()
            .statusCode();
        System.out.println("Response code: " + responseCode);

    } catch (PersonalizeEventsException e) {
        System.out.println(e.awsErrorDetails().errorMessage());
    }
}