O Vertex AI Search for retail vai ser renomeado para Vertex AI Search for commerce. Estamos a atualizar o conteúdo para refletir o novo branding.

Esta página foi traduzida pela API Cloud Translation.

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.

Tutorial em vídeo

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

Importe dados do catálogo 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

Importe dados 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

Importe dados do catálogo inline

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

Antes de começar

Antes de poder importar as informações do catálogo, tem de ter concluído as instruções em Antes de começar, especificamente configurar o seu projeto, criar uma conta de serviço e adicionar a conta de serviço ao seu ambiente local.

Tem de ter a função de IAM Administrador de retalho para realizar a importação.

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 de relatórios de erros do seu projeto. Se encontrar mais do que alguns erros, reveja-os e corrija os problemas de processo que originaram os erros.

Acerca da importação de dados do catálogo

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.

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.

BigQuery	Descrição	Importar dados de uma tabela do BigQuery carregada anteriormente que usa o esquema do Vertex AI Search for commerce. Pode ser realizada através da Google Cloud consola ou do curl.
	Quando usar	Se tiver catálogos de produtos com muitos atributos. A importação do BigQuery usa o esquema da Vertex AI Search for commerce, que tem mais atributos de produtos do que outras opções de importação, incluindo atributos personalizados de chave/valor. Se tiver grandes volumes de dados. A importação do BigQuery não tem um limite de dados. Se já usa o BigQuery.
	Limitações	Requer o passo adicional de criar uma tabela do BigQuery que seja mapeada para o esquema do Vertex AI Search para comércio.
Cloud Storage	Descrição	Importe dados num formato JSON a partir de ficheiros carregados num contentor do Cloud Storage. Cada ficheiro tem de ter 2 GB ou menos, e pode importar até 100 ficheiros de cada vez. A importação pode ser feita através da Google Cloud consola ou do curl. Usa o formato de dados JSON `Product`, que permite atributos personalizados.
	Quando usar	Se precisar de carregar uma grande quantidade de dados num único passo.
	Limitações	Não é ideal para catálogos com atualizações frequentes de inventário e preços, porque as alterações não se refletem imediatamente.
Importação inline	Descrição	Importe-os através de uma chamada ao método `Product.import`. Usa o objeto `ProductInlineSource`, que tem menos atributos do catálogo de produtos do que o esquema da Vertex AI Search para comércio, mas suporta atributos personalizados.
	Quando usar	Se tiver dados de catálogo simples e não relacionais ou uma frequência elevada de atualizações de quantidade ou preço.
	Limitações	Não é possível importar mais de 100 itens do catálogo de cada vez. No entanto, podem ser realizados muitos passos de carregamento. Não existe um limite de itens.

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

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

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.

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 o ramo predefinido apresenta resultados vazios após a limpeza, a limpeza de um ramo predefinido ativo pode causar uma indisponibilidade.

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

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

Aceda à página Dados
Selecione uma filial do catálogo no campo Nome da filial.
No menu de três pontos junto ao campo Nome da ramificação, escolha Eliminar ramificação.

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

Nota: não é possível anular uma limpeza de dados de uma ramificação do catálogo.
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.

Nota: a lista dos dados do catálogo da filial não é atualizada automaticamente após a conclusão da limpeza. Tem de atualizar a página para ver uma lista atualizada da ramificação.

Sincronize o Merchant Center com o Vertex AI Search for commerce

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 do 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

Cloud Console

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

Aceda à página Dados
Clique em Importar para abrir o painel Importar dados.
Escolha Catálogo de produtos.
Selecione Sincronização do Merchant Center como origem de dados.
Selecione a sua conta do Merchant Center. Verifique o acesso do utilizador se não vir a sua conta.
Opcional: selecione o filtro de feeds do Merchant Center para importar apenas ofertas de feeds selecionados.

Se não for especificado, as ofertas de todos os feeds são importadas (incluindo feeds futuros).
Opcional: para importar apenas ofertas segmentadas para determinados países ou idiomas, expanda Mostrar opções avançadas e selecione os países de venda e os idiomas do Merchant Center para filtrar.
Selecione a filial para a qual vai carregar o catálogo.
Clique em Importar.

curl

Verifique se a conta de serviço no seu ambiente local tem acesso à conta do Merchant Center e à Vertex AI Search for commerce. Para verificar que contas têm acesso à sua conta do Merchant Center, consulte o artigo Acesso do utilizador ao Merchant Center.
Use o método MerchantCenterAccountLink.create para estabelecer a associação.
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
  "merchantCenterAccountId": MERCHANT_CENTER_ID,
  "branchId": "BRANCH_ID",
  "feedFilters": [
    {"dataSourceId": DATA_SOURCE_ID_1}
    {"dataSourceId": DATA_SOURCE_ID_2}
  ],
  "languageCode": "LANGUAGE_CODE",
  "feedLabel": "FEED_LABEL",
 }' \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
```
- MERCHANT_CENTER_ID: O ID da conta do Merchant Center.
- BRANCH_ID: o ID da ramificação com a qual estabelecer a associação. Aceita os valores "0", "1" ou "2".
- LANGUAGE_CODE: (OPCIONAL) O código de idioma de duas letras dos produtos que quer importar. Conforme apresentado no Merchant Center na coluna Language do produto. Se não for definido, todos os idiomas são importados.
- FEED_LABEL: (OPCIONAL) A etiqueta do feed dos produtos que quer importar. Pode ver a etiqueta do feed no Merchant Center na coluna Etiqueta do feed do produto. Se não for definido, todas as etiquetas de feeds são importadas.
- FEED_FILTERS: (OPCIONAL) Lista de feeds principais a partir dos quais os produtos vão ser importados. Se não selecionar feeds, significa que todos os feeds da conta do Merchant Center são partilhados. Pode encontrar os IDs no recurso datafeeds da API Content ou visitando o Merchant Center, selecionando um feed e obtendo o ID do feed a partir do parâmetro afmDataSourceId no URL do site. Por exemplo, mc/products/sources/detail?a=MERCHANT_CENTER_ID&afmDataSourceId=DATA_SOURCE_ID.

Para ver o Merchant Center associado, aceda à página Dados da consola de comércio de 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

Cloud Console

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

Aceda à página Dados
Clique no botão Merchant Center na parte superior direita da página para abrir uma lista das suas contas do Merchant Center associadas.

curl

Use o método MerchantCenterAccountLink.list para indicar o recurso links.

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.

Cloud Console

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

Aceda à página Dados
Clique no botão Merchant Center na parte superior direita da página para abrir uma lista das suas contas do Merchant Center associadas.
Clique em Desassociar junto à conta do Merchant Center que está a desassociar e confirme a sua escolha na caixa de diálogo apresentada.

curl

Use o método MerchantCenterAccountLink.delete para remover o recurso MerchantCenterAccountLink.

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:

Se o seu conjunto de dados do BigQuery estiver noutro projeto, configure as autorizações necessárias para que a Pesquisa do Vertex AI para comércio possa aceder ao conjunto de dados do BigQuery. Saiba mais.
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 Product 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 de pesquisa do Vertex AI para comércio, conclua os seguintes passos.

Abra a página IAM na Google Cloud consola.

Abra a página do IAM
Selecione o seu projeto do Vertex AI Search for commerce.
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.
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).
Mude para o seu projeto do BigQuery (na mesma página IAM e administração) e clique em Conceder acesso.
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.
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.
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.

Veja o esquema de produtos do Vertex AI Search for commerce

[
  {
    "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.

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

curl

Importa as informações do catálogo inline fazendo um pedido POST ao método REST Products:import, usando o objeto productInlineSource para especificar os dados do catálogo.

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

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

Crie o ficheiro JSON para o seu produto e atribua-lhe o nome ./data.json:

{
"inputConfig": {
  "productInlineSource": {
      "products": [
        { PRODUCT_1 }
        { PRODUCT_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_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

Java

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"
  }

Objeto completo:

  {
    "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 dos utilizadores 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:

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:

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

Importe informações do catálogo Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Tutorial em vídeo

Importe dados do catálogo do BigQuery

Importe dados do catálogo a partir do Cloud Storage

Importe dados do catálogo inline

Antes de começar

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

Acerca da importação de dados do catálogo

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

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

Produtos principais

Produtos variantes

Obtenção de atributos

Pontuação de relevância

Correspondência de variantes nos resultados da pesquisa

Remova completamente ramificações do catálogo

Sincronize o Merchant Center com o Vertex AI Search for commerce

Associe a sua conta do Merchant Center

Sincronize a sua conta do Merchant Center

Cloud Console

curl

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

Cloud Console

curl

Desassocie a sua conta do Merchant Center

Cloud Console

curl

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

Importe dados do catálogo do BigQuery

Cloud Console

curl

Configure o acesso ao seu conjunto de dados do BigQuery

Esquema de produto

Veja o esquema de produtos do Vertex AI Search for commerce

Importe dados do catálogo a partir do Cloud Storage

Cloud Console

curl

Importe dados do catálogo inline

curl

Java

Formato de dados JSON de artigos de produtos

Dados do histórico do catálogo

Importe dados do catálogo do histórico

Chame o método Product.Create

Importe produtos expirados inline

Importe produtos expirados do BigQuery ou do Cloud Storage

Mantenha o seu catálogo atualizado

Atualização em lote

Monitorize o estado da importação

O que se segue?

Importe informações do catálogo

Chame o método `Product.Create`