Esta página foi traduzida pela API Cloud Translation.

Importe eventos históricos do usuário

Nesta página, descrevemos como importar em massa os dados de eventos do usuário de eventos anteriores. Os eventos do usuário são necessários para recomendações de mídia. Se você não usa recomendações de mídia, não é necessário importar eventos do usuário. No entanto, ela é recomendada para apps de pesquisa de mídia.

Para saber quais tipos de evento do usuário podem ser importados, consulte o campo eventType do objeto userEvents. Ao importar eventos de usuário, você pode melhorar a qualidade das suas recomendações e a classificação dos resultados da pesquisa. Os resultados da pesquisa com taxas de cliques mais altas são impulsionados, enquanto os resultados com taxas de cliques mais baixas são ocultados. Não importe eventos de usuário de documentos que você ainda não importou.

Se um evento tiver documentos listados em userEvents.Documents, a Vertex AI para Pesquisa vai unir automaticamente os eventos a esse documento. A mesclagem permite que a Vertex AI para Pesquisa atribua eventos, como cliques e visualizações, ao documento correto em um resultado de pesquisa ou recomendação. Para apps de caso de uso genérico, a mesclagem ocorre de forma assíncrona, ou seja, os eventos do usuário são mesclados aos documentos depois que a importação em lote é concluída (geralmente em minutos). Para apps de mídia, a mesclagem ocorre simultaneamente. A Vertex AI para Pesquisa começa a mesclar eventos do usuário a documentos enquanto a importação em lote ainda está em andamento. Para saber como visualizar as métricas de eventos desconectados no console, consulte Conferir informações de eventos do usuário agregados.

Para importar eventos do usuário em tempo real, consulte Gravar eventos do usuário em tempo real.

É possível importar eventos históricos das seguintes maneiras:

Do Cloud Storage
No BigQuery
Como dados JSON locais

Para a representação JSON de eventos do usuário, consulte userEvents na referência da API.

Antes de começar

Antes de importar eventos do usuário:

Crie um repositório de dados e um app.
Consulte Sobre os eventos do usuário para conferir os requisitos.

Importar eventos históricos do usuário do Cloud Storage

Se você tiver um app de mídia, poderá importar eventos de usuário usando o console do Google Cloud ou a API. Para outros tipos de apps, só é possível importar usando a API.

Console

Para importar eventos de usuário de apps de mídia usando o console, siga estas etapas:

No Console do Google Cloud, acesse a página Criador de agentes.

Agent Builder.
Na página Apps, clique no app de mídia.
Acesse a página Dados.

Para apps de recomendações de mídia, a guia Requirements mostra os documentos de mídia e os eventos do usuário que você precisa importar.
Clique na guia Eventos. Se você já importou eventos, as informações deles vão aparecer nesta guia.
Clique em Importar eventos.
Selecione o Cloud Storage como a origem de dados.
Insira ou selecione o local do Cloud Storage dos seus eventos de usuário.
Clique em Importar.
A guia Atividade mostra o status da importação.
Se ocorrerem erros de importação, na guia Atividade:
1. Abra o erro na coluna Detalhes e clique em Ver detalhes para acessar mais informações no painel Detalhes do registro de atividades.
2. No painel Detalhes do registro de atividades, clique em Ver registros de erros completos para ver o erro no Explorador de registros.

REST

Para importar eventos históricos de usuário em massa do Cloud Storage, siga estas etapas:

Crie um ou mais arquivos de dados para os parâmetros de entrada da importação. Use o objeto gcsSource para apontar para o bucket do Cloud Storage.
```
{
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}
```
- INPUT_FILE: um arquivo no Cloud Storage que contém os dados de evento do usuário. Verifique se cada evento do usuário está em uma linha única, sem quebras de linha. Para a representação JSON de eventos do usuário, consulte userEvents na referência da API. Os campos do arquivo de entrada precisam estar neste formato: gs://<bucket>/<path-to-file>/.
- ERROR_DIRECTORY: opcional. Um diretório do Cloud Storage para informações de erro sobre a importação, por exemplo, gs://<your-gcs-bucket>/directory/import_errors. O Google recomenda deixar esse campo em branco para permitir que o Vertex AI Agent Builder crie automaticamente um diretório temporário.

Para importar seus eventos, faça uma solicitação POST para o método userEvents:import, fornecendo o nome do arquivo de dados.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

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/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

Importar eventos históricos do usuário do BigQuery

Ao criar tabelas para eventos de usuário no BigQuery, use os esquemas documentados em Sobre eventos de usuário.

Configurar o acesso ao BigQuery

Se o conjunto de dados do BigQuery estiver em um projeto diferente do seu repositório de dados, siga estas etapas para configurar o acesso ao BigQuery.

Abra a página IAM e administrador no console do Google Cloud.
Selecione o projeto que contém o repositório de dados para importar eventos de usuário.
Marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google.
Encontre a conta de serviço com o nome Conta de serviço do Discovery Engine.
Se você ainda não iniciou uma operação de importação com o Discovery Engine, essa conta de serviço pode não estar listada. Se essa conta de serviço não for exibida, retorne à tarefa de importação e inicie a importação. Quando ela falhar devido a erros de permissão, volte aqui e conclua esta tarefa. A conta de serviço do Discovery Engine vai ser listada.
Copie o identificador da conta de serviço, que se parece com um endereço de e-mail (por exemplo, service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com).
Alterne para seu projeto do BigQuery (na mesma página IAM e administrador) e clique em Conceder acesso.
Em Novos administradores, insira o identificador da conta de serviço e selecione o papel BigQuery > Visualizador de dados do BigQuery.
Clique em Salvar.

Para mais informações sobre o acesso ao BigQuery, consulte Como controlar o acesso a conjuntos de dados na documentação do BigQuery.

Importar eventos do BigQuery

Se você tiver um app de mídia, poderá importar eventos de usuário usando o console do Google Cloud ou a API. Para outros tipos de apps, só é possível importar usando a API.

Console

Para importar eventos de usuário de apps de mídia usando o console, siga estas etapas:

No Console do Google Cloud, acesse a página Criador de agentes.

Agent Builder.
Na página Apps, clique no app de mídia.
Acesse a página Dados.

Para apps de recomendações de mídia, a guia Requirements mostra os documentos de mídia e os eventos do usuário que você precisa importar.
Clique na guia Eventos. Se você já importou eventos, as informações deles vão aparecer nesta guia.
Clique em Importar eventos.
Selecione BigQuery como a fonte de dados.
Insira ou selecione o caminho do BigQuery para seus eventos do usuário.
Clique em Importar.
A guia Atividade mostra o status da importação.
Se ocorrerem erros de importação, na guia Atividade:
1. Abra o erro na coluna Detalhes e clique em Ver detalhes para acessar mais informações no painel Detalhes do registro de atividades.
2. No painel Detalhes do registro de atividades, clique em Ver registros de erros completos para ver o erro no Explorador de registros.

REST

Para importar eventos históricos de usuário em massa do Cloud Storage, siga estas etapas:

Para importar os eventos do usuário, faça uma solicitação POST para o método userEvents:import, informando o nome do projeto, o ID do conjunto de dados e o ID da tabela do BigQuery.

Ao importar eventos, use o valor user_event para dataSchema.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1beta/projects/[PROJECT_NUMBER]/locations/global/dataStores/DATA_STORE_ID/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

Importar eventos históricos do usuário como dados JSON locais

É possível importar eventos do usuário incluindo dados JSON locais para os eventos na chamada para o método userEvents:import.

Para colocar dados de eventos do usuário em um arquivo JSON e especificar o arquivo em uma solicitação de API, siga estas instruções:

Crie um arquivo JSON com os dados dos eventos do usuário. Para a representação JSON de eventos do usuário, consulte userEvents na documentação de referência da API.
```
{
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}
```

Para importar seus eventos, faça uma solicitação POST para o método userEvents:import, fornecendo o nome do arquivo de dados.

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/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"