Esta página foi traduzida pela API Cloud Translation.

Importar 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 modelos da API Retail exigem dados de evento 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 aplicam-se ao Recommendations AI e à pesquisa de varejo. Depois de importar os dados para a API Retail, ambos os serviços podem usar esses eventos. Portanto, não é necessário importar os mesmos dados duas vezes, caso use os dois serviços.

É possível:

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 (pré-lançamento particular)
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ários do Cloud Storage.

Para orientações passo a passo sobre esta tarefa diretamente no editor do Cloud Shell, clique em Orientações:

Orientação

As seções a seguir guiam você pelas mesmas etapas que você encontra clicando em Orientações.

Tutorial de importação de eventos do BigQuery

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

Para orientações passo a passo sobre esta tarefa diretamente no editor do Cloud Shell, clique em Orientações:

Orientação

As seções a seguir guiam você pelas mesmas etapas que você encontra clicando em Orientações.

Tutorial de importação de eventos in-line

Neste tutorial, mostramos como importar dados de eventos do usuário in-line.

Para orientações passo a passo sobre esta tarefa diretamente no editor do Cloud Shell, clique em Orientações:

Orientação

As seções a seguir guiam você pelas mesmas etapas que você encontra clicando em Orientações.

Antes de começar

Para evitar erros de importação e garantir que a API Retail tenha dados suficientes para gerar bons resultados, analise as seguintes informações antes de importar os 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.
O Recommendations AI e o Retail Search têm requisitos mínimos de dados diferentes. Verifique se os eventos do usuário atendem aos requisitos do serviço que você pretende usar:
- Veja os requisitos e as práticas recomendadas para eventos do usuário para os requisitos da Pesquisa de varejo e do Recommendations AI.
- Se você usar os modelos do Recommendations AI, consulte também Requisitos de dados de eventos do usuário, que lista outros requisitos, dependendo do tipo de modelo de recomendação e do objetivo de otimização que você planeja usar.

Considerações sobre importação de eventos

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

Cloud Storage	Descrição	Importe dados em um formato JSON de arquivos carregados em um bucket do Cloud Storage. Cada arquivo precisa ter 2 GB ou menos, e até 100 arquivos por vez podem ser importados. A importação pode ser feita usando o Console do Cloud ou o cURL. Usa o formato de dados JSON `Product`, que permite atributos personalizados.
	Quando usar	Se você precisa de um volume maior de dados para carregar em uma única etapa.
	Limitações	Se os dados estiverem no Google Analytics ou no Merchant Center, eles só poderão ser exportados para o BigQuery e precisarão da etapa extra para importá-los no Cloud Storage.
BigQuery	Descrição	Importe dados de uma tabela do BigQuery carregada anteriormente que use o esquema de varejo. Pode ser realizado usando o Console do Cloud ou o cURL.
	Quando usar	Se você também estiver usando dados de eventos de análise ou pré-processamento antes de importá-los.
	Limitações	Exige a etapa extra de criação de uma tabela do BigQuery que é mapeada para o esquema de varejo. Se você tem um alto volume de eventos de usuários, considere também que o BigQuery é um recurso de custo mais alto do que o Cloud Storage.
BigQuery com Google Analytics 360	Descrição	Importe dados preexistentes do Google Analytics 360 para o varejo.
	Quando usar	Se você tiver o Google Analytics 360 e acompanhar as conversões de recomendações ou pesquisas. Não é necessário um mapeamento de esquema adicional.
	Limitações	Somente um subconjunto de atributos está disponível, portanto, alguns recursos avançados de varejo não podem ser usados. Esse procedimento é obrigatório se você pretende usar a pesquisa de varejo.
BigQuery com Google Analytics 4 (pré-lançamento particular)	Descrição	Importe dados preexistentes do Google Analytics 4 para o varejo.
	Quando usar	Se você tem o Google Analytics 4 e acompanha as conversões de recomendações ou pesquisas. Não é necessário um mapeamento de esquema adicional.
	Limitações	Somente um subconjunto de atributos está disponível, portanto, alguns recursos avançados de varejo não podem ser usados. Se você planeja usar a Pesquisa de varejo, precisa configurar pares de chave-valor de parâmetros de evento para rastreamento. A chave recomendada é `search_query`.
Importação in-line	Descrição	Importação usando uma chamada para o método `userEvents.import`.
	Quando usar	Se você quiser ter mais privacidade para que toda a autenticação ocorra no back-end e ser capaz de executar uma importação de back-end.
	Limitações	Geralmente, isso é mais complicado do que uma importação pela Web.

Importar eventos de usuário do Cloud Storage

Importe eventos do usuário do Cloud Storage usando o Console do Cloud ou o método userEvents.import.

Console

Acesse a página "Dados de varejo" no Console do Google Cloud.

Acessar a página "Dados"
Clique em Importar para abrir o painel Importar dados.
Escolha Eventos do usuário.
Selecione Google Cloud Storage como a fonte de dados.
Escolha Esquema de eventos de usuários de varejo como o esquema.
Insira o local dos seus dados no Cloud Storage.
Clique em Importar.

cURL

Use o método userEvents.import para importar eventos de usuário.

Crie um arquivo de dados para os parâmetros de entrada para a importação. Use o objeto GcsSource para apontar para o bucket do Cloud Storage.

É possível fornecer vários arquivos ou apenas um.
- INPUT_FILE: um ou mais arquivos no Cloud Storage contendo os dados de evento do usuário. Consulte Eventos do usuário para ver exemplos de cada formato de tipo de evento do usuário. Verifique se cada evento de usuário está em uma linha única, sem quebras de linha.
- ERROR_DIRECTORY: um diretório do Cloud Storage para informações de erro sobre a importação.
Os campos do arquivo de entrada precisam estar no formato gs://<bucket>/<path-to-file>/. O diretório de erro precisa estar no formato gs://<bucket>/<folder>/. Se o diretório de erro não existir, a API Retail o criará. O bucket já precisa existir
```
{
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  },
  "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}
```

Importe as informações do seu catálogo para a API Retail fazendo uma solicitação POST para o método REST 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 application-default print-access-token)"" \
     --data @./DATA_FILE.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"
  }
}'

Importar eventos de usuários do BigQuery

Importe eventos do usuário do BigQuery usando o Console do Cloud ou o método userEvents.import.

Console

Acesse a página "Dados de varejo" no Console do Google Cloud.

Acessar a página "Dados"
Clique em Importar para abrir o painel Importar dados.
Escolha Eventos do usuário.
Selecione BigQuery como a fonte de dados.
Escolha Esquema de eventos de usuários de varejo como o esquema.
Insira a tabela do BigQuery em que seus dados estão localizados.
(Opcional) Insira o local de um bucket do Cloud Storage no projeto como um local temporário para seus dados.
Se não for especificado, um local padrão será usado. Se especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
(Opcional) Em Mostrar opções avançadas, insira o local de um bucket do Cloud Storage no projeto como um local temporário para seus dados.

Se não for especificado, um local padrão será usado. Se especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
Clique em Importar.

cURL

Use o método userEvents.import para importar eventos de usuário.

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 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": "user_event"
    }
  }
}'

Se o conjunto de dados do BigQuery pertencer a um projeto diferente do projeto da API Retail, siga as instruções em Como configurar o acesso ao conjunto de dados do BigQuery para fornecer à sua conta de serviço do Retail o papel editor de dados do BigQuery no projeto do BigQuery; Modifique a solicitação de importação para especificar o ID do projeto do BigQuery:

"bigQuerySource": {
     "projectId": "BQ_PROJECT_ID",
   }

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

Você poderá importar eventos de usuário do Google Analytics 360 se tiver integrado o Google Analytics 360 ao BigQuery e usar o comércio eletrônico avançado.

Para os procedimentos a seguir, consideramos que você esteja familiarizado com o uso do BigQuery e do Google 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

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

A tabela precisa ter o formato project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

Consulte a documentação do Google Analytics para mais informações sobre o formato de tabela.
No Console do Google Cloud no BigQuery, selecione a tabela do painel Explorer para visualizar a tabela.

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.
  
  Observação: o tipo de evento purchase-complete de varejo requer um código de moeda. Se você estiver importando eventos de compra, que alguns modelos de varejo exigem, atualize os relatórios de comércio eletrônico avançado para incluir o código da moeda.
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, a API Retail cria eventos search do Analytics 360 combinando informações da consulta de pesquisa e, se presente, 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.

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

Importe os eventos do usuário incluindo os dados dos eventos na chamada para o método userEvents.import.

Para dataSchema, use o valor user_event_ga360.

curl

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"
    }
  }
}'

Java

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;
}

Se o conjunto de dados do BigQuery pertencer a um projeto diferente do projeto de varejo, siga as instruções em Como configurar o acesso ao conjunto de dados do BigQuery para fornecer à sua conta de serviço de varejo um Papel de editor de dados do BigQuery para o projeto do BigQuery. Modifique a solicitação de importação para especificar o ID do projeto do BigQuery:

"bigQuerySource": {
     "projectId": "GA360_BQ_PROJECT_ID",
   }

Como importar eventos do usuário do Google Analytics 4 com o BigQuery (pré-lançamento particular)

Você poderá importar eventos de usuário do Google Analytics 4 se tiver integrado o Google Analytics 4 com o BigQuery e usar o comércio eletrônico avançado.

Antes de começar

Antes de começar, verifique o seguinte:

você estiver usando o comércio eletrônico avançado;
Você tem o BigQuery vinculado ao Google Analytics 4.

Solicitar acesso

O acesso a esse recurso de visualização particular exige permissão:

Entre em contato com a equipe de suporte de varejo para pedir permissão e instruções sobre como importar eventos do usuário do Google Analytics 4.

Importar eventos de usuário in-line

curl

Importe os eventos do usuário in-line incluindo os dados dos eventos na 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 saber os formatos dos tipos de evento do usuário, consulte Eventos do usuário.

Crie o arquivo JSON:

{
"inputConfig": {
  "userEventInlineSource": {
      "userEvents": [
        {
          <userEvent1>>
        },
        {
          <userEvent2>
        },
        ....
      ]
    }
  }
}

Chame o método POST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data @./data.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"

Java

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 a API Retail pode utilizar informações anteriores do produto 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.

A seguir

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