Visão geral

Com o serviço do Cloud Retail e a API Retail, os clientes podem criar sistemas de recomendações personalizadas de ponta a ponta sem precisar de muita experiência com machine learning, sistema de recomendações ou o Google Cloud. Para usar os serviços de recomendação e pesquisa de produtos da API Retail, você precisa criar ou importar dados do catálogo de produtos e de eventos do usuário relacionados a esse catálogo.

Neste laboratório, você vai preparar um ambiente para os serviços de IA de recomendações para varejo e pesquisa de produtos fazendo upload de dados de eventos de usuário e catálogo de produtos usando várias técnicas. Você vai analisar alguns erros comuns de ingestão de dados e examinar os dados de eventos e catálogos de varejo usando o console do Cloud e a API Retail.

Este laboratório usa um subconjunto do conjunto de dados do Google Merchant Center para o catálogo de produtos. Os dados exportados diretamente do Google Merchant Center usam um esquema que não é compatível com a API Retail data ingestion. Por isso, o conjunto de dados usado no laboratório foi modificado para ficar em conformidade com o esquema da Retail.

Objetivos

Neste laboratório, você vai aprender as seguintes tarefas:

• Ativar a API Retail.
• Importar dados do catálogo de produtos e de eventos do usuário do BigQuery e do Cloud Storage.
• Examinar eventos e erros de importação de dados.
• Analisar o catálogo de produtos e os dados de eventos do usuário.
• Fazer upload de dados de eventos do usuário usando a API Retail.

Configuração e requisitos

Configuração do laboratório

Para cada laboratório, você recebe um novo projeto do Google Cloud e um conjunto de recursos por um determinado período e sem custos financeiros.

1. Faça login no Qwiklabs em uma janela anônima.

2. Confira o tempo de acesso do laboratório (por exemplo, 1:15:00) e finalize todas as atividades nesse prazo.
   Não é possível pausar o laboratório. Você pode reiniciar o desafio, mas vai precisar refazer todas as etapas.

3. Quando tudo estiver pronto, clique em Começar o laboratório.

4. Anote as credenciais (Nome de usuário e Senha). É com elas que você vai fazer login no Console do Google Cloud.

5. Clique em Abrir Console do Google.

6. Clique em Usar outra conta, depois copie e cole as credenciais deste laboratório nos locais indicados.
   Se você usar outras credenciais, vai receber mensagens de erro ou cobranças.

7. Aceite os termos e pule a página de recursos de recuperação.

Iniciar o Cloud Shell

O Google Cloud pode ser operado remotamente na sua própria máquina. Este laboratório usa o console do Google Cloud e o Cloud Shell, um ambiente de linha de comando executado no Google Cloud.

1. No console do Cloud, clique em Ativar o Cloud Shell.

   

   Observação: se você nunca iniciou o Cloud Shell, vai ver uma tela intermediária com a descrição dele. Se esse for o caso, clique em Continuar e você não a verá novamente.

   Esta é a aparência dessa tela única:

   

   Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.

   O Cloud Shell oferece acesso de terminal a uma máquina virtual hospedada na nuvem. A máquina virtual tem todas as ferramentas de desenvolvimento necessárias. Ela tem um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste laboratório, quase todo o trabalho pode ser feito no console do Cloud e no Cloud Shell usando apenas um navegador.

   Depois de se conectar ao Cloud Shell, você vai ver que sua conta já está autenticada e que o projeto está configurado com seu ID do projeto.

2. Execute o seguinte comando no Cloud Shell para confirmar se a conta está autenticada:

   gcloud auth list

   Saída:

   Credentialed Accounts ACTIVE: * ACCOUNT: {{{user_0.username| Lab User Name}}}

3. Para definir a conta ativa, execute:

   gcloud config set account {{{user_0.username| Lab User Name}}} Observação: a gcloud é a ferramenta de linha de comando avançada e unificada do Google Cloud. Ela vem pré-instalada no Cloud Shell. Entre os recursos da ferramenta, a gcloud oferece o preenchimento com tabulação no shell. Para mais informações, consulte o guia de visão geral da gcloud CLI.

4. Execute o seguinte comando para confirmar que você está usando o projeto correto neste laboratório:

   gcloud config list project

   Saída:

   [core] project = {{{project_0.project_id | Project ID}}}

5. Se o projeto correto não estiver na lista, use o comando a seguir para configurá-lo:

   gcloud config set project {{{project_0.project_id| Project ID}}}

   Saída:

   Updated property [core/project].

Tarefa 1: ativar a API Retail

Antes de começar a usar as APIs Retail Recommendations AI ou Retail Search, você precisa ativar a API Retail.

1. No menu de navegação (), clique em Ver todos os produtos na seção Inteligência artificial e selecione Pesquisa em E-commerce.

2. Clique em Ativar API.

3. Clique em Continuar e em Aceitar para confirmar que aceitou os termos de dados.

4. Clique em Primeiros passos.

Tarefa 2: importar dados de eventos do usuário e do catálogo de produtos

Nesta tarefa, você vai importar dados do catálogo de produtos do BigQuery e de eventos do usuário do Cloud Storage.

Importar dados do esquema da tabela de produtos do Merchant Center usando o BigQuery

A tabela merchant_center.products contém dados de catálogo que foram exportados de uma conta de teste no Google Merchant Center usando o esquema da tabela de produtos do Google Merchant Center. Esse conjunto de dados pode ser importado como dados de catálogo usando o console ou a API Recommendations AI mais antigos. A API Retail, que substitui a API Recommendations AI, não aceita a importação de dados que usam o esquema da tabela de produtos do Merchant Center. Todas as importações de dados precisam usar o esquema da Retail. Você ainda vai tentar importar esses dados usando a API Retail para saber como inspecionar erros de importação de dados.

1. No console do GCP, clique em Pesquisar em E-commerce > Dados para abrir a página de gerenciamento de dados de varejo.

2. Verifique se a guia Catálogo está selecionada e clique em Importar.

3. Configure os parâmetros de importação da seguinte maneira para importar o catálogo de produtos:

   • Em Tipo de importação, selecione Catálogo de produtos
   • Em Fonte de dados, selecione BigQuery
   • Em Importar ramificação, selecione Ramificação 0

4. Em Tabela do BigQuery, clique em Procurar.

5. Digite produtos na caixa de pesquisa e clique em Pesquisar.

6. Selecione o botão de opção da tabela products - Dataset: merchant_center.

7. Clique em Selecionar.

8. Clique em Importar.

Não é possível continuar porque a tabela de origem não tem um campo id.

Há muitos outros problemas com os dados devido ao esquema.

9. Role para cima e, em Esquema de dados, selecione Merchant Center.

10. Clique em Importar.

11. Clique no X para fechar o pop-up que apareceu para informar que a importação foi agendada.

12. Clique em Cancelar para fechar a página de importação e voltar à página "Dados de varejo" para verificar o status da importação de dados.

Importar dados do esquema de produtos da Retail usando o BigQuery

Nesta tarefa, importe dados de produtos para o catálogo de uma tabela do BigQuery que usa o esquema de produtos da Retail.

1. No console do GCP, no menu de navegação (), clique em Ver todos os produtos. Na seção Inteligência artificial, selecione Pesquisa em E-commerce > Dados para abrir a página de gerenciamento de dados da Retail.

2. Verifique se a guia Catálogo está selecionada e clique em Importar.

3. Configure os parâmetros de importação da seguinte maneira para importar o catálogo de produtos:

   • Em Tipo de importação, selecione Catálogo de produtos
   • Em Importar ramificação, selecione Ramificação 0
   • Em Fonte de dados, selecione BigQuery

4. Em Esquema de dados, selecione Esquema de catálogos de produtos da Retail.

5. Em Tabela do BigQuery, clique em Procurar.

6. Digite produtos na caixa de pesquisa e clique em Pesquisar.

7. Selecione o botão de opção da tabela products - Dataset: retail.

8. Clique em Selecionar.

9. Clique em Importar.

Você precisa esperar que um pop-up apareça com uma mensagem semelhante a esta:

Quando a tarefa de importação for programada, você também verá os detalhes de um comando gcloud scheduler exibido, que pode ser usado para programar uma tarefa regular de importação de dados.

10. Clique no X para fechar o pop-up que apareceu para informar que a importação foi agendada.

11. Clique em Cancelar para fechar a página de importação e voltar à página "Dados de varejo" para verificar o status da tarefa de importação de dados do catálogo.

12. No menu de navegação Pesquisar em E-commerce, clique em Dados e depois em Status da atividade para monitorar o progresso da tarefa de importação.

A tarefa de importação levará um ou dois minutos para que o status da tarefa de importação na seção Atividade de importação do catálogo de produtos mude para Concluído. Serão importados 1.268 itens.

Importar dados de eventos do usuário usando o Cloud Storage

Nesta tarefa, você vai importar dados de eventos do usuário de uma tabela do BigQuery.

1. No console do GCP, no menu de navegação (), clique em Ver todos os produtos. Na seção Inteligência artificial, selecione Pesquisa em E-commerce > Dados para abrir a página de gerenciamento de dados de varejo.

2. Verifique se a guia Eventos está selecionada e clique em Importar.

3. Configure os parâmetros de importação da seguinte maneira para importar o catálogo de produtos:

   • Em Tipo de importação, selecione Eventos do usuário
   • Em Fonte de dados, selecione Google Cloud Storage

4. Para Local do Google Cloud Storage, clique no botão Procurar.

5. Acesse o bucket de armazenamento chamado e selecione o arquivo recent_retail_events.json.

6. Clique no nome do arquivo para garantir que ele seja selecionado.

7. Clique em Selecionar.

8. Clique em Importar.

9. Clique no X para fechar o pop-up que apareceu para informar que a importação foi agendada.

10. Clique em Cancelar para fechar a página de importação e retornar à página "Dados de varejo" para verificar o status da tarefa de importação de dados de eventos.

Você precisa esperar que um pop-up apareça com uma mensagem semelhante a esta:

Quando a tarefa de importação for programada, você também verá os detalhes de um comando gcloud scheduler exibido, que pode ser usado para programar uma tarefa regular de importação de eventos.

9. Aguarde a tarefa de importação ser programada com o comando gcloud scheduler exibido.

10. Clique no X para fechar o pop-up que apareceu para informar que a importação foi agendada.

11. Clique em Cancelar para fechar a página de importação e retornar à página "Dados de varejo" para verificar o status da tarefa de importação de dados de eventos.

12. No menu de navegação Pesquisar em E-commerce, clique em Dados e depois em Status da atividade para monitorar o progresso da tarefa de importação.

A tarefa de importação vai levar um ou dois minutos para que o status dela na seção Atividade de importação de eventos do usuário mude para Concluído. Aproximadamente 32.000 itens serão importados e 5 itens não serão.

Tarefa 3: examinar eventos e erros na importação de dados

Nesta tarefa, você vai analisar os jobs de importação de dados e conferir alguns dos erros registrados pelas tarefas de importação quando dados inválidos são encontrados.

1. No menu de navegação Pesquisar em E-commerce, clique em Dados e depois em Status da atividade para monitorar o progresso da tarefa de importação.

2. Clique na guia Eventos do usuário e depois em Ver registros de erros completos na coluna Detalhes para analisar os erros.

Isso vai abrir a pasta /error no bucket do Cloud Storage em que os dados de origem estavam localizados.

3. Clique no nome do arquivo que corresponde ao arquivo de dados de eventos que você importou. Ele terá um tamanho de cerca de 1 kilobyte.

4. Clique em Fazer download para baixar o arquivo e abra no seu computador para analisar os detalhes do erro. Você vai ver cinco eventos com falha na importação devido a vários problemas com o esquema de dados nesses eventos.

5. Volte ao console do Cloud e feche a guia do Cloud Storage.

6. Abra a guia Status da atividade da Retail e clique em Fechar para fechar a janela pop-up Status da atividade.

Tarefa 4: analisar o catálogo de produtos e os dados de eventos do usuário

Nesta tarefa, você vai analisar os dados de produtos e eventos que importou.

1. No menu de navegação Pesquisar em E-commerce, clique em Dados e verifique se a guia Catálogo está selecionada.

2. Em Nome da ramificação, deixe a ramificação definida como Ramificação 0 (padrão).

3. A lista de produtos do catálogo mostra os 1.268 registros de produtos que foram enviados para o catálogo, dos quais 746 estão em estoque.

4. Em Filtro, digite GGOEGCBT136699.

Isso mostra o registro do produto Ioiô amarelo Google. O produto está esgotado.

5. Clique no ícone Link para tentar abrir o link. A página que é aberta diz: "Desculpe, esta página não está disponível".

6. Feche a guia do produto que foi aberta para voltar à página "Pesquisar dados de varejo".

7. Em Filtro, insira GGOECAEB163612.

Isso exibe o registro do produto Camiseta preta de nuvem Google. Observe que há estoque deste produto.

8. Clique no ícone Link para abrir o link. A página do produto na Google Merchandise Store será aberta.

9. Feche a guia do produto que foi aberta para voltar à página "Pesquisar dados de varejo".

Tarefa 5: fazer upload dos dados de eventos do usuário usando a API Retail

Agora você vai usar o curl e outros utilitários de linha de comando para fazer chamadas para a API Retail Recommendations AI e descobrir como fazer solicitações, receber recomendações e depois filtrar e refinar os resultados.

Criar uma conta de serviço do IAM para autenticar solicitações

1. Crie uma variável de ambiente para armazenar o ID do projeto:

   export PROJECT_ID=$(gcloud config get-value core/project)

2. Crie uma conta de serviço do IAM para ter acesso controlado à API Retail:

   export SA_NAME="retail-service-account" gcloud iam service-accounts create $SA_NAME --display-name $SA_NAME

3. Vincule a conta de serviço ao papel do IAM de editor da Retail:

   gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:$SA_NAME@${PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/retail.editor"

Permitir que a conta de usuário do laboratório use a representação com a nova conta de serviço

Ao criar uma vinculação de papel na conta de serviço para o usuário do laboratório com o papel de criador de token da conta de serviço, o usuário do laboratório pode usar a identidade temporária de conta de serviço para gerar com segurança tokens de autenticação de duração limitada para a conta de serviço. Esses tokens podem ser usados para testar interativamente o acesso a APIs e serviços.

1. Crie uma vinculação de papel na conta de serviço da API Retail para sua conta de usuário permitir a representação:

   export USER_ACCOUNT=$(gcloud config list --format 'value(core.account)') gcloud iam service-accounts add-iam-policy-binding $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com --member "user:$USER_ACCOUNT" --role roles/iam.serviceAccountTokenCreator

2. Gere um token de acesso temporário para a API Retail:

   export ACCESS_TOKEN=$(gcloud auth print-access-token --impersonate-service-account $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com )

Enviar um evento de usuário para a API Retail

Você vai enviar um evento de usuário de amostra para a API Retail transmitindo dados de eventos do usuário no formato JSON para o método userEvents:write da API Retail.

1. Armazene os dados JSON de amostra de eventos do usuário em uma variável de ambiente:

   DATA='{ "eventType": "detail-page-view", "visitorId": "GA1.3.1260529204.1622654859", "productDetails": [{ "product": { "id": "GGOEGDHB163199" } }, { "product": { "id": "GGOEAAKQ137410" } } ] }'

2. Armazene o URL da API REST para gravar dados de eventos do usuário no seu catálogo usando o método userEvents.write da API Retail em uma variável de ambiente:

   URL="https://retail.googleapis.com/v2/projects/${PROJECT_ID}/locations/global/catalogs/default_catalog/userEvents:write?access_token=${ACCESS_TOKEN}"

   Este é o URL da API REST para gravar dados de eventos do usuário na API Retail. Observe que o URL inclui substituições de variáveis de ambiente do bash para o ID do projeto e o parâmetro em linha do token de acesso chamado access_token. Esse token autentica a solicitação usando a conta de serviço que você gerou anteriormente usando a representação.

3. Faça upload de um evento de usuário usando a API REST com curl:

   curl -H 'Content-Type: application/json' -X POST -d "${DATA}" $URL

   Você usou o curl para chamar o método userEvents:write, transmitindo os dados do evento como um payload de dados JSON na solicitação POST.

   { "eventType": "detail-page-view", "visitorId": "GA1.3.1260529204.1622654859", "eventTime": "2021-06-28T18:39:26.691324Z", "productDetails": [ { "product": { "name": "projects/610724409905/locations/global/catalogs/default_catalog/branches/0/products/GGOEGDHB163199", "id": "GGOEGDHB163199", "type": "PRIMARY", "primaryProductId": "GGOEGDHB163199", "categories": [ "Drinkware" ], "title": "Google Chrome Dino Light Up Water Bottle", "priceInfo": { "currencyCode": "USD", "price": 24 }, "availability": "IN_STOCK", "uri": "https://shop.googlemerchandisestore.com/Google+Redesign/Google+Chrome+Dino+Light+Up+Water+Bottle", "images": [ { "uri": "https://shop.googlemerchandisestore.com/store/20160512512/assets/items/images/GGOEGDHB163199.jpg" } ] } }, { "product": { "name": "projects/610724409905/locations/global/catalogs/default_catalog/branches/0/products/GGOEAAKQ137410", "id": "GGOEAAKQ137410", "type": "PRIMARY", "primaryProductId": "GGOEAAKQ137410", "categories": [ "Apparel" ], "title": "Android Iconic Sock", "priceInfo": { "currencyCode": "USD", "price": 17 }, "availability": "IN_STOCK", "uri": "https://shop.googlemerchandisestore.com/Google+Redesign/Apparel/Android+Iconic+Sock", "images": [ { "uri": "https://shop.googlemerchandisestore.com/store/20160512512/assets/items/images/GGOEAAKQ137410.jpg" } ] } } ] }

Isso vai mostrar os dados formatados na resposta se o upload for bem-sucedido, incluindo os dados do produto associados, como o URL e a imagem do produto, bem como o carimbo de data/hora do evento. Caso contrário, um erro será exibido. Os erros mais comuns estão relacionados a um payload ou URL malformado ou a um token inválido.

Parabéns!

Você importou o catálogo de produtos e os dados de eventos do usuário da API Retail usando várias técnicas, analisou alguns erros comuns de ingestão de dados e examinou os dados de catálogo e eventos da API Retail usando o console do Cloud e a API Retail.

Finalize o laboratório

Clique em Terminar o laboratório após a conclusão. O Google Cloud Ensina remove os recursos usados e limpa a conta por você.

Você vai poder avaliar sua experiência no laboratório. Basta selecionar o número de estrelas, digitar um comentário e clicar em Enviar.

O número de estrelas indica o seguinte:

• 1 estrela = muito insatisfeito
• 2 estrelas = insatisfeito
• 3 estrelas = neutro
• 4 estrelas = satisfeito
• 5 estrelas = muito satisfeito

Feche a caixa de diálogo se não quiser enviar feedback.

Para enviar seu feedback, fazer sugestões ou correções, use a guia Suporte.

Copyright 2026 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de empresas e produtos podem ser marcas registradas das empresas a que estão associados.