Catálogos e informações de catálogo

Esta página informa as práticas recomendadas para criar informações do catálogo e preencher os dados do catálogo.

Visão geral

Os dados do catálogo importados para o Recommendations AI têm efeito direto sobre a qualidade do modelo resultante e, portanto, a qualidade do Recommendations AI fornecido. Em geral, quanto mais precisas e específicas forem as informações de catálogo que você fornecer, maior será a qualidade do seu modelo.

Seu catálogo precisa estar atualizado. É possível fazer upload das alterações do catálogo quantas vezes forem necessárias. Idealmente, todos os dias para catálogos com uma alta taxa de mudanças. É possível fazer upload (patch) de itens de produto existentes somente os campos alterados serão atualizados. Não há cobrança pelo upload das informações do catálogo. Para mais informações, consulte Como manter seu catálogo atualizado.

Produtos

O catálogo é um conjunto de objetos de produto.

Informações obrigatórias do produto

Os campos a seguir são obrigatórios. É preciso fornecer valores a eles ao criar itens de produtos no catálogo. Eles também precisam corresponder aos valores usados no banco de dados interno do produto e refletir com precisão o produto representado, porque estão incluídos no treinamento dos modelos.

Em alguns casos, outros campos também são obrigatórios. Consulte a lista completa de todos os campos de produtos na [página de referência Product][product-ref].

Todas as informações do produto que você fornece podem ser usadas para melhorar a qualidade das recomendações. Forneça o maior número possível de campos.

Campo	Observações
`name`	O nome exclusivo completo do recurso do produto. Obrigatório para todos os métodos de produto, exceto `import`. Durante a importação, o nome é gerado automaticamente e não precisa ser fornecido manualmente.
`id`	O ID do produto usado pelo banco de dados do produto. O campo "ID" precisa ser exclusivo em todo o catálogo. O mesmo valor é usado quando você registra um evento de usuário e também é retornado pelo método `predict`.
`title`	Título do produto do seu banco de dados de produtos. Uma string codificada em UTF-8. Limitado a 1.250 caracteres.

Como usar níveis de produto

Ao importar o catálogo pela primeira vez, especifique se você está fornecendo apenas itens principais ou itens principais, bem como as variantes deles.

Os itens primários são retornados pela API Retail nos resultados de previsão. Eles podem ser itens individuais (nível da SKU) ou grupos de itens semelhantes (grupos da SKU). Por padrão, a API Retail é configurada para importar apenas itens principais.
Os itens variantes são versões de um produto principal. As variantes só podem ser itens individuais (nível SKU). Por exemplo, se o produto principal for "camisa com gola em V", as variantes poderão ser "camisa com gola marrom branca, tamanho X". e "camisa com gola branca v e tamanho P". Ps vezes, as primárias e as variantes são descritas como itens "pais" e "filhos". A importação de variantes é opcional.

Durante a importação de catálogo, defina seus níveis de produto usando o método Catalog.patch. Exemplo:

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"

Para determinar as melhores opções de nível de produto para sua implementação, você precisará revisar os dados do catálogo e a lógica do seu site. Quais IDs de itens estão disponíveis quando você captura dados de eventos do usuário? Quais IDs de itens seriam mais eficazes a serem retornados com previsões? Como esses IDs se comparam e se relacionam?

Use as etapas apropriadas, dependendo se você está importando do Merchant Center ou não:

Como determinar os níveis de produto a serem importados do Merchant Center

Quando você importa dados de catálogo do Merchant Center, a API Retail usa ingestionProductType para ajudar a identificar se é necessário fazer o upload deles como itens primários ou variantes; e o campo merchantCenterProductIdField para especificar se é preciso usar offer_id ou item_group_id do Merchant Center como ID do produto.

Revise os dados do catálogo e a lógica do seu site para responder às seguintes perguntas:

Tenho primárias e variantes no meu catálogo?
Se sim, que nível de item terei ao capturar os dados de eventos do usuário?
Que tipo de itens preciso retornar com minhas previsões?

Determine se:

Seu catálogo tem apenas um nível de itens. Isso pode significar que:
- Todos os seus produtos e eventos estão no nível de SKU, e você quer previsões no nível de SKU.
- Todos os seus produtos e eventos estão no nível do grupo, e você quer previsões no nível do grupo.
Se for o caso, importe somente com os itens principais. Esta é a configuração de importação padrão.
Você quer previsões no nível do grupo (principal), mas seus produtos do Merchant Center estão no nível da SKU. Nesse caso, sua decisão de importação depende de como os eventos são capturados.
1. Os eventos são capturados no nível do grupo. Nesse caso, use as configurações a seguir durante a importação:
  - ingestionProductType definido como primary (padrão)
  - merchantCenterProductIdField definido como itemGroupId.
  Em que vários produtos do Merchant Center têm o mesmo item_group_id do Merchant Center, o Recommendations AI importa apenas um deles como um produto principal, e usa item_group_id como o ID do produto. Os produtos que não têm um item_group_id não podem ser importados nesse caso. Os eventos gravados precisam se referir ao ID do produto principal (no nível do grupo).
2. Seus eventos são capturados no nível de SKU. Nesse caso, use as configurações a seguir durante a importação:
  - ingestionProductType definido como variant.
  - merchantCenterProductIdField definido como offerId (padrão).
  O Recommendations AI importa seus produtos como variantes e usa o offer_id do Merchant Center como o ID do produto. Os eventos gravados precisam se referir ao ID da variante no nível da SKU.

Como determinar os níveis de produto para importação sem o Merchant Center

É necessário que todos os seus produtos tenham um valor para primaryProductId ou nenhum deles. Não é possível importar dados de catálogo com primaryProductId definido para alguns itens, mas para outros não.

Caso seu catálogo tenha somente um nível de itens, isso poderá significar que:
- Todos os seus produtos e eventos estão no nível de SKU, e você quer previsões no nível de SKU.
- Todos os seus produtos e eventos estão no nível do grupo, e você quer previsões no nível do grupo.
Se for o caso, importe somente com os itens principais. Essa é a configuração de importação padrão e recomendada.
Se os eventos e produtos estiverem no nível da SKU, você poderá receber previsões no nível do grupo. Defina ingestionProductType como variant durante a importação.

A previsão no nível de SKU não será compatível se você tiver apenas produtos e eventos no nível do grupo.

Se você pretende importar dados do catálogo do Merchant Center no futuro, revise seus dados conforme descritos para importações do Merchant Center para garantir que esteja fazendo a escolha correta. Para alterar essa configuração, exclua o catálogo e faça upload novamente. Consulte Como alterar a configuração no nível do produto.

Esquema do Recommendations AI

Ao importar um catálogo do BigQuery, use o esquema do Recommendations AI abaixo 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.

JSON do esquema do Recommendations AI

JSON

[
 {
   "name": "name",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "id",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "primaryProductId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "categories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "title",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "description",
   "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": "availableTime",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "availability",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "availableQuantity",
   "type": "INTEGER",
   "mode": "NULLABLE"
 },
 {
   "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"
     }
   ]
 }
]