Como 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. Quando você importa dados para a API Retail, os dois serviços podem usar esses eventos. Portanto, não é necessário 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 in-line com o método userEvents.import;

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 importação em lote de eventos de usuário históricos, quando você pode 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 para o varejo.
	Quando usar	Se você tem o Google Analytics e rastreia conversões de recomendações ou pesquisass 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.
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.

Como importar eventos do usuário do Cloud Storages

Importe eventos de usuários 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".
Escolha Eventos do usuário.
Selecione a ramificação em que você fará upload dos eventos.
Selecione Cloud Storage como a fonte de dados.
Insira o local dos seus dados no Cloud Storage.
(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. Caso seja especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
(Opcional) Escolha se você quer programar um upload recorrente dos seus eventos de usuário.

Esta opção só estará disponível se você tiver importado eventos de usuários para a API Retail pelo menos uma vez.
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"
  }
}'

Como importar eventos do usuário do BigQuery

Importe eventos de usuários 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".
Escolha Eventos do usuário.
Selecione a ramificação em que você fará upload dos eventos.
Selecione BigQuery como a fonte de dados.
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. Caso seja especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
(Opcional) Escolha se você quer programar um upload recorrente dos seus eventos de usuário.

Esta opção só estará disponível se você tiver importado eventos de usuários para a API Retail pelo menos uma vez.
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",
   }

Como importar eventos do usuário 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

você estiver usando o comércio eletrônico 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 do BigQuery, selecione a tabela no painel do 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 de usuários 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.