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:
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:
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:
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 formatogs://<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 RESTuserEvents: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:
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
).A coluna
hits.transaction.currencyCode
tem um código de moeda válido.Se você pretende importar eventos
search
, verifique se há uma colunahits.page.searchKeyword
ouhits.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 eventosearch
. tipos Durante a importação, a API Retail cria eventossearch
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 dehits.customVariables.customVarValue
sehits.customVariables.customVarName
forsearchQuery
. A impressão do produto será retirada dehits.product
sehits.product.isImpressions
forTRUE
.
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étodoproduct.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
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
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.