Entidades de dados de catálogo
Este artigo fornece informações sobre como configurar entidades de dados de catálogo no contrato de dados do Intelligent Recommendations.
Revisão de entidades de dados
Uma entidade de dados é um conjunto de um ou mais ficheiros de texto de dados, cada um com uma lista de colunas (também denominados atributos) e linhas que contêm os valores reais dos dados.
O Intelligent Recommendations define grupos lógicos de entidades de dados, cada um com o seu próprio propósito.
Nota
As entidades de dados são opcionais, a menos que tenha sido explicitamente indicado o contrário, o que significa que os respetivos dados podem estar vazios ou em falta.
Voltar à lista completa de entidades de dados
Introdução às entidades de dados de catálogo
A entidade de dados de catálogo representa todos os itens e variantes de item candidatos a aparecer nos resultados das recomendações. Os candidatos são determinados pela aplicação de disponibilidades a itens, uma data que indica ao sistema que deve incluir um item nos resultados das recomendações. Sem uma disponibilidade válida, os itens são ignorados quando os resultados são devolvidos.
O Intelligent Recommendations suporta as seguintes caraterísticas e cenários:
Itens com várias variações (por exemplo, uma camisa com tamanhos ou cores diferentes) ou que não têm variações nenhumas. Referimo-nos a estas variações como variantes. Os itens que não têm variantes são denominados de itens autónomos, enquanto os itens que têm, pelo menos, uma variante são denominados de item principais.
Atribuir valores de filtro a itens (por exemplo, categoria, cor ou tamanho). Mais tarde, quando consultar as recomendações, poderá filtrar por estes valores de filtro.
Atribuir imagens a itens.
Os itens podem estar disponíveis em entidades lógicas diferentes na organização. O Intelligent Recommendations suporta dois níveis de hierarquias:
Canal: é possível atribuídos itens a um canal, permitindo que o Intelligent Recommendations forneça recomendações com âmbito de apenas produtos incluídos num canal específico. Todos os itens são automaticamente associados ao canal predefinido, que utiliza a cadeia 0 (zero) como ID de canal reservado.
Exemplo:
Neste exemplo, o conjunto de dados contém apenas três itens: X, Y e Z. Estes três itens são atribuídos automaticamente ao canal predefinido (Channel=0). Pode também atribuir estes itens aos seus próprios canais personalizados. Por exemplo, pode atribuir os itens X e Y a Channel=C1 e os itens Y e Z a Channel=C2.
Assim, quando pedir recomendações, poderá transmitir estes outros parâmetros de consulta:
- Nenhum parâmetro de Canal (igual a canal predefinido): todos os três itens podem ser devolvidos na resposta
- Channel=0: o mesmo que nenhum parâmetro, uma vez que este é o canal predefinido
- Channel=C1: só é possível devolver itens que pertençam ao canal C1 (itens X e Y) na resposta
- Channel=C2: só é possível devolver itens que pertençam ao canal C2 (itens Y e Z) na resposta
- Channel=SomethingElse: resposta vazia porque este canal não foi definido e não lhe estão atribuídos itens
Catálogo: um catálogo é outro nível de disponibilidade mais fino e granular. Permite-lhe definir vários catálogos num canal e obter recomendações para catálogos específicos. Tal como com um canal, todos os itens são automaticamente associados ao catálogo predefinido no canal, o qual utiliza a cadeia 0 (zero) como ID de catálogo reservado.
Exemplo:
Continuando com o exemplo do Canal, tem os itens X, Y e Z. Atribuiu os itens X e Y ao canal C1 e estes são atribuídos automaticamente ao catálogo predefinido no canal (utilizando Catalog=0). Pode obter uma maior granularidade ao atribuir estes itens a catálogos personalizados no canal. Vamos atribuir o item X a Catalog=A e os itens X e Y a Catalog=B.
Assim, quando pedir recomendações, poderá transmitir estes outros parâmetros de consulta:
- Channel=C1: sem parâmetro de catálogo, é igual ao catálogo predefinido. Ambos os itens X e Y podem ser devolvidos na resposta.
- Channel=C1&Catalog=0: o mesmo que nenhum parâmetro de catálogo, porque este é o catálogo predefinido.
- Channel=C1&Catalog=A: só é possível devolver itens que pertençam ao catálogo A no canal C1 (só item X) na resposta.
- Channel=C1&Catalog=B: só é possível devolver itens que pertençam ao catálogo B no canal C1 (itens X e Y) na resposta.
- Channel=C1&Catalog=SomethingElse: resposta vazia porque este catálogo não foi definido no canal C1 e não lhe estão atribuídos itens.
Declarar disponibilidades de itens:
- Datas de início/fim da disponibilidade: os itens que estiverem fora do intervalo de tempo da disponibilidade serão excluídos da resposta da recomendação.
- Granularidade fina da disponibilidade: defina as datas de início/fim dentro de IDs de canal/catálogo específicos.
O catálogo é composto por várias entidades de dados, todas opcionais (dependendo das caraterísticas que pretende utilizar) e podem permanecer vazias (ou em falta) a partir da pasta raiz do Intelligent Recommendations. Siga as orientações na entidade de dados Reco_ItemsAndVariants, descritas a seguir, se não quiser fornecer esta 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 de itens
- Imagens de itens e de variantes
- Filtros de itens e variantes
- Disponibilidades de itens e variantes
Voltar à lista completa de entidades de dados
Itens e variantes
Nome da entidade de dados:Reco_ItemsAndVariants
Descrição: todas os itens e variantes de item
Atributos:
| Name | Tipo de dados | Obrigatório | Default value | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | Cadeia(16) | Sim | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de item. | |
| ItemVariantId | Cadeia(16) | Não | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de variante de item. | |
| Title | Cadeia(256) | Não | Cortar valor | Comprimento limitado a 256 carateres. | |
| Descrição | Cadeia(2048) | Não | Cortar valor | Comprimento limitado a 2048 carateres. | |
| ReleaseDate | DateTime | Não | 1970-01-01T00:00:00.000Z | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para valores de DateTime. |
Diretrizes:
As variantes de item herdam os atributos do item mestre. Por exemplo, se uma variante de item não tiver título, herda o título do item mestre (ou seja, a linha com o mesmo ItemId, mas com um ItemVariantId vazio) se existir.
ItemIds pode ter uma relação um-para-muitos com ItemVariantIds. É possível que um único ItemId seja mapeado para mais do que um ItemVariantId para capturar a relação de um item mestre com as variantes de item. É 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 de lançamento do item (publicado, introduzido) no mercado. Este atributo é diferente da disponibilidade de um item (quando um item/produto pode ser devolvido numa chamada à API), mas ReleaseDate pode ser utilizado em cenários como Novo e Mais Populares, os quais dependem de datas para a encomenda de itens.
Se esta entidade de dados estiver vazia (ou em falta), o Intelligent Recommendations utilizará automaticamente todos as variantes de item encontradas na entidade de dados Interações de Recomendações como o conjunto de itens de catálogo e atribuir cada item e variante de item o título, a descrição e a data de lançamento predefinidos. Estes itens são considerados como sempre disponíveis, a menos que tenham sido atribuídas disponibilidades explícitas na entidade de dados Reco_ItemAndVariantAvailabilities.
O Intelligent Recommendations pode utilizar os atributos Título e Descrição para fornecer recomendações baseadas em textual. Uma vez que o Intelligent Recommendations suporta atualmente apenas a região en-us para recomendações textuais, fornecer o Título e a Descrição em qualquer outra região poderá degradar a qualidade das recomendações textuais.
Dados de amostra:
Os cabeçalhos aparecem apenas para comodidade 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 castanhos | Óculos de sol castanhos para adultos | |
| Item2 | Pano de limpeza para óculos | 2019-09-20T18:00:00.000Z | ||
| Item3 | Item3Var1 |
Regressar à lista de entidades de dados de catálogo
Categorias de itens
Nome da entidade de dados:Reco_ItemCategories
Descrições: todas as categorias de itens.
Atributos:
| Name | Tipo de dados | Obrigatório | Default value | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | Cadeia(16) | Sim | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de item. | |
| Categoria | Cadeia(64) | Sim | Cortar valor | Comprimento limitado a 64 carateres. |
Diretrizes:
Cada ItemId pode ter várias categorias, o que significa que pode aparecer em várias entradas nos dados.
Se os dados forem construídos utilizando árvores de categorias, tem de fornecer o conjunto completo de categorias (simplificados) para cada item.
Dados de amostra:
Os cabeçalhos aparecem apenas para comodidade e não devem fazer parte dos dados reais.
| ItemId | Categoria |
|---|---|
| Item1 | Category1 |
| Item1 | Category1_subCategoryX |
| Item1 | Category1_subCategoryY |
| Item2 | Category1_subCategoryX |
Regressar à lista de entidades de dados de catálogo
Imagens de itens e de variantes
Nome da entidade de dados:Reco_ItemAndVariantImages
Descrição: todas as imagens de item e variante de item
Atributos:
| Name | Tipo de dados | Obrigatório | Default value | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | Cadeia(16) | Sim | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de item. | |
| ItemVariantId | Cadeia(16) | Não | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de variante de item. | |
| ImageFullUrl | Cadeia(2048) | Sim | Entrada de largada | Tem de ser um URL absoluto. O URL deve estar codificado corretamente (utilizando a codificação de percentagem). Comprimento limitado a 2048 carateres. | |
| IsPrimaryImage | Bool | Sim | Ver diretrizes | Consulte Entidades de dados obrigatórias por cenário de recomendações para valores booleanos. |
Diretrizes:
Tem de atribuir explicitamente imagens a um ItemId e a cada ItemVariantId relevante. As imagens atribuídas a um item não são atribuídas automaticamente a todas as variantes de item e vice-versa. As imagens atribuídas a uma variante de item não são atribuídas automaticamente ao item mestre dessa variante.
Se for especificada mais do que uma imagem principal para a mesma combinação de <ItemId, ItemVariantId>, apenas uma destas imagens será utilizada para o passo de inferência de recomendações visuais e as outras serão utilizadas apenas quando preparar todo o modelo visual.
Para qualquer imagem a que o Intelligent Recommendations não tenha conseguido aceder, o URL de imagem é ignorado e não será utilizado para o modelo de recomendação.
Se o valor de IsPrimaryImage for inválido, será utilizado um valor false (por exemplo, imagem não primária).
Se apenas foram especificadas imagens não primárias para uma variante de item ou item, o Intelligent Recommendations utiliza uma das imagens especificadas como a imagem primária para ainda assim fornecer recomendações visuais para esse item ou variante de item.
Existem dois tipos de URLs suportados:
- URLs HTTPS publicamente disponíveis: não requerem um cabeçalho de Autorização. Este URL não inclui URLs de blobs do Azure disponíveis publicamente/anónimos, que não são suportados.
-
URLs de armazenamento de blobs do Azure que requerem autenticação: não estão disponíveis publicamente/de forma anónima. As permissões para leitura de blobs de imagem devem ser concedidas ao Intelligent Recommendations, como explicado em Implementar o Intelligent Recommendations. Os URLs de blobs têm de começar pelo prefixo:
https://<StorageAccountName>.blob.core.windows.net/.
O tamanho máximo suportado para uma única imagem é 512 KB. Qualquer imagem com mais de 512 KB será ignorada pelo sistema.
O ContentType para a imagem tem de ter um tipo de conteúdo de imagem (deve começar por imagem). Este requisito aplica-se a todas as imagens, disponíveis através de HTTPS e blobs de imagem (através da propriedade ContentType do blob).
Dados de amostra:
Os cabeçalhos aparecem apenas para comodidade e não devem fazer parte dos dados reais.
| ItemId | ItemVariantId | ImageFullUrl | IsPrimaryImage |
|---|---|---|---|
| Item1 | https://my.server.org/images/Item1_primary.jpg |
True | |
| Item1 | https://my.server.org/images/Item1_secondary.jpg |
False | |
| Item1 | Item1Var1 | https://my.server.org/images/Item1Var1.jpg |
True |
| Item2 | https://my.server.org/images/Item2.jpg |
True |
Regressar à lista de tipos de entidade de catálogo
Filtros de itens e variantes
Nome da entidade de dados:Reco_ItemAndVariantFilters
Descrição: propriedades de variante de item e item utilizadas para filtragem de resultados em runtime
Atributos:
| Name | Tipo de dados | Obrigatório | Default value | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | Cadeia(16) | Sim | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de item. | |
| ItemVariantId | Cadeia(16) | Não | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de variante de item. | |
| FilterName | Cadeia(64) | Sim | Cortar valor | ||
| FilterValue | Cadeia(64) | Sim | Cortar valor | Comprimento limitado a 64 carateres. | |
| FilterType | Cadeia (de carateres) | Sim | Entrada de largada | Os valores possíveis incluem: Textual, Numérico. |
Diretrizes:
Os itens e as variantes de item têm uma relação principal-subordinado. Esta diretriz significa que as variantes de item herdarão os filtros do respetivo item mestre. Por exemplo, se o filtro "Cor" tiver sido declarado para um determinado ItemId, todas as variantes de item do mesmo ItemId obtêm o mesmo valor de filtro "Cor", a menos que tenha sido especificado um valor de "Cor" diferente para a variante de item.
Os tipos de filtro textual suportam a operação de filtragem "é igual a". Por exemplo, os pedidos de API podem filtrar itens com "Cor"="Azul".
Os tipos de filtro numérico suportam operações de filtragem de "intervalo". Por exemplo, os pedidos de API podem filtrar itens com "Tamanho" > 40.
Pode atribuir vários valores de filtro ao mesmo filtro. Por exemplo, para o filtro "Cor", pode fornecer vários valores, como "Verde" e "Azul". Neste exemplo, o item relevante tem dois valores para o filtro "Cor" e será devolvido quando filtrar itens "Verde" ou "Azul". Para atribuir vários valores ao mesmo filtro, adicione uma entrada para cada valor de filtro que pretende atribuir utilizando os mesmos valores de FilterName e FilterType.
Para cada FilterName, uma variante de item pode herdar ou substituir os valores de filtro do respetivo principal. Unir os dois não é suportado. Por predefinição, se a variante não tiver valores atribuídos a um filtro, herda os valores de filtro do item principal. Se, pelo menos, um valor de filtro estiver atribuído a um filtro para uma variante de item, o modo de substituição é ativado e apenas os valores de filtro de variante estão em vigor (só para o filtro específico). Este valor significa que para obter um comportamento de "unir", a variante de item tem de repetir os valores de filtro principal. Por exemplo, um item suporta duas cores, Azul e Verde. Se uma variante suportar outra cor, Vermelho, a variante tem de listar as três cores atribuídas ao ID da variante: Azul, Verde e Vermelho. Neste exemplo, a variante de item substituiu os valores do filtro "Cor", mas pode ainda herdar os valores de outros filtros do respetivo item principal.
As entradas com tipos de filtro não suportados serão ignoradas.
Pode fornecer até 20 FilterName diferentes.
Fornecer várias entradas com o mesmo FilterName, mas com um FilterType diferente irá falhar o processo de ingestão de dados do Intelligent Recommendations.
Os itens ou as variantes de item não podem ter filtros especificados. Se especificar qualquer filtro no pedido de API, os itens ou as variantes de item sem o filtro especificado serão filtrados.
Dados de amostra:
Os cabeçalhos aparecem apenas para comodidade e não devem fazer parte dos dados reais.
| ItemId | ItemVariantId | FilterName | FilterValue | FilterType |
|---|---|---|---|---|
| Item1 | Color | Vermelho | Textual | |
| Item1 | Item1Var1 | Color | Bordô | Textual |
| Item1 | Item1Var2 | Estilo | Retangular | Textual |
| Item2 | Size | 38 | Numérico | |
| Item2 | Color | Azul | Textual | |
| Item2 | Color | Verde | Textual |
Regressar à lista de tipos de entidade de catálogo
Disponibilidades de itens e variantes
Nome da entidade de dados:Reco_ItemAndVariantAvailabilities
Descrição: todas as disponibilidades de item e variante de item
Atributos:
| Name | Tipo de dados | Obrigatório | Default value | Comportamento de valor inválido | Comentários |
|---|---|---|---|---|---|
| ItemId | Cadeia(16) | Sim | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de item. | |
| ItemVariantId | Cadeia(16) | Não | Entrada de largada | Consulte Entidades de dados obrigatórias por cenário de recomendações para ID de variante de item. | |
| StartDate | DateTime | Não | 0001-01-01T00:00:00.000Z | Ver diretrizes | Consulte Entidades de dados obrigatórias por cenário de recomendações para valores de DateTime. |
| EndDate | DateTime | Não | 9999-12-31T23:59:59.999Z | Ver diretrizes | Consulte Entidades de dados obrigatórias por cenário de recomendações para valores de DateTime. |
| Atributo Duplo | Duplo | Não | Um atributo duplo que pode ser utilizado de acordo com as necessidades empresariais e que não afeta o processo de modelação. | ||
| Canal | Cadeia(64) | Não | 0 | Cortar valor | Comprimento limitado a 64 carateres. |
| Catálogo | Cadeia(64) | Não | 0 | Cortar valor | Comprimento limitado a 64 carateres. |
Diretrizes:
Lembrete: as disponibilidades dizem ao sistema que itens ou variantes de item são considerados candidatos aos resultados de recomendações.
A disponibilidade de uma variante de item é a união de disponibilidades do seu item mestre, com a disponibilidade da própria variante do item. Mesmo as variantes de item que não tenham entradas herdam as disponibilidades do item mestre.
Um item que está em falta desta entidade de dados será considerado como sempre disponível no canal predefinido e no catálogo. Especificamente, o Intelligent Recommendations agem exatamente como se esse item aparecesse nos dados com valores predefinidos para todos os atributos.
ItemIds tem uma relação um-para-muitos com ItemVariantIds. Apesar de não ser obrigatório que um ItemId tenha um ItemVariantId, é possível que mais do que um ItemVariantId possa ser mapeado para um único ItemId. Por exemplo, pode adicionar uma entrada para uma combinação ItemId e ItemVariantId específica sem também adicionar explicitamente outra entrada para o ItemId (e um ItemVariantId vazio). Ao determinar se as variantes de item têm disponibilidades válidas, apenas as variantes de item especificadas são consideradas como disponíveis (a intervalos de tempo especificados por cada variante).
Um catálogo só é relevante no contexto de um canal (Os catálogos são um subconjunto de canal). Por exemplo, catálogo=MySale em canal=Europa é um catálogo diferente de catálogo=MySale em canal=Ásia.
Se o conjunto de dados contiver múltiplos canais e catálogos, tem de adicionar uma entrada para cada combinação de canal e catálogo relevante para cada variante de item e item relevante.
As datas de disponibilidade são relevantes apenas para o canal e o catálogo especificados. Se pretender especificar as mesmas datas de disponibilidade para diferentes canais e catálogos, terá de adicionar explicitamente uma entrada para cada canal e catálogo.
Se houver um valor inválido para qualquer um dos atributos StartDate ou EndDate, toda a entrada é modificada para representar um item não disponível. Os valores StartDate e EndDate são substituídos pelos valores DateTime que estão no passado.
O "Atributo Duplo" pode ficar vazio.
Não utilize "0" como valor para "Canal". Este valor está reservado para o sistema. A utilização de "0" irá resultar num erro de processamento.
Dados de amostra:
Os cabeçalhos aparecem apenas para comodidade 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 |
Regressar à lista de tipos de entidade de catálogo
Consulte também
Descrição geral do contrato de dados
Tabela de mapeamento de entidades de dados
Entidades de dados de interações
Entidades de dados de configuração de recomendações
Entidades de dados de utilizadores que optaram ativamente por não participar
Entidades de dados de listas externas
Entidades de dados de melhoramento de recomendações
Entidades de dados de mapeamento de imagem para item
API do Intelligent Recommendations
Guia de Início Rápido: Configurar e executar o Intelligent Recommendations com dados de amostra