Entidades de dados de catálogo
Este artigo oferece orientações sobre como configurar entidades de dados de catálogo no contrato de dados do Recomendações Inteligentes.
Revisão de entidades de dados
Uma entidade de dados é um conjunto de um ou mais arquivos de texto de dados, cada um com uma lista de colunas (também chamadas de atributos) e linhas contendo os valores de dados reais.
O Recomendações Inteligentes define grupos lógicos de entidades de dados, cada um com sua própria finalidade.
Observação
As entidades de dados são opcionais (a menos que explicitamente indicado de outra forma), o que significa que seus dados podem estar vazios ou totalmente ausentes.
Ir para a lista completa das entidades de dados
Introdução às entidades de dados do catálogo
A entidade de dados catálogo representa todos os itens e variantes de itens que são candidatos para aparecer nos resultados de recomendações. Os candidatos são determinados por meio da aplicação de disponibilidades a itens, uma data que instrui o sistema a incluir um item nos resultados das recomendações. Sem uma disponibilidade válida, os itens serão ignorados quando os resultados forem retornados.
O Recomendações Inteligentes oferece suporte aos seguintes recursos e cenários:
Itens que têm diversas variações (por exemplo, uma camisa em tamanhos ou cores diferentes) ou nenhuma variação. Referimo-nos a essas variações como variantes. Os itens que não têm variantes são chamados de itens autônomos, enquanto os itens que possuem pelo menos uma variante são chamados de mestres de itens.
Atribuição de valores de filtro a itens (por exemplo, categoria, cor ou tamanho). Posteriormente, ao consultar recomendações, você poderá filtrar por esses valores de filtro.
Atribuição de imagens a itens.
Os itens podem estar disponíveis em diferentes entidades lógicas dentro da organização. O Recomendações Inteligentes oferece suporte a dois níveis de hierarquias:
Canal: os itens podem ser atribuídos a um canal, permitindo que o Recomendações Inteligentes forneça recomendações delimitadas apenas a produtos incluídos em um canal específico. Todos os itens são automaticamente associados ao canal padrão, que usa a cadeia de caracteres 0 (zero) como a ID do canal reservado.
Exemplo:
Neste exemplo, o conjunto de dados contém apenas três itens: X, Y e Z. Esses três itens são atribuídos automaticamente ao canal padrão (Channel=0). Você também pode atribuir esses itens aos seus próprios canais personalizados. Por exemplo, você pode atribuir os itens X e Y a Channel=C1 e os itens Y e Z a Channel=C2.
Assim, ao solicitar recomendações, você pode passar estes outros parâmetros de consulta:
- Nenhum parâmetro de canal (igual ao canal padrão): todos os três itens podem ser retornados na resposta
- Channel=0: o mesmo que nenhum parâmetro, pois este canal é o padrão
- Channel=C1: somente os itens que pertencem ao canal C1 (itens X e Y) podem ser retornados na resposta
- Channel=C2: somente os itens que pertencem ao canal C2 (itens Y e Z) podem ser retornados na resposta
- Channel=SomethingElse: resposta vazia porque este canal não foi definido e nenhum item foi atribuído a ele
Catálogo: um catálogo é outro nível mais refinado de granularidade de disponibilidade. Ele permite definir vários catálogos em um canal e obter recomendações para catálogos específicos. Semelhante a um canal, todos os itens são automaticamente associados ao catálogo padrão em um canal, que usa a cadeia de caracteres 0 (zero) como a ID do catálogo reservado.
Exemplo:
Continuando com o exemplo Canal, você tem os itens X, Y e Z. Você atribuiu os itens X e Y ao canal C1, e eles são atribuídos automaticamente ao catálogo padrão no canal (usando Catalog=0). Você pode ter mais granularidade atribuindo esses itens a catálogos personalizados dentro do canal. Vamos atribuir o item X a Catalog=A e os itens X e Y a Catalog=B.
Assim, ao solicitar recomendações, você pode passar estes outros parâmetros de consulta:
- Channel=C1: nenhum parâmetro de catálogo, é igual ao catálogo padrão. Os itens X e Y podem ser retornados na resposta.
- Channel=C1&Catalog=0: igual ao parâmetro nenhum catálogo, pois este catálogo é o padrão.
- Channel=C1&Catalog=A: somente os itens que pertencem ao catálogo A no canal C1 (somente o item X) podem ser retornados na resposta.
- Channel=C1&Catalog=B: somente os itens que pertencem ao catálogo B no canal C1 (itens X e Y) podem ser retornados na resposta.
- Channel=C1&Catalog=SomethingElse: resposta vazia porque este catálogo não foi definido no canal C1 e nenhum item foi atribuído a ele.
Declare as disponibilidades dos itens:
- Datas de início/término de disponibilidade: os itens que estiverem fora do intervalo de tempo de disponibilidade serão excluídos da resposta de recomendação.
- Granularidade fina de disponibilidade: defina as datas de início/término em IDs de canal/catálogo específicas.
O catálogo é composto por várias entidades de dados, todas opcionais (dependendo de quais recursos você deseja usar), e pode permanecer vazio (ou ausente) da pasta raiz do Recomendações Inteligentes. Siga as diretrizes na entidade de dados Reco_ItemsAndVariants, descritas abaixo, se você não quiser fornecer essa entidade de dados.
Lista de entidades de dados de catálogo
As seguintes entidades de dados fazem parte do catálogo:
- Itens e variantes
- Categorias do Item
- Imagens de itens e variantes
- Filtros de itens e variantes
- Disponibilidades de itens e variantes
Ir para a lista completa das entidades de dados
Itens e variantes
Nome da entidade de dados:Reco_ItemsAndVariants
Descrição: todos os itens e variantes de itens
Atributos:
| Name | Tipo de dados | Obrigatório | Valor padrão | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | String(16) | Sim | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID do item. | |
| ItemVariantId | String(16) | Não | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID da variante do item. | |
| Title | String(256) | Não | Cortar valor | Tamanho limitado a 256 caracteres. | |
| Descrição | String(2048) | Não | Cortar valor | Tamanho limitado a 2048 caracteres. | |
| ReleaseDate | DateTime | Não | 1970-01-01T00:00:00.000Z | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter valores de DateTime. |
Diretrizes:
As variantes de itens herdam os atributos do mestre do item. Por exemplo, se uma variante de item não tiver título, ela herdará o título do mestre do item (ou seja, a linha com a mesma ItemId, mas com uma ItemVariantId vazia), se existir.
ItemIds podem ter um relacionamento um para muitos com ItemVariantIds. É possível que uma única ItemId seja mapeada para mais de uma ItemVariantId para capturar o relacionamento de um mestre do item com suas variantes de itens. É possível ter uma única entrada para uma combinação específica de ItemId e ItemVariantId sem especificar outras combinações de ItemId e ItemVariantId.
O atributo ReleaseDate representa a data em que o item foi lançado (publicado, introduzido) no mercado. Este atributo é diferente da disponibilidade de um item (quando um item/produto pode ser retornado em uma chamada à API), mas ReleaseDate pode ser usado em cenários como Novos e Mais Populares, que dependem de datas para ordenação de itens.
Se esta entidade de dados estiver vazia (ou ausente), o Recomendações Inteligentes usará automaticamente todos os itens e variantes de itens encontrados na entidade de dados Reco_Interactions como o conjunto de itens de catálogo e atribuirá a cada item e variante de item o título, a descrição e a data de lançamento padrão. Esses itens serão considerados sempre disponíveis a menos que tenham recebido disponibilidades explícitas na entidade de dados Reco_ItemAndVariantAvailabilities.
O Recomendações Inteligentes pode usar os atributos Título e Descrição para fornecer recomendações baseadas em texto. Como o Recomendações Inteligentes atualmente oferece suporte apenas à localidade en-us para recomendações textuais, fornecer o Título e a Descrição em qualquer outra localidade pode degradar a qualidade das recomendações textuais.
Dados de exemplo:
Os cabeçalhos aparecem apenas por conveniência e não devem fazer parte dos dados reais.
| ItemId | ItemVariantId | Title | Descrição | ReleaseDate |
|---|---|---|---|---|
| Item1 | 2018-05-15T13:30:00.000Z | |||
| Item1 | Item1Var1 | Óculos de sol pretos | Óculos de sol pretos para crianças | 2018-08-01T10:45:00.000Z |
| Item1 | Item1Var2 | Óculos de sol marrons | Óculos de sol marrons para adultos | |
| Item2 | Pano de limpeza de óculos | 2019-09-20T18:00:00.000Z | ||
| Item3 | Item3Var1 |
Retornar à lista de entidades de catálogo de dados
Categorias do Item
Nome da entidade de dados:Reco_ItemCategories
Descrição: todas as categorias de itens.
Atributos:
| Name | Tipo de dados | Obrigatório | Valor padrão | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | String(16) | Sim | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID do item. | |
| Categoria | String(64) | Sim | Cortar valor | Tamanho limitado a 64 caracteres. |
Diretrizes:
Cada ItemId pode ter várias categorias, o que significa que pode aparecer em várias entradas nos dados.
Se os seus dados forem construídos usando árvores de categorias, você precisará fornecer o conjunto completo de categorias (achatadas) para cada item.
Dados de exemplo:
Os cabeçalhos aparecem apenas por conveniência e não devem fazer parte dos dados reais.
| ItemId | Categoria |
|---|---|
| Item1 | Category1 |
| Item1 | Category1_subCategoryX |
| Item1 | Category1_subCategoryY |
| Item2 | Category1_subCategoryX |
Retornar à lista de entidades de catálogo de dados
Imagens de itens e variantes
Nome da entidade de dados:Reco_ItemAndVariantImages
Descrição: todas as imagens de itens e variantes de itens
Atributos:
| Name | Tipo de dados | Obrigatório | Valor padrão | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | String(16) | Sim | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID do item. | |
| ItemVariantId | String(16) | Não | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID da variante do item. | |
| ImageFullUrl | String(2048) | Sim | Soltar entrada | Deve ser uma URL absoluta. A URL deve ser codificada corretamente (usando codificação percentual). Tamanho limitado a 2048 caracteres. | |
| IsPrimaryImage | Bool | Sim | Veja as diretrizes | Consulte Entidades de dados necessárias por cenário de recomendações para obter valores boolianos. |
Diretrizes:
Você deve atribuir imagens explicitamente a uma ItemId e a cada ItemVariantId relevante. As imagens atribuídas a um item não são atribuídas automaticamente a todas as variantes do item e vice-versa. As imagens atribuídas a uma variante do item não são atribuídas automaticamente ao mestre do item dessa variante.
Se mais de uma imagem primária for especificada para a mesma combinação <ItemId, ItemVariantId>, somente uma dessas imagens será usada para a etapa de inferência de recomendações visuais e as demais serão usadas apenas no treinamento de todo o modelo visual.
Para qualquer imagem que Recomendações Inteligentes não conseguir acessar, a URL da imagem será ignorada e não será usada para o modelo de recomendação.
Se o valor IsPrimaryImage for inválido, um valor de falso será usado (por exemplo, imagem não primária).
Se somente imagens não primárias forem especificadas para um item ou variante de item, o Recomendações Inteligentes usará uma das imagens especificadas como imagem primária para ainda fornecer recomendações visuais para esse item ou variante de item.
Há dois tipos de URLs com suporte:
- URLs HTTPS disponíveis publicamente: não exigem um cabeçalho Autorização. Esta URL não inclui URLs de blobs do Azure disponíveis publicamente/anonimamente, que não têm suporte.
-
URLs de Armazenamento de Blobs do Azure que exigem autenticação: não estão disponíveis publicamente/anonimamente. As permissões para ler os blobs de imagem devem ser concedidas ao Recomendações Inteligentes, conforme explicado em Implantar o Recomendações Inteligentes). As URLs de blob devem começar com o prefixo:
https://<StorageAccountName>.blob.core.windows.net/.
O tamanho máximo permitido para uma única imagem é de 512 KB. Qualquer imagem maior que 512 KB será ignorada pelo sistema.
O ContentType para a imagem deve ter um tipo de conteúdo de imagem (deve começar com imagem). Esse requisito se aplica a todas as imagens, disponíveis via HTTPS e blobs de imagem (por meio da propriedade ContentType do blob).
Dados de exemplo:
Os cabeçalhos aparecem apenas por conveniência e não devem fazer parte dos dados reais.
| ItemId | ItemVariantId | ImageFullUrl | IsPrimaryImage |
|---|---|---|---|
| Item1 | https://my.server.org/images/Item1_primary.jpg |
Verdadeiro | |
| Item1 | https://my.server.org/images/Item1_secondary.jpg |
Falso | |
| Item1 | Item1Var1 | https://my.server.org/images/Item1Var1.jpg |
Verdadeiro |
| Item2 | https://my.server.org/images/Item2.jpg |
Verdadeiro |
Retornar à lista de tipos de entidades de catálogo
Filtros de itens e variantes
Nome da entidade de dados:Reco_ItemAndVariantFilters
Descrição: propriedades de itens e variantes de itens usadas para filtragem de resultados de runtime
Atributos:
| Name | Tipo de dados | Obrigatório | Valor padrão | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | String(16) | Sim | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID do item. | |
| ItemVariantId | String(16) | Não | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID da variante do item. | |
| FilterName | String(64) | Sim | Cortar valor | ||
| FilterValue | String(64) | Sim | Cortar valor | Tamanho limitado a 64 caracteres. | |
| FilterType | String | Sim | Soltar entrada | Os valores possíveis incluem: Textual, Numérico. |
Diretrizes:
Itens e variantes de itens têm um relacionamento principal-secundário. Esta diretriz significa que as variantes de itens herdarão os filtros do mestre do item. Por exemplo, se o filtro "Cor" tiver sido declarado para uma determinada ItemId, todas as variantes de itens da mesma ItemId obterão o mesmo valor do filtro "Cor", a menos que um valor "Cor" diferente tenha sido especificado para a variante do item.
Os tipos de filtros textuais oferecem suporte à operação de filtragem "igual". Por exemplo, as solicitações de API podem filtrar itens com "Cor"="Azul".
Os tipos de filtros numéricos oferecem suporte a operações de filtragem "intervalo". Por exemplo, as solicitações de API podem filtrar itens com "Tamanho" > 40.
Você pode atribuir vários valores de filtro ao mesmo filtro. Por exemplo, para o filtro "Cor", você pode fornecer vários valores, como "Verde" e "Azul". Neste exemplo, o item relevante tem dois valores para o filtro "Cor" e será retornado quando você filtrar por itens da cor "Verde" ou "Azul". Para atribuir vários valores ao mesmo filtro, adicione uma entrada para cada valor de filtro que você deseja atribuir, usando os mesmos valores FilterName e FilterType.
Para cada FilterName, uma variante de item pode herdar os valores do filtro principal ou substituí-los. Não há suporte para a mesclagem dos dois. Por padrão, se a variante não tiver valores atribuídos a um filtro, ela herdará os valores do filtro do item principal. Se pelo menos um valor de filtro for atribuído a um filtro para uma variante de item, o modo de substituição será ativado e somente os valores de filtro da variante serão efetivos (somente para o filtro específico). Este valor significa que, para obter um comportamento de "mesclagem", a variante do item deve repetir os valores do filtro principal. Por exemplo, um item oferece suporte a duas cores, Azul e Verde. Se uma variante oferecer suporte a outra cor, Vermelho, ela deverá listar todas as três cores atribuídas à ID da variante: Azul, Verde e Vermelho. Neste exemplo, a variante do item substituiu os valores do filtro "Cor", mas ainda pode herdar os valores para outros filtros do item principal.
As entradas com tipos de filtro sem suporte serão ignoradas.
Você pode fornecer até 20 FilterName diferentes.
Fornecer várias entradas com o mesmo FilterName, mas um FilterType diferente falhará no processo de ingestão de dados das Recomendações Inteligentes.
Itens ou variantes de itens não podem ter filtros especificados. Se você especificar qualquer filtro na solicitação de API, os itens ou variantes de itens sem o filtro especificado serão filtrados.
Dados de exemplo:
Os cabeçalhos aparecem apenas por conveniência e não devem fazer parte dos dados reais.
| ItemId | ItemVariantId | FilterName | FilterValue | FilterType |
|---|---|---|---|---|
| Item1 | Color | Vermelho | Textual | |
| Item1 | Item1Var1 | Color | Vinho | Textual |
| Item1 | Item1Var2 | Estilo | Retangular | Textual |
| Item2 | Size | 38 | Numérico | |
| Item2 | Color | Azul | Textual | |
| Item2 | Color | Verde | Textual |
Retornar à lista de tipos de entidades de catálogo
Disponibilidades de itens e variantes
Nome da entidade de dados:Reco_ItemAndVariantAvailabilities
Descrição: todas as disponibilidades de itens e variantes de itens
Atributos:
| Name | Tipo de dados | Obrigatório | Valor padrão | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | String(16) | Sim | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID do item. | |
| ItemVariantId | String(16) | Não | Soltar entrada | Consulte Entidades de dados necessárias por cenário de recomendações para obter a ID da variante do item. | |
| StartDate | DateTime | Não | 0001-01-01T00:00:00.000Z | Veja as diretrizes | Consulte Entidades de dados necessárias por cenário de recomendações para obter valores de DateTime. |
| EndDate | DateTime | Não | 9999-12-31T23:59:59.999Z | Veja as diretrizes | Consulte Entidades de dados necessárias por cenário de recomendações para obter valores de DateTime. |
| Atributo duplo | Duplo | Não | Um atributo duplo que pode ser usado de acordo com as necessidades do negócio e não afeta o processo de modelagem. | ||
| Canal | String(64) | Não | 0 | Cortar valor | Tamanho limitado a 64 caracteres. |
| Catálogo | String(64) | Não | 0 | Cortar valor | Tamanho limitado a 64 caracteres. |
Diretrizes:
Lembrete: as disponibilidades informam ao sistema quais itens ou variantes de itens são considerados candidatos para resultados de recomendações.
A disponibilidade de uma variante de item é a união das disponibilidades do mestre do item e da disponibilidade da própria variante de item. Mesmo as variantes de itens que não têm entradas herdarão as disponibilidades do mestre do item.
Um item que esteja ausente nesta entidade de dados será considerado como sempre disponível no canal e catálogo padrão. Mais especificamente, o Recomendações Inteligentes se comportará exatamente como se esse item aparecesse nos dados com valores padrão para todos os atributos.
ItemIds têm um relacionamento um para muitos com ItemVariantIds. Embora uma ItemId não seja necessária para ter uma ItemVariantId, é possível que mais de uma ItemVariantId possa ser mapeada para uma única ItemId. Por exemplo, você pode adicionar uma entrada para uma combinação específica de ItemId e ItemVariantId sem também adicionar explicitamente outra entrada para a ItemId (e uma ItemVariantId vazia). Ao determinar se as variantes de itens têm disponibilidades válidas, somente as variantes de itens especificadas serão consideradas disponíveis (nos intervalos de tempo especificados para cada variante).
Um catálogo é relevante apenas no contexto de um canal (Catálogos são um subconjunto de canais). Por exemplo, catalog=MySale em channel=Europe é um catálogo diferente de catalog=MySale em channel=Asia.
Se o seu conjunto de dados contiver vários canais e catálogos, você precisará adicionar uma entrada para cada combinação relevante de canal e catálogo para cada item e variante de item relevante.
As datas de disponibilidade são relevantes apenas para o canal e o catálogo especificados. Se quiser especificar as mesmas datas de disponibilidade para canais e catálogos diferentes, você precisará adicionar explicitamente uma entrada para cada canal e catálogo.
Se houver um valor inválido para qualquer um dos atributos StartDate ou EndDate, a entrada inteira será modificada para representar um item não disponível. Ambos StartDate e EndDate serão substituídos por valores DateTime que estão no passado.
O "atributo duplo" pode ser deixado em branco.
Não use "0" como valor para "Canal". Este valor é reservado para o sistema. Usar "0" resultará em um erro de processamento.
Dados de exemplo:
Os cabeçalhos aparecem apenas por conveniência e não devem fazer parte dos dados reais.
| ItemId | ItemVariantId | StartDate | EndDate | Atributo duplo | Canal | Catálogo |
|---|---|---|---|---|---|---|
| Item1 | 2020-08-20T10:00:00.000Z | |||||
| Item1 | Item1Var1 | 2020-08-01T12:00:00.000Z | ||||
| Item2 | 2020-04-01T10:00:00.000Z | 2020-04-15T23:59:59.999Z | 15.0 | |||
| Item2 | 2020-04-01T10:00:00.000Z | 9.76 | ||||
| Item3 | 2020-05-01T12:00:00.000Z | Europa | MySale |
Retornar à lista de tipos de entidades de catálogo
Confira também
Visão geral do contrato de dados
Tabela Mapeamento de entidades de dados
Entidades de dados de interações
Entidades de dados de configuração de recomendações
Entidades de dados de usuários recusados
Entidades de dados de listas externas
Entidades de dados de enriquecimento de recomendações
Entidades de dados de mapeamentos de imagem para item
API do Recomendações Inteligentes
Guia de Início Rápido: configurar e executar o Recomendações Inteligentes com dados de exemplo