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. A Vertex AI para Pesquisa para modelos de varejo exige dados de eventos do usuário para treinamento.

Depois de configurar a gravação de eventos em tempo real, pode levar um tempo considerável para registrar dados de evento do usuário suficientes para treinar seus modelos. É possível acelerar o treinamento inicial de modelos importando dados de eventos do usuário de eventos anteriores em massa. Antes de fazer isso, consulte as práticas recomendadas para gravar eventos do usuário e a seção Antes de começar nesta página.

Os procedimentos de importação nesta página se aplicam às duas recomendações e pesquisar. Depois de importar os dados, os dois serviços podem usar esses eventos, então não é preciso importar os mesmos dados duas vezes se você usar os dois serviços.

Você pode:

• Importar eventos do Cloud Storage.
• Importar eventos do BigQuery.
• Importar eventos do Google Analytics 360 do BigQuery.
• Importar eventos do Google Analytics 4 do BigQuery
• importar eventos in-line com o método userEvents.import;

Tutorial de importação de eventos do Cloud Storage

Neste tutorial, mostramos como importar eventos de usuário do Cloud Storage.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Tutorial de importação de eventos do BigQuery

Neste tutorial, mostramos como importar eventos de usuário do BigQuery.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Tutorial de importação de eventos inline

Neste tutorial, mostramos como importar dados inline de eventos de usuários.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Antes de começar

Para evitar erros de importação e garantir que haja dados suficientes para gerar bons resultados, analise as seguintes informações antes de importar seus eventos do usuário.

• Revise as práticas recomendadas para registrar eventos do usuário.

• A formatação de eventos do usuário varia de acordo com o tipo de evento. Consulte Tipos de eventos de usuários e esquema de exemplos para saber o formato a ser especificado ao criar tabelas para cada tipo de evento.

• as recomendações e a pesquisa têm diferenças requisitos mínimos de dados. Verifique se os eventos do usuário atendem aos requisitos do serviço que você pretende usar:

  • Consulte os requisitos e práticas recomendadas para eventos do usuário para requisitos de pesquisa e recomendações.

  • Se você usar modelos de recomendação, consulte também Requisitos dos dados de eventos do usuário, que lista outros de acordo com o tipo de modelo de recomendação e a otimização que você planeja usar.

Considerações sobre importação de eventos

Esta seção descreve os métodos que podem ser usados para a importação em lote de históricos de eventos do usuário, quando é possível usar cada método e alguns dos limitações.

Importar eventos de usuário do Cloud Storage

Importar eventos de usuário do Cloud Storage usando o console do Google Cloud ou o método userEvents.import.

Importar eventos de usuário do BigQuery

Importar eventos de usuário do BigQuery usando o console do Google Cloud ou o método userEvents.import.

Configurar o acesso ao BigQuery

Siga as instruções em Como configurar o acesso ao conjunto de dados do BigQuery para fornecer à sua conta de serviço da Pesquisa da Vertex AI para varejo o papel de proprietário de dados do BigQuery no seu conjunto de dados do BigQuery.

Importar os eventos do usuário do BigQuery

É possível importar eventos do 360 usando o Pesquise o console do Retail ou o método userEvents.import.

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 application-default print-access-token)"" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \
--data '{
  "inputConfig": {
    "bigQuerySource": {
      "datasetId": "DATASET_ID",
      "tableId": "TABLE_ID",
      "dataSchema": "SCHEMA_TYPE"
  }
}
}'

Importar eventos de usuário do Google Analytics 360 com o BigQuery

Você poderá importar eventos do usuário do Google Analytics 360 se tiver integrou o Analytics 360 ao BigQuery e use o e-commerce avançado.

Os procedimentos a seguir pressupõem que você esteja familiarizado com o uso BigQuery e Analytics 360.

Antes de começar

Antes de iniciar as próximas etapas, verifique se:

• Você está usando o e-commerce avançado.
• Você tem o BigQuery vinculado ao Google Analytics 360.

Verificar a fonte de dados

1. Verifique se os dados de eventos do usuário que você vai importar estão formatados corretamente em uma tabela do BigQuery a que você tem acesso.

   Verifique se a tabela tem o nome project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

   Consulte a documentação do Google Analytics para saber mais sobre o formato e a nomenclatura da tabela.

2. Na Console do Google Cloud do BigQuery, selecione a tabela no painel Explorador para visualizá-la.

   Verifique se:

   1. A coluna clientId tem um valor válido, por exemplo, 123456789.123456789.

      Esse valor é diferente do valor completo do cookie "_ga" (que tem um formato como GA1.3.123456789.123456789).

   2. A coluna hits.transaction.currencyCode tem um código de moeda válido.

   3. Se você pretende importar eventos search, verifique se há uma coluna hits.page.searchKeyword ou hits.customVariable.searchQuery.

      A importação de eventos search é compatível, mas não é mapeada do Google Analytics 360 da mesma forma que outros tipos de eventos, porque o Google Analytics 360 não é compatível nativamente com o evento search. tipos Durante a importação, eventos search são construídos do Google Analytics 360 combinando informações consulta de pesquisa e, se houver, a impressão do produto.

      A consulta de pesquisa é derivada de hits.page.searchKeyword ou de hits.customVariables.customVarValue se hits.customVariables.customVarName for searchQuery. A impressão do produto será retirada de hits.product se hits.product.isImpressions for TRUE.

3. Verifique a consistência dos IDs dos itens entre o catálogo enviado e a tabela de eventos do usuário do Analytics 360.

   Usando qualquer ID do produto da coluna hits.product.productSKU na visualização da tabela do BigQuery, use o método product.get para garantir que o mesmo produto esteja no seu catálogo enviado.

   export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
   
      curl \
        -v \
        -X GET \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

Importar eventos do Google Analytics 360

É possível importar eventos do Google Analytics 360 usando o Pesquise o console do Retail ou o método userEvents.import.

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 application-default print-access-token)"" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Importar visualizações da página inicial do Google Analytics 360 com o BigQuery

No Google Analytics 360, os eventos de visualização da página inicial não são diferentes de outros eventos de visualização de página. Isso significa que os eventos de visualização da página inicial não são importados como eventos de outros tipos (por exemplo, visualização de página de detalhes) em Importar os eventos do Google Analytics 360.

O procedimento a seguir explica como extrair eventos de visualização de página inicial de seus dados do Google Analytics 360 e importá-los para o Vertex AI para Pesquisa para Retail. Em suma, isso é feito extraindo os dados vistas da casa (identificada pelo caminho da página inicial) em uma nova tabela do BigQuery e, em seguida, importar os dados dessa nova tabela para a Vertex AI para Pesquisa para varejo.

Para importar eventos de visualização da página inicial do Google Analytics 360 para o Vertex AI para Pesquisa para Retail:

1. Crie um conjunto de dados do BigQuery ou verifique se você tem um É possível adicionar uma tabela ao conjunto de dados do BigQuery disponível.

   Esse conjunto de dados pode estar no projeto da Vertex AI para Pesquisa para varejo ou no projeto em que você tem os dados do Analytics 360. Ele é o alvo conjunto de dados para copiar o Analytics 360 eventos de visualização da página inicial.

2. Crie uma tabela do BigQuery no conjunto de dados da seguinte maneira:

   1. Substitua as variáveis no código SQL a seguir da seguinte maneira.

      • target_project_id::o projeto em que o conjunto de dados da etapa 1 está localizado.

      • target_dataset: nome do conjunto de dados da etapa 1.

      CREATE TABLE TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage (
       eventType STRING NOT NULL,
       visitorId STRING NOT NULL,
       userId STRING,
       eventTime STRING NOT NULL
      );

   2. Copie o exemplo de código SQL.

   3. Abra a página do BigQuery no console do Google Cloud.

      Acessar a página do BigQuery

   4. Selecione o projeto de destino, se ainda não estiver selecionado.

   5. No painel Editor, cole o exemplo de código SQL.

   6. Clique em play_circle Executar e aguarde a consulta terminar de ser executada.

   A execução desse código cria uma tabela no formato target_project_id:target_dataset.ga_homepage_YYYYMMDD: por exemplo, my-project:view_events.ga_homepage_20230115.

3. Copie os eventos de visualização da página inicial do Google Analytics 360 da sua tabela de dados do Google Analytics 360 para a tabela criada na etapa 2 anterior.

   1. Substitua as variáveis no código de exemplo de SQL a seguir:

      • source_project_id::o ID do projeto que contém o Dados do Analytics 360 em um arquivo do BigQuery tabela.

      • source_dataset: o conjunto de dados no projeto de origem que contém os dados do Google Analytics 360 em um Tabela do BigQuery.

      • source_table: a tabela no projeto de origem que contém os dados do Analytics 360.

      • target_project_id: o mesmo ID do projeto de destino que no na etapa 2 anterior.

      • target_dataset: o mesmo conjunto de dados de destino do exemplo anterior etapa 2.

      • path: é o caminho para a página inicial. Geralmente é /, por exemplo, se a página inicial for example.com/. No entanto, se a página inicial for como examplepetstore.com/index.html, o caminho é /index.html.

      INSERT INTO `TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage(eventType,visitorId,userID,eventTime)`
      
      SELECT
        "home-page-view" as eventType,
        clientId as visitorId,
        userId,
        CAST(FORMAT_TIMESTAMP("%Y-%m-%dT%H:%M:%SZ",TIMESTAMP_SECONDS(visitStartTime)) as STRING) AS eventTime
      
      FROM
        `SOURCE_PROJECT_ID.SOURCE_DATASET.SOURCE_TABLE`, UNNEST(hits) as hits
      
      WHERE hits.page.pagePath = "PATH" AND visitorId is NOT NULL;

   2. Copie o exemplo de código SQL.

   3. Abra a página do BigQuery no console do Google Cloud.

      Acessar a página do BigQuery

   4. Selecione o projeto de destino, se ainda não estiver selecionado.

   5. No painel Editor, cole o exemplo de código SQL.

   6. Clique em play_circle Executar e aguarde a consulta terminar de ser executada.

4. Siga as instruções em Importar eventos de usuário do BigQuery. os eventos de visualização da página inicial da tabela de destino. Durante a seleção do esquema, se que você importar usando o console, selecione Esquema de eventos de usuário de varejo. se você importar Usando userEvents.import, especifique user_event para o valor dataSchema.

5. Exclua a tabela e o conjunto de dados criados nas etapas 1 e 2.

Importar eventos do usuário do Google Analytics 4 com o BigQuery

Você poderá importar eventos de usuário do Google Analytics 4 se tiver integrou o Google Analytics 4 ao BigQuery e use Comércio eletrônico do Google Analytics.

Os procedimentos a seguir pressupõem que você esteja familiarizado com o uso BigQuery e Google Analytics 4.

Antes de começar

Antes de iniciar as próximas etapas, verifique se:

• Você usa o comércio eletrônico do Google Analytics.
• Você tem BigQuery vinculado ao Google Analytics 4.

Verificar a fonte de dados

Para garantir que os dados de eventos do usuário estejam preparados para importação, siga estas etapas: etapas.

Para uma tabela de campos do Google Analytics 4 que a Vertex AI para Pesquisa para Retail usa e para quais campos da Vertex AI para Pesquisa para Retail eles são mapeados, consulte os campos de evento do usuário do Google Analytics 4.

Para todos os parâmetros de evento do Google Analytics, consulte o Documentação de referência dos eventos do Google Analytics.

1. Verifique se os dados de eventos do usuário que você vai importar estão formatados corretamente em uma tabela do BigQuery a que você tem acesso.

   • O conjunto de dados precisa ser nomeado como analytics_PROPERTY_ID.
   • A tabela precisa ser nomeada como events_YYYYMMDD.

   Para informações sobre os nomes e o formato das tabelas, consulte a Documentação do Google Analytics.

2. Na Console do Google Cloud do BigQuery, selecione o conjunto de dados no painel Explorador e encontre a tabela de usuários que você planeja importar.

   Verifique se:

   1. A coluna event_params.key tem uma chave currency e que a respectiva o valor da string é um código de moeda válido.

   2. Se você pretende importar eventos search, verifique se a coluna event.event_params.key tem uma chave search_term e um valor associado.

      É possível importar eventos search, mas eventos search não são mapeados do Google Analytics 4, assim como outros tipos de evento porque o Google Analytics 4 não oferece suporte nativo à Tipo de evento search da Vertex AI para Pesquisa para varejo. Durante a importação, Os eventos search são criados com base no Google Analytics 4 combinando informações view_item_list e o parâmetro search_term.

      Para saber mais sobre search no Google Analytics 4, consulte search na documentação do Google Analytics.

3. Verifique a consistência dos IDs de itens entre o catálogo enviado e o Tabela de eventos do usuário do Google Analytics 4.

   Para garantir que um produto na tabela de usuários do Google Analytics 4 seja também no catálogo enviado, copie o ID do produto da Coluna event.items.item_id na visualização da tabela do BigQuery e use o método product.get para verificar se o ID do produto está no catálogo enviado.

   export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
   
      curl \
        -v \
        -X GET \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

Configurar o acesso ao BigQuery

Siga as instruções em Como configurar o acesso ao conjunto de dados do BigQuery para fornecer à sua conta de serviço da Pesquisa da Vertex AI para varejo o papel de proprietário de dados do BigQuery no seu conjunto de dados do BigQuery.

Importar seus eventos do Google Analytics 4

É possível importar eventos do Google Analytics 4 usando o Pesquise o console do Retail ou o método userEvents.import.

Importar eventos do Google Analytics 4 usando o console

1. Acesse Dados> no console da Pesquisa para varejo.
   
   Acessar a página "Dados"
2. Clique em Importar para abrir o painel Importar dados.
3. Escolha Eventos do usuário.
4. Selecione BigQuery como a fonte de dados.

5. Selecione o esquema de dados.

   • Google Analytics 4: use para eventos do Google Analytics 4.
   • Google Analytics 360: use para eventos do Google Analytics 360, a menos que você esteja importando apenas visualizações da página inicial de eventos do Google Analytics 360. Nesse caso, use o Esquema de eventos do usuário de varejo.
   • Esquema de eventos do usuário de varejo: use para importar eventos de origens diferentes do Google Analytics, e para Como importar apenas visualizações da página inicial de eventos do Google Analytics 360.
6. Insira a tabela do BigQuery em que seus dados estão localizados.
7. Opcional: insira o local de um bucket do Cloud Storage em seu projeto como um local temporário para seus dados.
   Se não for especificado, um local padrão é usados. Se especificado, os buckets do BigQuery e do Cloud Storage na mesma região.
8. Opcional: em Mostrar opções avançadas, digite a localização de um bucket do Cloud Storage no projeto como um local temporário para os dados.
   
   Se não for especificado, um local padrão será usado. Caso seja especificado, o bucket do BigQuery e do Cloud Storage precisam estar na mesma região.
9. Clique em Importar.

Importar eventos do Google Analytics 4 usando a API

Inclua os dados dos eventos da chamada para importar seus eventos do usuário ao método userEvents.import. Consulte a Referência da API userEvents.import.

Para dataSchema, use o valor user_event_ga4.

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 application-default print-access-token)"" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event_ga4"
    }
  }
}'

Importar eventos de usuário inline

Você pode importar eventos de usuário inline incluindo os dados dos eventos na sua chamada para o método userEvents.import.

A maneira mais fácil de fazer isso é colocar os dados de evento do usuário em um arquivo JSON e fornecer o arquivo para cURL.

Para os formatos dos tipos de evento de usuário, consulte Sobre os eventos de usuário.

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Dados históricos do catálogo

Também é possível importar os dados do catálogo histórico que aparecem nos eventos históricos do usuário. Esses dados históricos de catálogo podem ser úteis porque informações anteriores do produto podem ser usadas para enriquecer os eventos do usuário, o que pode melhorar a precisão do modelo.

Para mais detalhes, consulte Importar dados do catálogo histórico.

Ver eventos importados

Veja as métricas de integração de eventos na guia Eventos do console da Pesquisa para Retail página Dados. Esta página mostra todos os eventos gravados ou importados no último ano. As métricas podem ocupar até 24 horas para aparecer após a ingestão de dados.

Acessar a página "Dados"

A seguir

• Comece a gravar eventos de usuários.
• Gerencie seus eventos de usuários.