As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Registrar eventos de interação com ações em tempo real
*Evento de interação com item* é uma interação entre um usuário e um item do catálogo. Por exemplo, um usuário comprando sapatos ou assistindo a um filme.
Registre eventos de interação com itens em tempo real ao mostrar recomendações de itens ao cliente. Isso cria dados de interações e os mantém atualizados. Também informa o Amazon Personalize sobre os interesses atuais do usuário, o que pode melhorar a relevância das recomendações.
Você deve registrar eventos de interação com itens com a operação de API [PutEvents](API_UBS_PutEvents.md). O Amazon Personalize anexa os dados do evento ao *conjunto de dados de interações com itens* no grupo de conjuntos de dados. Se você gravar dois eventos com exatamente as mesmas informações de data e hora e propriedades idênticas, o Amazon Personalize manterá somente um dos eventos. Você pode gravar eventos de interação do item usando o AWS SDKs, AWS Amplify ou AWS Command Line Interface ()AWS CLI.
Se você usa o Apache Kafka, utilize o *conector do Kafka para o Amazon Personalize* para transmitir interações com itens em tempo real para o Amazon Personalize. Para obter informações, consulte [Conector Kafka para Amazon](https://github.com/aws/personalize-kafka-connector/blob/main/README.md) Personalize no *personalize-kafka-connector*repositório Github.
AWS O Amplify inclui uma JavaScript biblioteca para registrar eventos de interação de itens de aplicativos cliente web e uma biblioteca para gravar eventos no código do servidor. Para obter mais informações, consulte a [documentação do Amplify](https://docs.amplify.aws/).
**Topics**
+ [Requisitos para registrar eventos de interação com itens e treinar um modelo](#recording-events-requirements)
+ [Criar um rastreador de eventos de interação com itens](event-get-tracker.md)
+ [Registrar um único evento de interação com itens](putevents-example.md)
+ [Registrar vários eventos de interação com itens com dados de valor dos eventos](recording-events-example-event-value.md)
+ [Registrar eventos de interação com itens usando os dados de impressões](putevents-including-impressions-data.md)
+ [Métricas de eventos e relatórios de atribuição](event-metrics.md)
## Requisitos para registrar eventos de interação com itens e treinar um modelo
Para registrar eventos de interação com itens, é necessário o seguinte:
+ Um grupo de conjuntos de dados que inclui um conjunto de dados `Item interactions`, que pode estar vazio. Se você consultou o guia [Tutoriais de conceitos básicos](getting-started.md), pode usar o mesmo conjunto de dados e o grupo de conjuntos de dados que criou. Para mais informações sobre como criar um grupo de conjuntos de dados e um conjunto de dados, consulte [Importar dados de treinamento para os conjuntos de dados do Amazon Personalize](import-data.md).
+ Um rastreador de eventos.
+ Uma chamada para a operação de API [PutEvents](API_UBS_PutEvents.md).
+ Se você usar uma AWS Lambda função para chamar a PutEvents operação, a função de execução da função deverá ter permissão para realizar a `personalize:PutEvents` ação com o caractere curinga `*` no `Resource` elemento.
É possível começar com um conjunto de dados de interações com itens vazio e, depois de registrar dados suficientes, treinar o modelo usando somente novos eventos registrados. Para todos os casos de uso (grupos de conjuntos de dados de Domínio) e fórmulas (grupos de conjuntos de dados personalizados), seus dados de interações precisam do seguinte antes do treinamento:
+ No mínimo, mil registros de interações com itens de usuários que interagem com itens do catálogo. Essas interações podem ser de importações em massa, eventos transmitidos ou ambas as coisas.
+ No mínimo 25 usuários únicos IDs com pelo menos duas interações de itens para cada um.
Para obter recomendações de qualidade, o ideal é que você tenha, no mínimo, cinquenta mil interações com itens de, pelo menos, mil usuários com duas ou mais interações com itens cada.
# Criar um rastreador de eventos de interação com itens
Antes de registrar eventos de interação com itens, é necessário criar um rastreador de eventos de interação com itens. Um *rastreador de eventos* direciona novos dados de eventos para o *conjunto de dados de interações com itens* no grupo de conjuntos de dados.
Você cria um rastreador de eventos com o console do Amazon Personalize ou a operação de API [CreateEventTracker](API_CreateEventTracker.md). Você deve transmitir como parâmetro o nome do recurso da Amazon (ARN) do grupo de conjuntos de dados que contém o conjunto de dados de interações com itens de destino. Para instruções sobre como criar um rastreador de eventos usando o console do Amazon Personalize, consulte [Como criar um rastreador de eventos (console)](importing-interactions.md#event-tracker-console).
Um rastreador de eventos inclui uma *ID de rastreamento*, que você passa como parâmetro ao usar a [PutEvents](https://docs.aws.amazon.com/personalize/latest/dg/API_UBS_PutEvents.html)operação. Depois, o Amazon Personalize anexará os dados do novo evento ao conjunto de dados de interações com itens do grupo do conjunto de dados que você especificar no rastreador de eventos.
**nota**
É possível criar apenas um rastreador de eventos de interação com itens para um grupo de conjuntos de dados.
------
#### [ Python ]
```
import boto3
personalize = boto3.client('personalize')
response = personalize.create_event_tracker(
name='MovieClickTracker',
datasetGroupArn='arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieClickGroup'
)
print(response['eventTrackerArn'])
print(response['trackingId'])
```
O ARN do rastreador de eventos e o ID de rastreamento mostram, por exemplo:
```
{
"eventTrackerArn": "arn:aws:personalize:us-west-2:acct-id:event-tracker/MovieClickTracker",
"trackingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
------
#### [ AWS CLI ]
```
aws personalize create-event-tracker \
--name MovieClickTracker \
--dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieClickGroup
```
O ARN do rastreador de eventos e o ID de rastreamento mostram, por exemplo:
```
{
"eventTrackerArn": "arn:aws:personalize:us-west-2:acct-id:event-tracker/MovieClickTracker",
"trackingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
------
#### [ SDK for JavaScript v3 ]
```
// Get service clients module and commands using ES6 syntax.
import { CreateEventTrackerCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});
// Set the event tracker's parameters.
export const createEventTrackerParam = {
datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
name: "NAME" /* required */,
};
export const run = async () => {
try {
const response = await personalizeClient.send(
new CreateEventTrackerCommand(createEventTrackerParam),
);
console.log("Success", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
------
#### [ SDK for Java 2.x ]
```
public static String createEventTracker(PersonalizeClient personalizeClient,
String eventTrackerName,
String datasetGroupArn) {
String eventTrackerId = null;
String eventTrackerArn = null;
long maxTime = 3 * 60 * 60;
long waitInMilliseconds = 30 * 1000;
String status;
try {
CreateEventTrackerRequest createEventTrackerRequest = CreateEventTrackerRequest.builder()
.name(eventTrackerName)
.datasetGroupArn(datasetGroupArn)
.build();
CreateEventTrackerResponse createEventTrackerResponse =
personalizeClient.createEventTracker(createEventTrackerRequest);
eventTrackerArn = createEventTrackerResponse.eventTrackerArn();
eventTrackerId = createEventTrackerResponse.trackingId();
System.out.println("Event tracker ARN: " + eventTrackerArn);
System.out.println("Event tracker ID: " + eventTrackerId);
maxTime = Instant.now().getEpochSecond() + maxTime;
DescribeEventTrackerRequest describeRequest = DescribeEventTrackerRequest.builder()
.eventTrackerArn(eventTrackerArn)
.build();
while (Instant.now().getEpochSecond() < maxTime) {
status = personalizeClient.describeEventTracker(describeRequest).eventTracker().status();
System.out.println("EventTracker status: " + status);
if (status.equals("ACTIVE") || status.equals("CREATE FAILED")) {
break;
}
try {
Thread.sleep(waitInMilliseconds);
} catch (InterruptedException e) {
System.out.println(e.getMessage());
}
}
return eventTrackerId;
}
catch (PersonalizeException e){
System.out.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
return eventTrackerId;
}
```
------
# Registrar um único evento de interação com itens
Depois de criar um *conjunto de dados de interações com itens* e um [rastreador de eventos](event-get-tracker.md) para o grupo de conjuntos de dados, você já pode registrar eventos de interação. O exemplo a seguir mostra uma operação `PutEvents` que transmite um evento de interação com itens. O esquema correspondente é mostrado com uma linha de exemplo do conjunto de dados de interações com itens.
Seu aplicativo gera um `sessionId` exclusivo quando alguém visita seu site ou usa seu aplicativo pela primeira vez. Você deve usar o mesmo `sessionId` em todos os eventos durante a sessão. O Amazon Personalize usa o `sessionId` para associar eventos ao usuário antes que ele faça login (com anonimato). Para obter mais informações, consulte [Como registrar eventos de usuários anônimos](recording-events.md#recording-anonymous-user-events).
A lista de eventos é uma matriz de objetos [Event](API_UBS_Event.md). É necessário ter um `eventType` para cada evento. Se você não tiver dados de tipos de evento, você pode fornecer um valor de espaço reservado para atender ao requisito.
O `trackingId` vem do rastreador de eventos que você criou em [Criar um rastreador de eventos de interação com itens](event-get-tracker.md). Os parâmetros `userId`, `itemId` e `sentAt` são mapeados para os campos USER\$1ID, ITEM\$1ID e TIMESTAMP de um conjunto de dados `Interactions` históricos correspondente. Para obter mais informações, consulte [Criar arquivos JSON de esquema para esquemas do Amazon Personalize](how-it-works-dataset-schema.md).
**Colunas correspondentes do conjunto de dados**
```
Dataset columns: USER_ID, ITEM_ID, TIMESTAMP, EVENT_TYPE
Example data: user123, item-xyz, 1543631760, click
```
**Exemplo 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.
const 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());
}
}
```
------
# Registrar vários eventos de interação com itens com dados de valor dos eventos
Depois de criar um *conjunto de dados de interações com itens* e um [rastreador de eventos](event-get-tracker.md) para o grupo de conjuntos de dados, você já pode registrar eventos de interação. O exemplo abaixo mostra como registrar vários eventos de interação com itens com diferentes tipos e valores dos eventos.
Na hora de configurar uma solução, se o *conjunto de dados de interações com itens* incluir os campos EVENT\$1TYPE e EVENT\$1VALUE, será possível definir um valor específico como limite para excluir registros do treinamento. Para obter mais informações, consulte [Selecionar os dados de interações com itens utilizados para treinamento](event-values-types.md).
------
#### [ 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
})
}, {
'eventId': 'event2',
'sentAt': 1553631782,
'eventType': 'rating',
'properties': json.dumps({
'itemId': 'movie_ten',
'eventValue': 3
})
}]
)
```
------
#### [ 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 eventList = new ArrayList();
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**
As chaves de propriedades usam nomes concatenados correspondentes aos campos no esquema de interações. Por exemplo, se o campo 'NUM\$1RATINGS' estiver definido no esquema de interações, a chave da propriedade deverá ser `numRatings`.
# Registrar eventos de interação com itens usando os dados de impressões
Se você usar a [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md) receita ou adicionar o campo IMPRESSÕES ao seu esquema para um conjunto de dados em um grupo de conjuntos de dados do Domínio, poderá registrar dados de impressões em sua operação. PutEvents Impressões são listas de itens que estavam visíveis para um usuário durante a interação (por exemplo, clicar ou assistir) com determinado item. O Amazon Personalize usa dados de impressões para orientar a exploração, considerando que as recomendações incluem itens com menos dados de interações ou relevância. Para mais informações sobre as impressões *implícitas* e *explícitas* que o Amazon Personalize pode modelar, consulte [Dados de impressões](interactions-datasets.md#interactions-impressions-data).
**Importante**
Se você fornecer dados de impressões implícitas e explícitas conflitantes nas solicitações de `PutEvents`, o Amazon Personalize usa as impressões explícitas por padrão.
Para registrar as recomendações do Amazon Personalize que você apresenta ao usuário como dados de impressões, inclua o `recommendationId` na sua solicitação de [PutEvents](API_UBS_PutEvents.md). O Amazon Personalize derivará as impressões implícitas com base nos dados de recomendações.
Para registrar manualmente os dados de impressões de um evento, liste as impressões no parâmetro de entrada de `impression` do comando [PutEvents](API_UBS_PutEvents.md). O exemplo de código a seguir mostra como incluir a `recommendationId` e an `impression` em uma PutEvents operação com o SDK para Python (Boto3) ou o SDK para Java 2.x. Se incluir os dois, o Amazon Personalize usará as impressões explícitas por padrão.
------
#### [ 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 ]
Use o método de `putEvents` a seguir para registrar um evento com dados de impressões e um recommendationId. Para o parâmetro impressions, passe a lista de itemIDs como um. ArrayList
```
public static void putEvents(PersonalizeEventsClient personalizeEventsClient,
String trackingId,
String sessionId,
String userId,
String eventType,
Float eventValue,
String itemId,
ArrayList 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());
}
}
```
------
# Métricas de eventos e relatórios de atribuição
Para monitorar o tipo e o número de eventos enviados para o Amazon Personalize, use as métricas da Amazon CloudWatch . Para obter mais informações, consulte [Monitorando o Amazon Personalize com a Amazon CloudWatch](personalize-monitoring.md).
Para gerar CloudWatch relatórios que mostrem o impacto das recomendações, crie uma atribuição métrica e registre as interações do usuário com recomendações em tempo real. Para informações sobre como criar uma atribuição de métrica, consulte [Avaliar o impacto das recomendações do Amazon Personalize](measuring-recommendation-impact.md).
Para cada evento, inclua o ID de recomendação das recomendações que você mostrou ao usuário. ou inclua a fonte do evento, como um terceiro. Importe esses dados para comparar campanhas, recomendadores e terceiros diferentes. Você pode importar no máximo 100 fontes de atribuição de eventos.
+ Se você fornecer um `recommendationId`, o Amazon Personalize determinará automaticamente a campanha ou o recomendador de origem e os identificará nos relatórios em uma coluna EVENT\$1ATTRIBUTION\$1SOURCE.
+ Se você fornecer os dois atributos, o Amazon Personalize usará somente o `eventAttributionSource`.
+ Se você não fornecer uma fonte, o Amazon Personalize rotula a fonte `SOURCE_NAME_UNDEFINED` nos relatórios.
O código a seguir mostra como fornecer um `eventAttributionSource` para um evento em uma PutEvents operação.
```
response = personalize_events.put_events(
trackingId = 'eventTrackerId',
userId= 'userId',
sessionId = 'sessionId123',
eventList = [{
'eventId': 'event1',
'eventType': 'watch',
'sentAt': '1667260945',
'itemId': '123',
'metricAttribution': {
'eventAttributionSource': 'thirdPartyServiceXYZ'
}
}]
)
statusCode = response['ResponseMetadata']['HTTPStatusCode']
print(statusCode)
```
O código a seguir mostra como fornecer um `recommendationId` para um evento em uma PutEvents operação.
```
response = personalize_events.put_events(
trackingId = 'eventTrackerId',
userId= 'userId',
sessionId = 'sessionId123',
eventList = [{
'eventId': 'event1',
'eventType': 'watch',
'sentAt': '1667260945',
'itemId': '123',
'recommendationId': 'RID-12345678-1234-1234-1234-abcdefghijkl'
}]
)
statusCode = response['ResponseMetadata']['HTTPStatusCode']
print(statusCode)
```