Importe eventos de utilizadores históricos

Esta página descreve como importar dados de eventos de utilizadores de eventos anteriores em massa.

Para os tipos de eventos de utilizador que pode importar, consulte o campo eventType do objeto userEvents. Ao importar eventos de utilizadores, pode melhorar a qualidade dos seus resultados. Por exemplo, os eventos do utilizador afetam a classificação dos resultados da pesquisa. Os resultados com taxas de cliques mais elevadas são promovidos, enquanto os resultados com taxas de cliques mais baixas são ocultados. Importe apenas eventos de utilizadores para documentos que já tenha importado para o seu repositório de dados.

Se um evento tiver documentos listados em userEvents.Documents, o Gemini Enterprise junta-se automaticamente aos eventos com esse documento. A associação permite ao Gemini Enterprise atribuir eventos, como cliques e visualizações, ao documento correto num resultado da pesquisa ou numa recomendação. Para apps de pesquisa e recomendações personalizadas, a associação ocorre de forma assíncrona, ou seja, os eventos do utilizador são associados a documentos após a conclusão da importação em lote (geralmente, isto acontece em poucos minutos).

Se estiver a usar uma app de pesquisa com várias lojas de dados anexadas, importe eventos do utilizador ao nível da localização em vez de ao nível da loja de dados. Isto permite que um evento de utilizador específico seja enviado para o armazenamento de dados ao qual está associado. Para importar eventos de utilizadores com documentos de diferentes dataStores ao nível da localização em vez do nível do repositório de dados, consulte userEvents.import.

Para importar eventos do utilizador em tempo real, consulte o artigo Registe eventos do utilizador em tempo real.

Pode importar eventos históricos das seguintes formas:

Para a representação JSON dos eventos do utilizador, consulte userEvents na referência da API.

Antes de começar

Antes de importar eventos do utilizador:

Importe eventos de utilizadores históricos do Cloud Storage

REST

Para importar eventos de utilizador históricos em massa a partir do Cloud Storage, siga estes passos:

  1. Crie um ou mais ficheiros de dados para os parâmetros de entrada da importação. Use o objeto gcsSource para apontar para o seu contentor do Cloud Storage.

    {
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}

    Substitua o seguinte:

    • INPUT_FILE: um ficheiro no Cloud Storage que contém os dados de eventos do utilizador. Certifique-se de que cada evento do utilizador está na sua própria linha única, sem quebras de linha. Para a representação JSON de eventos do utilizador, consulte userEvents na referência da API. Os campos do ficheiro de entrada têm de 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. A Google recomenda deixar este campo vazio para permitir que o Gemini Enterprise crie automaticamente um diretório temporário.

  2. Importe os seus eventos fazendo um pedido POST ao método userEvents.import, indicando o nome do ficheiro 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/dataStores/DATA_STORE_ID/userEvents:import"

    Se estiver a importar eventos de utilizador ao nível da localização, use o ponto final https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.

Importe eventos de utilizadores do histórico do BigQuery

Quando criar tabelas para eventos do utilizador no BigQuery, use os esquemas documentados no artigo Acerca dos eventos do utilizador.

Configure o acesso ao BigQuery

Se o seu conjunto de dados do BigQuery estiver num projeto diferente do seu repositório de dados, siga estes passos para configurar o acesso ao BigQuery.

  1. Abra a página IAM e administrador na Google Cloud consola.
  2. Selecione o projeto que contém o repositório de dados para o qual quer importar eventos do utilizador.
  3. Selecione a caixa de verificação Incluir concessões de funções fornecidas pela Google.
  4. Encontre a conta de serviço com o nome Discovery Engine Service Account.
  5. Se não tiver iniciado anteriormente uma operação de importação com o Discovery Engine, esta conta de serviço pode não estar listada. Se não vir esta conta de serviço, regresse à tarefa de importação e inicie a importação. Quando falhar devido a erros de autorização, regresse aqui e conclua esta tarefa. A conta de serviço do Discovery Engine é apresentada.
  6. Copie o identificador da conta de serviço, que se assemelha a um endereço de email, por exemplo, service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com.
  7. Mude para o seu projeto do BigQuery (na mesma página de IAM e administração) e clique em Conceder acesso.
  8. Para Novos responsáveis, introduza o identificador da conta de serviço e selecione a função BigQuery > Visitante de dados do BigQuery.
  9. Clique em Guardar.

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

Importe eventos do BigQuery

REST

Para importar eventos de utilizador históricos em massa a partir do Cloud Storage, siga estes passos:

  1. Importe os seus eventos de utilizador fazendo um pedido POST ao método userEvents.import, indicando o nome do projeto do BigQuery, o ID do conjunto de dados e o ID da tabela.

    Quando importar os seus 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/dataStores/DATA_STORE_ID/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

    Se estiver a importar eventos de utilizador ao nível da localização, use o ponto final https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.

Importe eventos de utilizadores do histórico como dados JSON locais

Pode importar eventos do utilizador incluindo dados JSON locais para os eventos na sua chamada ao método userEvents.import.

Para colocar os dados de eventos do utilizador num ficheiro JSON e especificar o ficheiro num pedido de API, siga estas instruções:

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

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

  2. Importe os seus eventos fazendo um pedido POST ao método userEvents.import, indicando o nome do ficheiro 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/dataStores/DATA_STORE_ID/userEvents:import"

    Se estiver a importar eventos de utilizador ao nível da localização, use o ponto final https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.