Importe eventos de utilizadores históricos

Esta página descreve como importar dados de eventos de utilizadores de eventos anteriores em massa. Os eventos do utilizador são necessários para apps de multimédia. Se não usar apps de multimédia, não é necessário importar eventos do utilizador. No entanto, é recomendável registar eventos de utilizador para apps de pesquisa e recomendações personalizadas.

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á foram importados para o seu repositório de dados.

Se um evento tiver documentos listados em userEvents.Documents, as aplicações de IA juntam-se automaticamente aos eventos com esse documento. A associação permite que as aplicações de IA atribuam 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 aos documentos após a conclusão da importação em lote (geralmente, isto acontece em poucos minutos). Para apps de multimédia, a associação ocorre de forma síncrona. As aplicações de IA começam a associar eventos do utilizador a documentos enquanto a importação em lote ainda está em curso. Para saber como ver métricas de eventos não associados na consola, consulte Ver informações agregadas de eventos de utilizadores.

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

Se tiver uma app de multimédia, pode importar eventos de utilizadores através da Google Cloud consola ou da API. Para outros tipos de apps, só pode importar através da API.

Consola

Para importar eventos de utilizadores para apps de multimédia através da consola, siga estes passos:

  1. Na Google Cloud consola, aceda à página Aplicações de IA.

    Aplicações de IA

  2. Na página Apps, clique na sua app de multimédia.

  3. Aceda à página Dados.

    Para apps de recomendações de conteúdo multimédia, o separador Requisitos apresenta os documentos de conteúdo multimédia e os eventos do utilizador que tem de importar.

  4. Clique no separador Eventos. Se já tiver importado eventos, as informações sobre estes são apresentadas neste separador.

  5. Clique em Importar eventos.

  6. Selecione Cloud Storage como origem de dados.

  7. Introduza ou selecione a localização do Cloud Storage dos seus eventos do utilizador.

  8. Clique em Importar.

  9. O separador Atividade apresenta o estado da sua importação.

  10. Se ocorrerem erros de importação, no separador Atividade:

    1. Expanda o erro na coluna Detalhes e clique em Ver detalhes para ver mais informações no painel Detalhes do registo de atividade.

    2. No painel Detalhes do registo de atividade, clique em Ver registos de erros completos para ver o erro no Explorador de registos.

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 as aplicações de IA criem 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 arquivo 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

Se tiver uma app de multimédia, pode importar eventos do utilizador através da Google Cloud consola ou da API. Para outros tipos de apps, só pode importar através da API.

Consola

Para importar eventos de utilizadores para apps de multimédia através da consola, siga estes passos:

  1. Na Google Cloud consola, aceda à página Aplicações de IA.

    Aplicações de IA

  2. Na página Apps, clique na sua app de multimédia.

  3. Aceda à página Dados.

    Para apps de recomendações de conteúdo multimédia, o separador Requisitos apresenta os documentos de conteúdo multimédia e os eventos do utilizador que tem de importar.

  4. Clique no separador Eventos. Se já tiver importado eventos, as informações sobre estes são apresentadas neste separador.

  5. Clique em Importar eventos.

  6. Selecione BigQuery como origem de dados.

  7. Introduza ou selecione o caminho do BigQuery para os seus eventos de utilizador.

  8. Clique em Importar.

  9. O separador Atividade apresenta o estado da sua importação.

  10. Se ocorrerem erros de importação, no separador Atividade:

    1. Expanda o erro na coluna Detalhes e clique em Ver detalhes para ver mais informações no painel Detalhes do registo de atividade.

    2. No painel Detalhes do registo de atividade, clique em Ver registos de erros completos para ver o erro no Explorador de registos.

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 do 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.