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.

Para os tipos de eventos de usuário que podem ser importados, consulte o campo eventType do objeto userEvents. Ao importar eventos do usuário, você pode melhorar a qualidade dos resultados. Por exemplo, os eventos do usuário afetam a classificação dos resultados da pesquisa. Os resultados com taxas de cliques mais altas são impulsionados, enquanto os resultados com taxas de cliques mais baixas são ocultados. Importe apenas eventos de usuário para documentos que já foram importados para seu repositório de dados.

Se um evento tiver documentos listados em userEvents.Documents, o Gemini Enterprise vai associar automaticamente os eventos a esse documento. A mesclagem permite que o Gemini Enterprise atribua eventos, como cliques e visualizações, ao documento correto em um resultado da pesquisa ou recomendação. Para apps de pesquisa e recomendações personalizados, a mesclagem ocorre de forma assíncrona, ou seja, os eventos do usuário são mesclados aos documentos após a conclusão da importação em lote (geralmente em minutos).

Se você estiver usando um app de pesquisa com vários repositórios de dados anexados, importe eventos de usuário no nível do local, em vez do nível do repositório de dados. Isso permite que um determinado evento de usuário seja enviado ao repositório de dados associado a ele. Ao importar eventos de usuário em um nível de local, inclua o campo engine no evento de usuário para associar o evento ao app correto. Para exemplos de eventos de usuário que incluem o campo engine, consulte o seguinte:

Para mais informações sobre o método de importação, consulte userEvents.import.

Para importar eventos de usuários em tempo real, consulte Registrar eventos de usuários em tempo real.

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

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

Antes de começar

Antes de importar eventos de usuário:

  • Criar um repositório de dados e um app.
  • Consulte Sobre eventos de usuário para ver os requisitos para eventos de usuário.

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

REST

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

  1. 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"
  }
}

    Substitua:

    • INPUT_FILE: um arquivo no Cloud Storage que contém os dados de eventos do usuário. Verifique se cada evento de usuário está em uma única linha, sem quebras de linha. Para ver a representação JSON de eventos de 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 vazio para que o Gemini Enterprise crie automaticamente um diretório temporário.

  2. Importe seus eventos fazendo uma solicitação POST para o método userEvents.import, fornecendo o nome do arquivo de dados.

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

Importar eventos históricos de usuário do BigQuery

Ao criar tabelas para eventos de usuário no BigQuery, use os esquemas documentados em Sobre eventos de usuário para apps personalizados. Cada evento de usuário search precisa incluir um campo engine para associar o evento a um app. Para mais informações, consulte engine.

Configurar o acesso ao BigQuery

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

  1. Abra a página IAM e administrador no console do Google Cloud .
  2. Selecione o projeto que contém o repositório de dados em que você quer importar eventos de usuário.
  3. Marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google.
  4. Encontre a conta de serviço com o nome Conta de serviço do Discovery Engine.
  5. Se você não tiver iniciado uma operação de importação com o Discovery Engine, essa conta de serviço pode não estar listada. Se você não encontrar essa conta de serviço, volte para a 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 será listada.
  6. 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.
  7. Mude para o projeto do BigQuery (na mesma página IAM e administrador) e clique em Conceder acesso.
  8. Em Novos principais, insira o identificador da conta de serviço e selecione o papel BigQuery > Visualizador de dados do BigQuery.
  9. 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

REST

Para importar eventos históricos de usuários em massa do BigQuery, siga estas etapas:

  1. Importe seus eventos de usuário fazendo uma solicitação POST para o método userEvents.import, fornecendo o nome do projeto do BigQuery, o ID do conjunto de dados e o ID da tabela.

    Ao importar eventos, use o valor user_event para dataSchema.

    curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1/projects/[PROJECT_NUMBER]/locations/global/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 de usuário incluindo dados JSON locais para os eventos na chamada para o método userEvents.import.

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

  1. Crie um arquivo JSON com os dados de eventos do usuário. Para ver a representação JSON de eventos de usuário, consulte userEvents na documentação de referência da API.

    {
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}

  2. Importe seus eventos fazendo 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/v1/projects/PROJECT_NUMBER/locations/global/userEvents:import"