Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Varejo. Para usar a pesquisa de varejo na fase GA restrita, entre em contato com a equipe de vendas do Cloud.

Se você estiver usando apenas o Recommendations AI, permaneça no Console do Recommendations e consulte a documentação do Recommendations AI.

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:

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.

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

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

    Acessar a página "Dados"

  2. Clique em Importar para abrir o painel "Importar".

  3. Escolha Eventos do usuário.

  4. Selecione a ramificação em que você fará upload dos eventos.

  5. Selecione Cloud Storage como a fonte de dados.

  6. Insira o local dos seus dados no Cloud Storage.

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

  8. (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.

  9. Clique em Importar.

cURL

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

  1. 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"}
    }
    
  2. 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

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

    Acessar a página "Dados"

  2. Clique em Importar para abrir o painel "Importar".

  3. Escolha Eventos do usuário.

  4. Selecione a ramificação em que você fará upload dos eventos.

  5. Selecione BigQuery como a fonte de dados.

  6. Insira a tabela do BigQuery em que seus dados estão localizados.

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

  8. (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.

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

Verificar a fonte de dados

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

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

    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.

  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

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.

  1. Crie o arquivo JSON:

    {
    "inputConfig": {
      "userEventInlineSource": {
          "userEvents": [
            {
              <userEvent1>>
            },
            {
              <userEvent2>
            },
            ....
          ]
        }
      }
    }
    
  2. 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