Importe informações do catálogo

Esta página descreve como importar as informações do catálogo e mantê-las atualizadas.

Os procedimentos de importação nesta página aplicam-se às recomendações e à pesquisa. Depois de importar dados, ambos os serviços podem usar esses dados, pelo que não precisa de importar os mesmos dados duas vezes se usar ambos os serviços.

Pode importar os dados dos produtos do BigQuery ou especificar os dados incorporados no pedido. Cada um destes procedimentos é uma importação única, com exceção da associação do Merchant Center. Agende importações regulares do catálogo (idealmente, diárias) para verificar se o catálogo está atualizado.

Consulte o artigo Mantenha o seu catálogo atualizado.

Também pode importar itens de produtos individuais. Para mais informações, consulte o artigo Carregue um produto.

Antes de começar

Antes de começar a importar o seu catálogo, tem de:

1. Configure o seu projeto.
2. Crie uma conta de serviço.
3. Adicione a conta de serviço ao seu ambiente local.

Consulte os pré-requisitos de configuração para mais informações.

Considerações sobre a importação de catálogos

Esta secção descreve os métodos que podem ser usados para a importação em lote dos seus dados do catálogo, quando pode usar cada método e algumas das respetivas limitações.

Tutoriais

Esta secção explora diferentes métodos de importação de catálogos com tutoriais em vídeo e de estrutura.

Tutorial de vídeo

Veja este vídeo para saber como importar um catálogo através da API Retail.

Tutorial de importação do catálogo a partir do BigQuery

Este tutorial mostra como usar uma tabela do BigQuery para importar grandes quantidades de dados do catálogo sem limites.

Para seguir orientações passo a passo para esta tarefa diretamente no editor do Cloud Shell, clique em Orientar-me:

Visita guiada

Tutorial de importação do catálogo a partir do Cloud Storage

Este tutorial mostra como importar um grande número de artigos para um catálogo.

Para seguir orientações passo a passo para esta tarefa diretamente no editor do Cloud Shell, clique em Orientar-me:

Visita guiada

Tutorial inline sobre a importação de dados do catálogo

Este tutorial mostra como importar produtos para um catálogo inline.

Para seguir orientações passo a passo para esta tarefa diretamente no editor do Cloud Shell, clique em Orientar-me:

Visita guiada

Práticas recomendadas para a importação de catálogos

São necessários dados de alta qualidade para gerar resultados de alta qualidade. Se os seus dados tiverem campos em falta ou valores de marcadores de posição em vez de valores reais, a qualidade das suas previsões e resultados da pesquisa é afetada.

Quando importa dados do catálogo, certifique-se de que implementa as seguintes práticas recomendadas:

• Certifique-se de que distingue cuidadosamente os produtos principais dos produtos variantes. Antes de carregar dados, consulte os níveis de produtos.

  • Alterar a configuração ao nível do produto depois de despender um esforço significativo na importação de dados. Os artigos principais, e não as variantes, são devolvidos como resultados da pesquisa ou recomendações.

  • Exemplo: se o grupo de SKU principal for Camisola com decote em V,o modelo de recomendação devolve uma camisola com decote em V e, talvez, camisolas com decote redondo e em U. No entanto, se não forem usadas variantes e cada SKU for principal, todas as combinações de cores ou tamanhos da camisa de decote em V são devolvidas como um artigo distinto no painel de recomendações: camisa de decote em V castanha, tamanho XL, camisa de decote em V castanha, tamanho L,até camisa de decote em V branca, tamanho M, camisa de decote em V branca, tamanho S.

  • As coleções podem ser reconhecidas em conjunto, desde que os IDs das variantes sejam incluídos juntamente com os IDs dos produtos principais em collectionMemberIds[]. Isto faz com que uma coleção de produtos, da qual um utilizador pode ter comprado um ou mais produtos no conjunto, seja captada no evento do utilizador, creditando todo o conjunto à compra. Isto facilita a publicação de outros produtos ao mesmo utilizador numa determinada coleção numa consulta relacionada futura.

  • Exemplo: um utilizador comprou anteriormente uma capa de edredão, pelo que são devolvidos produtos correspondentes numa coleção de lençóis, como fronhas.

• Respeite os limites de importação de artigos de produtos.

  • Para a importação em massa a partir do Cloud Storage, o tamanho de cada ficheiro tem de ser 2 GB ou inferior. Pode incluir até 100 ficheiros de cada vez num único pedido de importação em massa.

  • Para a importação inline, importe no máximo 5000 itens de produtos de cada vez.

• Certifique-se de que as informações obrigatórias do catálogo estão incluídas e corretas. Não use valores de marcadores de posição.

• Inclua o máximo de informações opcionais do catálogo possível.

• Certifique-se de que todos os seus eventos usam uma única moeda, especialmente se planeia usar a Google Cloud consola para obter métricas de receita. A API Vertex AI Search for commerce não suporta a utilização de várias moedas por catálogo.

• Mantenha o seu catálogo atualizado, idealmente todos os dias. O agendamento de importações periódicas do catálogo evita que a qualidade do modelo diminua ao longo do tempo. Pode agendar importações automáticas e recorrentes quando importa o catálogo através da consola de comércio do Search. Em alternativa, pode usar o Google Cloud Scheduler para automatizar as importações.

• Não registar eventos de utilizador para itens de produtos que ainda não foram importados.

• Depois de importar as informações do catálogo, reveja as informações de registo e relatórios de erros do seu projeto. Se encontrar mais do que alguns erros, reveja-os e corrija os problemas do processo que originaram os erros.

O pipeline de carregamento de dados do Vertex AI Search for commerce abrange o catálogo de produtos e os dados de eventos do utilizador. Este fluxo de dados fornece a base para uma preparação de modelos robusta e uma avaliação contínua através de mecanismos de feedback. A carregamento de dados precisos e completos não é apenas um pré-requisito, mas sim um processo contínuo essencial para manter a capacidade de adaptação dos modelos subjacentes. Isto, por sua vez, influencia diretamente a qualidade e a relevância dos resultados da pesquisa, oferecendo retornos significativos sobre o investimento.

Tenha em conta estas práticas recomendadas de carregamento de dados ao arquitetar a sua solução de pesquisa de comércio.

Importação em massa, streaming em tempo real ou ambos?

O Vertex AI Search for commerce oferece dois métodos principais para o carregamento do catálogo:

• Importação em massa

• Streaming em tempo real

Esta abordagem dupla satisfaz as diversas necessidades de arquitetura de vários backends de clientes. Não existe qualquer requisito para escolher exclusivamente um método. Pode usar um modo de ingestão híbrido, usando a importação em massa e as atualizações de streaming com base em requisitos específicos.

As importações em massa são ideais quando lida com adições, eliminações ou atualizações em grande escala de milhares de produtos de uma só vez. Por outro lado, o streaming em tempo real é excelente quando são necessárias atualizações contínuas para um volume relativamente menor de produtos. A escolha entre estes métodos depende da natureza do seu catálogo de produtos, da frequência das atualizações e da arquitetura geral dos seus sistemas de back-end.

A funcionalidade de importação em massa suporta três origens de dados distintas:

• BigQuery: o BigQuery facilita a modificação rápida dos dados do catálogo, permite a especificação de datas de partição durante a importação e permite a transformação eficiente de dados através de consultas SQL.
• Google Cloud Storage: o Cloud Storage requer a conformidade com formatos específicos, como JSON, e restrições de ficheiros. Os utilizadores são responsáveis pela gestão das estruturas de contentores, da divisão de ficheiros em partes e de outros aspetos do processo de importação. Além disso, a edição direta do catálogo no Cloud Storage pode ser difícil e, embora potencialmente rentável, não tem a flexibilidade de outros métodos.
• Dados inline: para catálogos extensos, as importações inline podem não ser a opção mais escalável devido às limitações de tamanho. Reserve a sua utilização para atualizações menores ou testes experimentais.

Para cenários que envolvem um volume elevado de atualizações do catálogo de produtos (milhares de alterações, adições ou eliminações de produtos) num curto período e a intervalos regulares, uma abordagem combinada de importações em massa e streaming em tempo real pode ser altamente eficaz. Prepare as atualizações no BigQuery ou no Cloud Storage e faça importações em massa incrementais a intervalos regulares, como a cada hora ou duas horas. Este método gere de forma eficiente as atualizações em grande escala, ao mesmo tempo que minimiza as interrupções.

Para atualizações mais pequenas e menos frequentes ou que exijam uma reflexão imediata no catálogo, use a API de streaming em tempo real. Na abordagem híbrida, o streaming em tempo real pode preencher as lacunas entre as importações em massa, garantindo que o seu catálogo permanece atualizado. Esta estratégia equilibra a realização de chamadas individuais da API REST (para aplicar patches a produtos) e a realização de alterações em massa, otimizando a eficiência e a capacidade de resposta na gestão do catálogo do Vertex AI Search for commerce.

Estratégias de ramificação para a gestão de catálogos

Manter um catálogo unificado numa única filial, em vez de ter catálogos separados em várias filiais. Esta prática simplifica as atualizações do catálogo e reduz o risco de inconsistências durante a mudança de ramificações.

As seguintes estratégias de ramificação comuns são eficazes para a gestão de catálogos.

Atualizações de uma única filial

Designar um ramo em direto como o predefinido e atualizá-lo continuamente à medida que ocorrem alterações no catálogo. Para atualizações em massa, use a funcionalidade de importação durante períodos de tráfego baixo para minimizar as interrupções. Use APIs de streaming para atualizações incrementais mais pequenas ou agrupe-as em blocos maiores para importações regulares.

Comutação de ramos

Existem algumas opções para gerir diferentes ramos:

• Use ramificações para testes e validação:

  • Alguns engenheiros de sites de comércio optam por uma abordagem de comutação de ramificações, em que o catálogo é atualizado numa ramificação não publicada e, em seguida, torna-se a ramificação predefinida (publicada) quando estiver pronto para produção. Isto permite a preparação antecipada do catálogo do dia seguinte. As atualizações podem ser feitas através da importação em massa ou do streaming para o ramo não publicado, o que garante uma transição perfeita durante os períodos de pouco tráfego.
  • A escolha entre estas estratégias depende dos seus requisitos específicos, da frequência de atualização e da configuração da infraestrutura. No entanto, independentemente da estratégia escolhida, a manutenção de um catálogo unificado num único ramo é fundamental para um desempenho ideal e resultados de pesquisa consistentes no Vertex AI Search for commerce.

• Use ramificações para cópias de segurança:

  • Um único ramo publicado foca-se no carregamento e processamento contínuos de atualizações de produtos para manter o índice do Vertex AI Search for commerce atualizado em tempo quase real.
  • Outro ramo centra-se na criação de um instantâneo diário dos dados transformados na pesquisa de retalho, atuando como um mecanismo de alternativa robusto em caso de danos nos dados ou problemas com o ramo 0.
  • Uma terceira ramificação foca-se na criação de uma imagem instantânea semanal da data transformada. Desta forma, o cliente pode ter uma cópia de segurança com um dia e uma cópia de segurança com uma semana em ramos diferentes.

Remova completamente ramificações do catálogo

Se estiver a importar novos dados do catálogo para uma ramificação existente, é importante que a ramificação do catálogo esteja vazia para garantir a integridade dos dados importados para a ramificação. Quando o ramo está vazio, pode importar novos dados do catálogo e associar o ramo a uma conta de comerciante.

Se estiver a publicar tráfego de previsão ou de pesquisa em direto e planear limpar a ramificação predefinida, considere especificar primeiro outra ramificação como predefinida antes de limpar. Uma vez que a ramificação predefinida apresenta resultados vazios após a limpeza, a limpeza de uma ramificação predefinida ativa pode causar uma interrupção.

Para expurgar dados de uma ramificação do catálogo, conclua os seguintes passos:

1. Aceda à página Dados> na consola de pesquisa para comércio.
   
   Aceda à página Dados

2. Selecione uma filial do catálogo no campo Nome da filial.

3. No menu de três pontos junto ao campo Nome da ramificação, escolha Eliminar ramificação.

   É apresentada uma mensagem a avisar que está prestes a eliminar todos os dados na ramificação, bem como todos os atributos criados para a ramificação.

4. Introduza a ramificação e clique em Confirmar para limpar os dados do catálogo da ramificação.

   É iniciada uma operação de longa duração para expurgar dados da ramificação do catálogo. Quando a operação de eliminação estiver concluída, o estado da eliminação é apresentado na lista do catálogo de produtos na janela Estado da atividade.

Atualizações de inventário no Vertex AI Search for commerce

Esta secção descreve como otimizar o desempenho do Vertex AI Search para comércio fazendo atualizações regulares do inventário.

Streaming em tempo real

• Para dados dinâmicos, como informações de inventário (preço, disponibilidade) e detalhes ao nível da loja, incluindo o estado do processamento e os preços específicos da loja, o streaming em tempo real é a única opção no Vertex AI Search for commerce.
• Esta distinção surge devido à natureza de alta frequência das flutuações do inventário em comparação com os dados do catálogo de produtos relativamente estáticos. A disponibilidade dos produtos pode mudar várias vezes por dia, enquanto as descrições ou os atributos permanecem relativamente constantes.
• A frequência das atualizações ao nível da loja aumenta ainda mais com o número de localizações de retalho.

Atualizações assíncronas

• Para se adaptar a este ritmo rápido de mudança, a Pesquisa do Vertex AI para comércio usa atualizações de inventário assíncronas através de APIs que devolvem um ID de tarefa.
• O processo de atualização não é considerado concluído até que o estado da tarefa seja consultado e confirmado, o que pode introduzir um pequeno atraso que varia entre segundos e minutos.

Atualizações fora de ordem

• Uma funcionalidade notável deste sistema é a capacidade de atualizar as informações de inventário antes de o produto correspondente ser carregado no catálogo. Isto resolve o cenário comum em que os pipelines de dados de inventário e de produtos funcionam de forma independente nos retalhistas, o que, por vezes, faz com que as informações de inventário fiquem disponíveis antes da atualização do catálogo de produtos. Quando atualizar o inventário, use a opção allowMissing para processar atualizações do inventário fora de ordem em comparação com o produto.
• Ao permitir que as atualizações de inventário precedam o carregamento do catálogo, a Vertex AI Search for commerce acomoda estas discrepâncias na pipeline, garantindo que os dados de inventário precisos estão disponíveis mesmo para produtos introduzidos recentemente.
• No entanto, as informações de inventário de um produto são retidas durante 24 horas e são eliminadas se não for carregado um produto correspondente nesse período. Este mecanismo garante a consistência dos dados e impede que as informações de inventário desatualizadas persistam no sistema.

Pré-verificações do catálogo de produtos para testes A/B robustos no Vertex AI Search for commerce

Esta secção aborda como executar verificações prévias nos dados do catálogo de produtos.

Garanta a paridade das atualizações consistentes do catálogo

• Em preparação para um teste A/B no Vertex AI Search para comércio, é fundamental manter uma paridade rigorosa entre o catálogo antigo (controlo) e o catálogo do Vertex AI Search para comércio (teste). Quaisquer desequilíbrios entre os dois podem afetar negativamente o teste A/B, o que leva a observações distorcidas e resultados potencialmente inválidos. Por exemplo, as inconsistências na disponibilidade, nos preços ou até mesmo pequenas discrepâncias de atributos dos produtos podem introduzir parcialidades não intencionais nos dados de teste.
• Para mitigar este risco, é imperativo criar um processo de atualização paralelo para os catálogos de controlo e de teste, evitando atualizações sequenciais sempre que possível. O objetivo é maximizar o tempo durante o qual ambos os catálogos estão sincronizados. Por outro lado, as atualizações em série podem introduzir atrasos numa ou noutra faixa. Estes atrasos podem resultar em incompatibilidades temporárias do catálogo, em que um produto pode estar em stock num catálogo, mas não no outro. Em alternativa, um produto adicionado recentemente aparece num catálogo mais cedo do que no outro. Estas disparidades podem influenciar significativamente o comportamento dos utilizadores, os cliques e as compras, o que, em última análise, leva a uma comparação injusta e a resultados incorretos do teste A/B.
• Ao dar prioridade às atualizações paralelas e procurar uma paridade consistente do catálogo, os retalhistas podem garantir condições de concorrência equitativas para os testes A/B na Vertex AI Search for commerce. Esta abordagem permite uma análise imparcial e justa dos resultados do teste, o que leva a estatísticas mais fiáveis e a uma tomada de decisões mais informada.

Alcance a paridade dos dados do catálogo

• A profundidade e a precisão da compreensão dos produtos de um modelo de pesquisa de comércio eletrónico dependem da riqueza e da qualidade das informações do catálogo de produtos subjacente. Quanto mais abrangentes forem os dados dos produtos no catálogo, mais bem equipado está o modelo para compreender e classificar os produtos de forma eficaz.
• Assim, em preparação para os testes A/B, é imperativo garantir que os dados dos produtos carregados para o catálogo antigo (controlo) e para o catálogo do Vertex AI Search for commerce (teste) são idênticos. Quaisquer discrepâncias nas informações dos produtos entre estes dois ambientes podem influenciar significativamente os resultados do teste A/B.
• Por exemplo, se o motor de pesquisa antigo beneficiar de um catálogo mais rico ou mais extenso em comparação com o Vertex AI Search for commerce, isto cria uma vantagem injusta. A falta de informações no catálogo do Vertex AI Search para comércio pode ser fundamental para a compreensão e a classificação dos produtos, o que pode levar a resultados de pesquisa imprecisos e a comparações de desempenho enganadoras. A deteção destas disparidades pode ser difícil com ferramentas externas e requer frequentemente uma inspeção manual meticulosa de ambos os catálogos.
• Ao garantir diligentemente que ambos os catálogos contêm os mesmos dados dos produtos com o mesmo nível de detalhe, os retalhistas podem criar condições de concorrência equitativas para os testes A/B no Vertex AI Search for commerce. Esta abordagem promove uma comparação justa e imparcial dos dois motores de pesquisa, facilitando a avaliação precisa do respetivo desempenho e capacidades.

Planeamento de recuperação de desastres

Um plano de recuperação de desastres bem preparado garante que as suas capacidades de pesquisa de comércio permanecem operacionais e eficazes, minimizando o impacto na experiência do cliente e na geração de receita. Este plano deve permitir o restauro rápido do catálogo para resolver a potencial falha dos pipelines de carregamento de eventos de utilizadores e do catálogo, independentemente da causa subjacente.

A utilização do BigQuery para a preparação de dados oferece uma vantagem distinta na recuperação de desastres. Se o catálogo atual ou os dados de eventos do utilizador na Vertex AI Search for commerce não forem significativamente diferentes da imagem instantânea mais recente armazenada no BigQuery, a chamada da API Import pode iniciar um restauro rápido. Esta abordagem minimiza o tempo de inatividade e garante que a funcionalidade de pesquisa permanece operacional.

Por outro lado, se o BigQuery não estiver integrado no seu pipeline de dados, têm de existir mecanismos alternativos para recarregar rapidamente o catálogo a partir de um estado bom conhecido. Estes mecanismos podem envolver sistemas de cópia de segurança, replicação de dados ou outras estratégias de comutação por falha.

Ao incorporar estas considerações de recuperação de desastres na sua arquitetura do Vertex AI Search for commerce, pode reforçar a robustez do sistema e manter a continuidade da empresa, mesmo perante interrupções inesperadas.

Planeie a alta disponibilidade

Quando carrega o catálogo de produtos para o Vertex AI Search, é importante considerar como os diferentes Google Cloud serviços processam a regionalidade para criar um pipeline de carregamento de dados resiliente.

Para criar um pipeline de carregamento capaz de recuperação de desastres com o Dataflow, implemente os seus trabalhos em várias regiões através de um dos seguintes designs:

• Ativo/ativo: as instâncias do Dataflow em várias regiões processam ativamente os dados em simultâneo.
• Ativo/passivo: uma instância do Dataflow numa região está ativa, enquanto as instâncias noutras regiões permanecem em modo de espera.

Veja como implementar estes designs com o Pub/Sub e o Dataflow:

• Serviços globais: alguns serviços, como o Pub/Sub, funcionam a nível global. Google Cloud gere a respetiva disponibilidade de acordo com os respetivos contratos de nível de serviço (SLAs) específicos.
• Serviços regionais: outros serviços, como o Dataflow, que pode usar para transformar e carregar dados no Vertex AI Search, são regionais. É responsável por configurar estes componentes para alta disponibilidade e recuperação de desastres.

Por exemplo, quando usa o BigQuery para persistir dados, pode configurá-lo para ser multirregional, de modo que a redundância e a disponibilidade dos dados sejam processadas automaticamente pelo Google Cloud. Da mesma forma, quando usa o armazenamento na nuvem, este pode ser configurado para ser multirregional.

Design ativo/ativo

O design ativo/ativo usa atributos de mensagens do Pub/Sub e filtros de subscrição para garantir que cada mensagem é processada exatamente uma vez por uma tarefa do Dataflow ativa numa região específica.

1. Adicione atributos de mensagens: quando publicar mensagens no tópico do Pub/Sub, como atualizações de produtos, inclua um atributo que indique a região de destino. Por exemplo:

   • region: us-central1
   • region: us-east1

2. Configure filtros de subscrição: para cada pipeline do Dataflow regional, configure a respetiva subscrição do Pub/Sub para extrair apenas mensagens correspondentes à respetiva região através de filtros de mensagens. Por exemplo, a subscrição da tarefa do us-central1 Dataflow teria um filtro como attributes.region = "us-central1".

3. Failover: se uma região ficar indisponível, atualize o seu sistema de publicação a montante para etiquetar todas as novas mensagens com um atributo para uma região em bom estado. Isto redireciona o processamento de mensagens para a instância do Dataflow na região de alternativa.

Vários componentes usados na arquitetura podem ser configurados para serem multirregionais por predefinição. Por exemplo, quando usa o BigQuery para persistir dados, pode configurá-lo como multirregional para que a redundância e a disponibilidade dos dados sejam processadas automaticamente pelo Cloud Storage. Da mesma forma, quando usa o Cloud Storage, pode configurá-lo como multirregional.

Design ativo/passivo

Este design envolve ter apenas um pipeline do Dataflow regional a extrair ativamente mensagens do Pub/Sub em qualquer altura.

1. Anexe uma subscrição: certifique-se de que apenas a subscrição do Pub/Sub para a tarefa do Dataflow da região ativa está anexada e a receber mensagens. As subscrições para tarefas do Dataflow em regiões passivas devem ser criadas, mas permanecer separadas.

2. Failover: se a região ativa sofrer uma falha, manual ou programaticamente:

   • Desassocie a subscrição do Pub/Sub associada à tarefa do Dataflow da região com falhas.
   • Anexe a subscrição do Pub/Sub associada a uma tarefa do Dataflow numa das regiões passivas (em espera).

Isto transfere a carga de processamento de mensagens para a região recém-ativada.

Resiliência e análise forense

A utilização do BigQuery na conceção do carregamento de dados pode resultar no processamento da resiliência e na criação de capacidade para análise forense e depuração. Os produtos e o inventário carregados diretamente com a API patch e addLocalInventory implicam que, quando os dados são enviados para o Vertex AI Search for commerce, não fica nenhum rasto da atualização do produto e do inventário. O utilizador pode querer saber por que motivo um produto não está a ser apresentado como esperado. Ter uma área de preparação criada com o BigQuery com um histórico completo de dados facilita este tipo de investigação e depuração.

Arquitetura de referência

Nesta arquitetura, o carregamento de dados teria normalmente fases não processadas, preparadas e de consumo, todas criadas no BigQuery. O sistema moveria os dados entre as fases através do Dataflow e orquestraria a automatização de tudo isto através de fluxos de trabalho na nuvem:

• O sistema aceita os dados não processados tal como estão e adiciona-lhes uma indicação de tempo para manter o histórico. Estes dados permanecem inalterados, pelo que os clientes os considerariam uma origem verdadeira.
• Em seguida, o sistema transformaria os dados numa fase organizada e atribuiria-lhes novamente uma data/hora. Desta forma, os clientes sabem quando a transformação ocorreu e se algo falhou.
• Por fim, o sistema criaria visualizações na fase de consumo dos dados organizados usando a hora em que o sistema etiquetou os dados anteriormente. Desta forma, o cliente sabe exatamente que dados transformados devem ser finalmente carregados no Vertex AI Search for commerce.

O ramo 0, o ramo 1 e o ramo 2 servem como cópia de segurança em direto, com um dia e com uma semana, respetivamente. Os dados carregados diretamente no ramo 0 são agregados e indexados no ramo 1 diariamente e no ramo 2 semanalmente. Desta forma, qualquer dano nos dados pode ser revertido, o que melhora a continuidade do negócio e a resiliência do sistema.

Além disso, é possível realizar análises e depurações, uma vez que todo o histórico e a linhagem dos dados são mantidos em conjuntos de dados globais do BigQuery.

Planeie casos extremos com o carregamento de catálogos

Assim que os mecanismos principais para o carregamento do catálogo no Vertex AI Search para comércio estiverem estabelecidos, uma abordagem proativa envolve a avaliação da respetiva resiliência em relação a vários casos extremos. Embora alguns destes cenários possam não ser imediatamente relevantes para os requisitos específicos da sua empresa, a sua incorporação no design de back-end pode oferecer uma preparação valiosa para o futuro.

Este passo preparatório implica rever a capacidade do pipeline de dados para processar cenários inesperados ou extremos, garantindo a sua robustez e adaptabilidade às exigências em evolução. Ao antecipar potenciais desafios e resolvê-los proativamente, pode mitigar futuras interrupções e manter o fluxo contínuo de dados dos produtos no seu sistema de pesquisa de retalho.

Para o conseguir, a lógica do Dataflow deve ser criada de forma a:

• Valida cada item dos dados não processados para corresponder a um esquema adequado. O contrato dos dados não processados deve ser determinado antecipadamente e cada elemento de dados deve ser sempre comparado com o contrato. Em caso de falha na validação, o elemento de dados não processados deve ser etiquetado com a data/hora e persistido nas tabelas de dados não processados com falhas do BigQuery com erros reais destinados a análises detalhadas.

  Seguem-se alguns exemplos de falhas:

  • Um determinado atributo que não faz parte do contrato aparece subitamente no elemento de dados não processados.
  • Um determinado atributo obrigatório não está presente no elemento de dados não processados.

• Valida cada item dos dados não processados para transformação no formato do Vertex AI Search para comércio. Existem alguns campos obrigatórios exigidos pelo Vertex AI Search for commerce para o carregamento de produtos. Todos os elementos dos dados não processados devem ser verificados novamente para ver se podem ser transformados com êxito no formato de esquema do Vertex AI Search for commerce. Em caso de falha da transformação, o elemento de dados não processados deve ser etiquetado com a hora e persistir nas tabelas organizadas com falhas do BigQuery com mensagens de erro reais que podem ajudar na análise forense.

  Seguem-se alguns exemplos de falhas:

  • Não é possível formatar um determinado atributo, como o preço, num número, porque o elemento de dados não processados tem-no como alfanumérico.
  • O nome do produto está completamente em falta.

Este exemplo mostra um esquema de tabela do BigQuery de exemplo para persistir todas as falhas para depuração:

[
    {
      "mode": "REQUIRED",
      "name": "ingestedTimestamp",
      "type": "TIMESTAMP"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadString",
      "type": "STRING"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadBytes",
      "type": "BYTES"
    },
    {
      "fields": [
        {
          "mode": "NULLABLE",
          "name": "key",
          "type": "STRING"
        },
        {
          "mode": "NULLABLE",
          "name": "value",
          "type": "STRING"
        }
      ],
      "mode": "REPEATED",
      "name": "attributes",
      "type": "RECORD"
    },
    {
      "mode": "NULLABLE",
      "name": "errorMessage",
      "type": "STRING"
    },
    {
      "mode": "NULLABLE",
      "name": "stacktrace",
      "type": "STRING"
    }
  ]

Testes de esforço e escalabilidade

Prepare-se para eventos de grande volume e crescimento com testes de esforço e escalabilidade.

Eventos com muito trânsito

Os eventos com tráfego elevado, como as festividades, representam um desafio significativo para os pipelines de carregamento de dados. O aumento das atualizações de inventário, incluindo os níveis de stock e os preços, e as potenciais alterações aos atributos dos produtos exigem uma infraestrutura robusta. É importante avaliar se o seu sistema de carregamento consegue processar este aumento da carga. Os testes de carga simulados, que replicam os padrões de tráfego de pico, identificam gargalos e garantem um funcionamento sem problemas durante estes períodos críticos.

Vendas flash

As vendas relâmpago apresentam um desafio único devido à sua curta duração e às rápidas flutuações de inventário. Garantir a sincronização do inventário em tempo real é fundamental para evitar discrepâncias entre os resultados da pesquisa e a disponibilidade real. Se não o fizer, pode originar experiências negativas para os clientes, como produtos populares aparecerem como disponíveis quando, na verdade, estão esgotados, ou vice-versa. Além disso, as alterações de preços durante as vendas relâmpago podem afetar significativamente a classificação dos produtos, o que realça a necessidade de atualizações de preços precisas e oportunas no índice de pesquisa.

Expansão do catálogo

O crescimento da empresa ou as expansões da linha de produtos podem resultar num aumento drástico, como 5 ou 10 vezes, no número de produtos no seu catálogo. A sua arquitetura de carregamento tem de ser escalável para acomodar este crescimento de forma integrada. Isto pode exigir a revisão de todo o pipeline de ETL (extração, transformação e carregamento), especialmente se forem introduzidas novas origens de dados ou formatos de informações dos produtos.

Ao abordar proativamente estes potenciais cenários, pode garantir que o pipeline de carregamento do Vertex AI Search for commerce permanece robusto, escalável e reativo, mesmo perante picos de tráfego repentinos, vendas relâmpago ou um crescimento significativo do catálogo. Esta abordagem proativa salvaguarda a precisão e a fiabilidade dos seus resultados da pesquisa, contribuindo para uma experiência do utilizador positiva e impulsionando o sucesso da empresa.

O desempenho do pipeline de carregamento de dados deve ser avaliado e deve ser criada uma base de referência para as seguintes métricas:

1. Quanto tempo demora a publicar e carregar todos os dados do catálogo e do inventário? Isto pode ser necessário numa base ad hoc durante a BFCM, quando os preços podem mudar significativamente para todo o catálogo.
2. Quanto tempo demora a refletir-se uma única atualização de produto?
3. Qual é a taxa mais elevada de atualizações de produtos e inventário que o sistema pode processar?

Restrições

• Avalie e descubra se os pipelines conseguem aumentar e diminuir a escala corretamente.
• Determine se o limite máximo para o número de instâncias é demasiado elevado ou demasiado baixo.
• Determine se o sistema está a ser limitado pela taxa do Vertex AI Search for commerce verificando o código HTTP 429.
• Confirme se é necessário aumentar determinadas quotas da API para reduzir os limites de taxa.

Estrutura dos dados dos produtos para o carregamento do catálogo

Esta secção descreve como preparar os dados dos produtos para o carregamento do catálogo.

Produtos principais

Os produtos principais funcionam como contentores para agrupar produtos variantes e como entradas na grelha de pesquisa. Ter apenas atributos comuns partilhados entre as variantes especificadas para os produtos principais. Por exemplo:

• ID do produto principal
• ID do produto (idêntico ao ID do produto principal)
• Título
• Descrição

Consulte o artigo Acerca dos atributos dos produtos para mais informações.

Produtos variantes

Os produtos variantes herdam atributos comuns do produto principal, mas também podem especificar valores únicos.

Os atributos obrigatórios incluem:

• Todos os atributos especificados para produtos principais (título, descrição). O preço, o título e a descrição podem ser diferentes do produto principal.
• Atributos específicos da variante (cor, tamanho e outras variações relevantes do produto).

Consulte o artigo Acerca dos atributos dos produtos para mais informações.

Obtenção de atributos

O processo de obtenção considera todos os atributos pesquisáveis para produtos principais e variantes.

Pontuação de relevância

A classificação de relevância baseia-se apenas nos campos do título e da descrição. Para salvaguardar a diferenciação adequada, modifique ligeiramente os títulos das variantes dos produtos principais (por exemplo, Nome do produto + Cor).

Correspondência de variantes nos resultados da pesquisa

A correspondência de variantes (por exemplo, vestido azul) filtra os resultados com base em atributos de variantes predefinidos, como a cor e o tamanho. Os resultados da pesquisa devolvem até cinco variantes correspondentes para cada produto principal.

Sincronize o Merchant Center com o Vertex AI Search para comércio

O Merchant Center é uma ferramenta que pode usar para disponibilizar os dados da sua loja e produtos para anúncios do Shopping e outros serviços Google.

Para uma sincronização contínua entre o Merchant Center e o Vertex AI Search para comércio, pode associar a sua conta do Merchant Center ao Vertex AI Search para comércio.

Quando configura uma sincronização do Merchant Center para o Vertex AI Search for commerce, tem de ter a função de IAM Administrador atribuída no Merchant Center. Embora uma função de acesso padrão lhe permita ler os feeds do Merchant Center, quando tenta sincronizar o Merchant Center com o Vertex AI Search para comércio, recebe uma mensagem de erro. Assim, antes de poder sincronizar com êxito o Merchant Center com o Vertex AI Search para comércio, atualize a sua função.

Associe a sua conta do Merchant Center

Enquanto o Vertex AI Search para comércio estiver associado à conta do Merchant Center, as alterações aos dados dos produtos na conta do Merchant Center são atualizadas automaticamente em minutos no Vertex AI Search para comércio. Se quiser impedir que as alterações do Merchant Center sejam sincronizadas com a Vertex AI Search for commerce, pode desassociar a sua conta do Merchant Center.

Desassociar a sua conta do Merchant Center não elimina os produtos na Pesquisa da Vertex AI para comércio. Para eliminar produtos importados, consulte o artigo Elimine informações sobre produtos.

Para sincronizar a sua conta do Merchant Center, conclua os passos seguintes.

Sincronize a sua conta do Merchant Center

Para ver o Merchant Center associado, aceda à página Dados da consola de comércio da Pesquisa e clique no botão Merchant Center na parte superior direita da página. É apresentado o painel Contas do Merchant Center associadas. Também pode adicionar contas do Merchant Center adicionais a partir deste painel.

Consulte o artigo Veja informações agregadas sobre o seu catálogo para ver instruções sobre como ver os produtos que foram importados.

Apresente as associações da sua conta do Merchant Center

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

Desassocie a sua conta do Merchant Center

A desassociação da sua conta do Merchant Center impede que essa conta sincronize os dados do catálogo com a Vertex AI Search for commerce. Este procedimento não elimina produtos no Vertex AI Search for commerce que já tenham sido carregados.

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

Limitações na associação ao Merchant Center

• Uma conta do Merchant Center pode ser associada a qualquer número de ramificações do catálogo, mas uma única ramificação do catálogo só pode ser associada a uma conta do Merchant Center.

• Uma conta do Merchant Center não pode ser uma conta multicliente (MCA). No entanto, pode associar subcontas individuais.

• A primeira importação após a associação da sua conta do Merchant Center pode demorar horas a concluir. O período depende do número de ofertas na conta do Merchant Center.

• Todas as modificações de produtos que usam métodos de API estão desativadas para filiais associadas a uma conta do Merchant Center. Quaisquer alterações aos dados do catálogo de produtos nessas filiais têm de ser feitas através do Merchant Center. Depois, essas alterações são sincronizadas automaticamente com o Vertex AI Search for commerce.

• O tipo de produto de coleção não é suportado para estabelecimentos que usam a associação do Merchant Center.

• A sua conta do Merchant Center só pode ser associada a ramificações do catálogo vazias para garantir a precisão dos dados. Para eliminar produtos de um ramo do catálogo, consulte o artigo Elimine informações sobre produtos.

Importe dados do catálogo do BigQuery

Para importar dados do catálogo no formato correto a partir do BigQuery, use o esquema do Vertex AI Search for commerce para criar uma tabela do BigQuery com o formato correto e carregar a tabela vazia com os dados do catálogo. Em seguida, carregue os seus dados para o Vertex AI Search para comércio.

Para mais ajuda com as tabelas do BigQuery, consulte o artigo Introdução às tabelas. Para obter ajuda com as consultas do BigQuery, consulte o artigo Vista geral da consulta de dados do BigQuery.

Para seguir orientações passo a passo para esta tarefa diretamente no editor do Cloud Shell, clique em Orientar-me:

Visita guiada

Para importar o catálogo:

1. Se o seu conjunto de dados do BigQuery estiver noutro projeto, configure as autorizações necessárias para que a Pesquisa Vertex AI para comércio possa aceder ao conjunto de dados do BigQuery. Saiba mais.

2. Importe os dados do catálogo para o Vertex AI Search for commerce.

   Cloud Console

   1. Aceda à página Dados> na consola de pesquisa para comércio.
      
      Aceda à página Dados
   2. Clique em Importar para abrir o painel Importar dados.
   3. Escolha Catálogo de produtos.
   4. Selecione BigQuery como origem de dados.
   5. Selecione a filial para a qual vai carregar o catálogo.
   6. Escolha Esquema de catálogos de produtos de retalho. Este é o esquema de produtos para o Vertex AI Search for commerce.
   7. Introduza a tabela do BigQuery onde os seus dados se encontram.
   8. Opcional: em Mostrar opções avançadas, introduza a localização de um contentor do Cloud Storage no seu projeto como uma localização temporária para os seus dados.
      
      Se não for especificado, é usada uma localização predefinida. Se especificado, o BigQuery e o contentor do Cloud Storage têm de estar na mesma região.
   9. Se não tiver a pesquisa ativada e estiver a usar o esquema do Merchant Center, selecione o nível do produto.
      
      Tem de selecionar o nível do produto se esta for a primeira vez que importa o catálogo ou se estiver a reimportar o catálogo depois de o limpar. Saiba mais acerca dos níveis dos produtos. Alterar os níveis dos produtos depois de importar dados requer um esforço significativo.
      
      Importante: não pode ativar a pesquisa de projetos com um catálogo de produtos que tenha sido carregado como variantes.
   10. Clique em Importar.

   curl

   1. Se estiver a carregar o catálogo pela primeira vez ou a reimportá-lo depois de o limpar, defina os níveis dos produtos através do método Catalog.patch. Esta operação requer a função de administrador de retalho.

      • ingestionProductType: suporta os valores primary (predefinição) e variant.
      • merchantCenterProductIdField: suporta os valores offerId e itemGroupId. Se não usar o Merchant Center, não precisa de definir este campo.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Crie um ficheiro de dados para os parâmetros de entrada da importação.

      Use o objeto BigQuerySource para apontar para o seu conjunto de dados do BigQuery.

      • DATASET_ID: O ID do conjunto de dados do BigQuery.
      • TABLE_ID: o ID da tabela do BigQuery que contém os seus dados.
      • PROJECT_ID: o ID do projeto em que se encontra a origem do BigQuery. Se não for especificado, o ID do projeto é herdado do pedido principal.
      • STAGING_DIRECTORY: opcional. Um diretório do Cloud Storage usado como uma localização provisória para os seus dados antes de serem importados para o BigQuery. Deixe este campo vazio para criar automaticamente um diretório temporário (recomendado).
      • ERROR_DIRECTORY: opcional. Um diretório do Cloud Storage para informações de erros sobre a importação. Deixe este campo vazio para criar automaticamente um diretório temporário (recomendado).
      • dataSchema: para a propriedade dataSchema, use o valor product (predefinição). Vai usar o esquema do Vertex AI Search para comércio.

      Recomendamos que não especifique diretórios de preparação nem de erros. Desta forma, é possível criar automaticamente um contentor do Cloud Storage com novos diretórios de preparação e de erros. Estes diretórios são criados na mesma região que o conjunto de dados do BigQuery e são exclusivos de cada importação (o que impede que várias tarefas de importação organizem dados no mesmo diretório e, potencialmente, reimportem os mesmos dados). Após três dias, o contentor e os diretórios são eliminados automaticamente para reduzir os custos de armazenamento.

      Um nome de contentor criado automaticamente inclui o ID do projeto, a região do contentor e o nome do esquema de dados, separados por carateres de sublinhado (por exemplo, 4321_us_catalog_retail). Os diretórios criados automaticamente são denominados staging ou errors, com um número anexado (por exemplo, staging2345 ou errors5678).

      Se especificar diretórios, o contentor do Cloud Storage tem de estar na mesma região que o conjunto de dados do BigQuery, caso contrário, a importação falha. Indique os diretórios de preparação e de erros no formato gs://<bucket>/<folder>/. Estes devem ser diferentes.

      {
         "inputConfig":{
           "bigQuerySource": {
             "projectId":"PROJECT_ID",
             "datasetId":"DATASET_ID",
             "tableId":"TABLE_ID",
             "dataSchema":"product"}
            }
      }

   3. Importe as informações do catálogo fazendo um pedido POST ao método REST Products:import, indicando o nome do ficheiro de dados (aqui, apresentado como input.json).

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

      Pode verificar o estado de forma programática através da API. Deve receber um objeto de resposta com um aspeto semelhante ao seguinte:

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }

      O campo name é o ID do objeto de operação. Para pedir o estado deste objeto, substitua o campo name pelo valor devolvido pelo método import até que o campo done seja devolvido como true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456"

      Quando a operação estiver concluída, o objeto devolvido tem um valor de donetrue e inclui um objeto de estado semelhante ao seguinte exemplo:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      Pode inspecionar os ficheiros no diretório de erros no Cloud Storage para ver se ocorreram erros durante a importação.

Configure o acesso ao seu conjunto de dados do BigQuery

Para configurar o acesso quando o seu conjunto de dados do BigQuery estiver num projeto diferente do seu serviço Vertex AI Search for commerce, conclua os seguintes passos.

1. Abra a página IAM na Google Cloud consola.

   Abra a página do IAM

2. Selecione o seu projeto do Vertex AI Search para comércio.

3. Encontre a conta de serviço com o nome Conta de serviço de retalho.

   Se não tiver iniciado anteriormente uma operação de importação, esta conta de serviço pode não ser apresentada. Se não vir esta conta de serviço, regresse à tarefa de importação e inicie a importação. Quando falha devido a erros de autorização, regresse aqui e conclua esta tarefa.

4. Copie o identificador da conta de serviço, que se assemelha a um endereço de email (por exemplo, service-525@gcp-sa-retail.iam.gserviceaccount.com).

5. Mude para o seu projeto do BigQuery (na mesma página IAM e administração) e clique em person_add Conceder acesso.

6. Para Novos responsáveis, introduza o identificador da conta de serviço do Vertex AI Search for commerce e selecione a função BigQuery > Utilizador do BigQuery.

7. Clique em Adicionar outra função e selecione BigQuery > Editor de dados do BigQuery.

   Se não quiser atribuir a função de editor de dados a todo o projeto, pode adicioná-la diretamente ao conjunto de dados. Saiba mais.

8. Clique em Guardar.

Esquema de produto

Quando importar um catálogo do BigQuery, use o seguinte esquema de produtos do Vertex AI Search for commerce para criar uma tabela do BigQuery com o formato correto e carregá-la com os dados do catálogo. Em seguida, importe o catálogo.

[
  {
    "name": "name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "id",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "type",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "primaryProductId",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "collectionMemberIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "gtin",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "categories",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "title",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "brands",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "description",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "languageCode",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "key",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "value",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          },
          {
            "name": "numbers",
            "type": "FLOAT",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "tags",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "priceInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "currencyCode",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "price",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "originalPrice",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "cost",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "priceEffectiveTime",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "priceExpireTime",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "rating",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "ratingCount",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "averageRating",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "ratingHistogram",
        "type": "INTEGER",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "expireTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "ttl",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "seconds",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "availableTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availability",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availableQuantity",
    "type": "INTEGER",
    "mode": "NULLABLE"
  },
  {
    "name": "fulfillmentInfo",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "type",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "placeIds",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "uri",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "images",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "uri",
        "type": "STRING",
        "mode": "REQUIRED"
      },
      {
        "name": "height",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "width",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "audience",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "genders",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "ageGroups",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "colorInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "colorFamilies",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "colors",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "sizes",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "materials",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "patterns",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "conditions",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "publishTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "promotions",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "promotionId",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

Importe dados do catálogo a partir do Cloud Storage

Para importar dados do catálogo no formato JSON, crie um ou mais ficheiros JSON que contenham os dados do catálogo que quer importar e carregue-os para o Cloud Storage. A partir daí, pode importá-lo para o Vertex AI Search for commerce.

Para ver um exemplo do formato de artigo do produto JSON, consulte o formato de dados JSON do artigo do produto.

Para obter ajuda com o carregamento de ficheiros para o Cloud Storage, consulte o artigo Carregue objetos.

1. Certifique-se de que a conta de serviço do Vertex AI Search para comércio tem autorização para ler e escrever no contentor.

   A conta de serviço do Vertex AI Search for commerce é apresentada na página IAM na Google Cloud consola com o nome Conta de serviço de retalho. Use o identificador da conta de serviço, que se assemelha a um endereço de email (por exemplo, service-525@gcp-sa-retail.iam.gserviceaccount.com), quando adicionar a conta às autorizações do seu contentor.

2. Importe os dados do catálogo.

   Cloud Console

   1. Aceda à página Dados> na consola de pesquisa para comércio.
      
      Aceda à página Dados
   2. Clique em Importar para abrir o painel Importar dados.
   3. Escolha Catálogo de produtos como origem de dados.
   4. Selecione a filial para a qual vai carregar o catálogo.
   5. Escolha Esquema de catálogos de produtos de retalho como esquema.
   6. Introduza a localização do Cloud Storage dos seus dados.
   7. Se não tiver a pesquisa ativada, selecione os níveis de produtos.
      
      Tem de selecionar os níveis de produtos se estiver a importar o catálogo pela primeira vez ou se estiver a reimportar o catálogo depois de o limpar. Saiba mais acerca dos níveis dos produtos. Alterar os níveis dos produtos depois de importar dados requer um esforço significativo.
      
      Importante: não pode ativar a pesquisa de projetos com um catálogo de produtos que tenha sido carregado como variantes.
   8. Clique em Importar.

   curl

   1. Se estiver a carregar o catálogo pela primeira vez ou a reimportá-lo depois de o limpar, defina os níveis dos produtos através do método Catalog.patch. Saiba mais sobre os níveis dos produtos.

      • ingestionProductType: suporta os valores primary (predefinição) e variant.
      • merchantCenterProductIdField: suporta os valores offerId e itemGroupId. Se não usar o Merchant Center, não precisa de definir este campo.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. Crie um ficheiro de dados para os parâmetros de entrada da importação. Use o objeto GcsSource para apontar para o seu contentor do Cloud Storage.

      Pode fornecer vários ficheiros ou apenas um. Este exemplo usa dois ficheiros.

      • INPUT_FILE: Um ou mais ficheiros no Cloud Storage que contêm os dados do seu catálogo.
      • ERROR_DIRECTORY: Um diretório do Cloud Storage para informações de erro sobre a importação.

      Os campos do ficheiro de entrada têm de estar no formato gs://<bucket>/<path-to-file>/. O diretório de erros tem de estar no formato gs://<bucket>/<folder>/. Se o diretório de erros não existir, é criado. O contentor já tem de existir.

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }

   3. Importe as informações do catálogo fazendo um pedido POST ao método REST Products:import, indicando o nome do ficheiro de dados (aqui, apresentado como input.json).

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

      A forma mais fácil de verificar o estado da operação de importação é usar a Google Cloud consola. Para mais informações, consulte o artigo Veja o estado de uma operação de integração específica.

      Também pode verificar o estado de forma programática através da API. Deve receber um objeto de resposta com um aspeto semelhante ao seguinte:

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }

      O campo name é o ID do objeto de operação. Pede o estado deste objeto, substituindo o campo de nome pelo valor devolvido pelo método de importação, até que o campo done seja devolvido como true:

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/[OPERATION_NAME]"

      Quando a operação estiver concluída, o objeto devolvido tem um valor done de true e inclui um objeto de estado semelhante ao seguinte exemplo:

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse"
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      Pode inspecionar os ficheiros no diretório de erros no Cloud Storage para ver que tipo de erros ocorreram durante a importação.

Importe dados do catálogo inline

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Formato de dados JSON de artigos de produtos

As entradas Product no seu ficheiro JSON devem ter o seguinte aspeto.

Indique um produto completo numa única linha. Cada produto deve estar na sua própria linha.

Campos mínimos obrigatórios:

      {
        "id": "1234",
        "categories": "Apparel & Accessories > Shoes",
        "title": "ABC sneakers"
      }
      {
        "id": "5839",
        "categories": "casual attire > t-shirts",
        "title": "Crew t-shirt"
      }

      {
        "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
        "id": "1234",
        "categories": "Apparel & Accessories > Shoes",
        "title": "ABC sneakers",
        "description": "Sneakers for the rest of us",
        "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
        "language_code": "en",
        "tags": [ "black-friday" ],
        "priceInfo": {
          "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
        },
        "availableTime": "2020-01-01T03:33:33.000001Z",
        "availableQuantity": "1",
        "uri":"http://example.com",
        "images": [
          {"uri": "http://example.com/img1", "height": 320, "width": 320 }
        ]
      }
      {
        "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
        "id": "4567",
        "categories": "casual attire > t-shirts",
        "title": "Crew t-shirt",
        "description": "A casual shirt for a casual day",
        "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
        "language_code": "en",
        "tags": [ "black-friday" ],
        "priceInfo": {
          "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
        },
        "availableTime": "2020-02-01T04:44:44.000001Z",
        "availableQuantity": "2",
        "uri":"http://example.com",
        "images": [
          {"uri": "http://example.com/img2", "height": 320, "width": 320 }
        ]
      }

Dados do histórico do catálogo

O Vertex AI Search para comércio é compatível com a importação e a gestão de dados do catálogo históricos. Os dados do catálogo do histórico podem ser úteis quando usa eventos de utilizadores do histórico para a preparação de modelos. As informações dos produtos anteriores podem ser usadas para enriquecer os dados de eventos do utilizador históricos e melhorar a precisão do modelo.

Os produtos históricos são armazenados como produtos expirados. Não são devolvidos nas respostas de pesquisa, mas são visíveis para as chamadas da API Update, List e Delete.

Importe dados do catálogo do histórico

Quando o campo expireTime de um produto está definido para uma data/hora anterior, este produto é considerado um produto histórico. Defina a disponibilidade do produto como OUT_OF_STOCK para evitar afetar as recomendações.

Recomendamos que use os seguintes métodos para importar dados do catálogo do histórico:

• Chamar o método Product.Create.
• Importação inline de produtos expirados.
• Importar produtos expirados do BigQuery.

Chame o método Product.Create

Use o método Product.Create para criar uma entrada Product com o campo expireTime definido como uma data/hora anterior.

Importe produtos expirados inline

Os passos são idênticos à importação inline, exceto que os produtos devem ter os campos expireTime definidos para uma data/hora anterior.

Indique um produto completo numa única linha. Cada produto deve estar na sua própria linha.

Um exemplo do ./data.json usado no pedido de importação inline:

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

Importe produtos expirados do BigQuery ou do Cloud Storage

Use os mesmos procedimentos documentados para importar dados do catálogo do BigQuery ou importar dados do catálogo do Cloud Storage. No entanto, certifique-se de que define o campo expireTime para uma data/hora anterior.

Mantenha o seu catálogo atualizado

Para obter os melhores resultados, o catálogo tem de conter informações atuais. Recomendamos que importe o seu catálogo diariamente para garantir que está atualizado. Pode usar o Google Cloud Scheduler para agendar importações ou escolher uma opção de agendamento automático quando importa dados através daGoogle Cloud consola.

Pode atualizar apenas os artigos de produtos novos ou alterados, ou importar o catálogo completo. Se importar produtos que já estão no seu catálogo, estes não são adicionados novamente. Todos os itens que foram alterados são atualizados.

Para atualizar um único item, consulte o artigo Atualize as informações dos produtos.

Atualização em lote

Pode usar o método de importação para atualizar o catálogo em lote. Faz isto da mesma forma que faz a importação inicial. Siga os passos em Importar dados do catálogo.

Monitorize o estado da importação

Para monitorizar o carregamento e o estado do catálogo:

1. Veja informações agregadas sobre o seu catálogo e pré-visualize os produtos carregados no separador Catálogo da página Dados de pesquisa para comércio.

   Aceda à página Dados

2. Avalie se precisa de atualizar os dados do catálogo para melhorar a qualidade dos resultados da pesquisa e desbloquear os níveis de desempenho da pesquisa na página Qualidade dos dados.

   Para saber como verificar a qualidade dos dados de pesquisa e ver os níveis de desempenho da pesquisa, consulte o artigo Desbloqueie os níveis de desempenho da pesquisa. Para ver um resumo das métricas do catálogo disponíveis nesta página, consulte Métricas de qualidade do catálogo.

   Aceda à página Qualidade de dados

3. Para criar alertas que lhe permitem saber se algo correu mal com os carregamentos de dados, siga os procedimentos em Configure alertas do Cloud Monitoring.

   Manter o catálogo atualizado é importante para receber resultados de alta qualidade. Use alertas para monitorizar as taxas de erro de importação e tome medidas se necessário.

O que se segue?

• Comece a gravar eventos do utilizador.
• Veja informações agregadas sobre o seu catálogo.
• Configure alertas de carregamento de dados.