Entidades de datos de catálogo
En este artículo se proporcionan instrucciones sobre cómo configurar de entidades de datos de catálogo en el contrato de datos de Intelligent Recommendations.
Revisión de entidades de datos
Una entidad de datos es un conjunto de uno o más archivos de texto de datos, cada uno con una lista de columnas (también llamadas atributos) y filas que contienen los valores de datos reales.
Intelligent Recommendations define grupos lógicos de entidades de datos, cada uno con su propio propósito.
Nota
Las entidades de datos se consideran opcionales, a menos que se indique explícitamente lo contrario, lo que significa que sus datos pueden estar vacíos o faltar.
Volver a la lista completa de entidades de datos
Introducción a las entidades de datos de catálogo
La entidad de datos de catálogo representa todos los artículos y variantes de artículos que son candidatos para aparecer en resultados de recomendaciones. Los candidatos se determinan aplicando disponibilidades a artículos, una fecha que le indica al sistema que incluya un artículo en los resultados de las recomendaciones. Sin una disponibilidad válida, los artículos se ignorarán cuando se devuelvan los resultados.
Intelligent Recommendations admite las siguientes características y escenarios:
Artículos con múltiples variaciones (por ejemplo, una camisa en diferentes tamaños o colores) o ninguna variación. Nos referimos a estas variaciones como variantes. Los artículos que no tienen variantes se denominan artículos independientes, mientras que los artículos que tienen al menos una variante se denominan maestros de artículos.
Asignación de valores de filtro a artículos (por ejemplo, categoría, color o tamaño). Más adelante, al consultar recomendaciones, puede filtrar por estos valores de filtro.
Asignación de imágenes a los artículos.
Los artículos pueden estar disponibles dentro de diferentes entidades lógicas en la organización. Intelligent Recommendations admite dos niveles de jerarquías:
Canal : los artículos se pueden asignar a un canal, lo que permite que Intelligent Recommendations proporcione recomendaciones con alcance solo a productos incluidos en un canal específico. Todos los artículos se asocian automáticamente con el canal predeterminado, que utiliza la cadena 0 (cero) como id. de canal reservado.
Ejemplo:
En este ejemplo, el conjunto de datos contiene solo tres artículos: X, Y y Z. Estos tres artículos se asignan automáticamente al canal predeterminado (Canal=0). También puede asignar estos artículos a sus propios canales personalizados. Por ejemplo, puede asignar artículos X e Y a Canal=C1 y los artículos Y y Z a Canal=C2.
Entonces, al solicitar recomendaciones, puede pasar estos otros parámetros de consulta:
- Sin parámetro de canal (es igual al canal predeterminado): los tres artículos se pueden devolver en la respuesta
- Canal=0: igual que ningún parámetro, ya que este es el canal predeterminado
- Canal=C1: solo los artículos que pertenecen al canal C1 (artículos X e Y) pueden devolverse en la respuesta
- Canal=C2: solo los artículos que pertenecen al canal C2 (artículos Y y Z) pueden devolverse en la respuesta
- Canal=SomethingElse: respuesta vacía porque este canal no se definió y no se le asignaron artículos
Catálogo: un catálogo es otro nivel más fino de granularidad de disponibilidad. Le permite definir múltiples catálogos dentro de un canal y obtener recomendaciones para catálogos específicos. De forma similar a los canales, todos los artículos se asocian automáticamente con el catálogo predeterminado de un canal, que utiliza la cadena 0 (cero) como id. de catálogo reservado.
Ejemplo:
Continuando con el ejemplo Canal, tiene artículos X, Y y Z. Asignó artículos X e Y al canal C1, y se asignan automáticamente al catálogo predeterminado en el canal (usando Catálogo=0). Puede tener mayor granularidad asignando estos artículos a catálogos personalizados dentro del canal. Vamos a asignar el artículo X a Catálogo=A y los artículos X e Y a Catálogo=B.
Entonces, al solicitar recomendaciones, puede pasar estos otros parámetros de consulta:
- Canal=C1: sin parámetros de catálogo, es igual al catálogo predeterminado. Ambos artículos X e Y se pueden devolver en la respuesta.
- Channel=C1&Catalog=0: igual que ningún parámetro de catálogo, porque este es el catálogo predeterminado.
- Channel=C1&Catalog=A: solo los artículos que pertenecen al catálogo A en el canal C1 (solo artículo X) pueden devolverse en la respuesta.
- Channel=C1&Catalog=B: solo los artículos que pertenecen al catálogo B en el canal C1 (artículos X e Y) pueden devolverse en la respuesta.
- Channel=C1&Catalog=SomethingElse: respuesta vacía porque este catálogo no se definió en el canal C1 y no se le asignaron artículos.
Declarar disponibilidades de artículos:
- Fechas de inicio/fin de disponibilidad: los artículos que estén fuera de su intervalo de tiempo de disponibilidad serán excluidos de la respuesta de recomendación.
- Granularidad fina de disponibilidad: define las fechas de inicio/finalización dentro de los id. de catálogo/canal específicos.
El catálogo se compone de varias entidades de datos, todas opcionales (según las características que desee utilizar), y pueden permanecer vacías (o faltar) en la carpeta raíz de Intelligent Recommendations. Siga las pautas de la entidad de datos Reco_ItemsAndVariants, que se describe a continuación, si no desea proporcionar esta entidad de datos.
Lista de entidades de datos de catálogo
Las siguientes entidades de datos forman parte del catálogo:
- Artículos y variantes
- Categorías producto
- Imágenes de artículos y variantes
- Filtros de artículos y variantes
- Disponibilidades de artículos y variantes
Volver a la lista completa de entidades de datos
Artículos y variantes
Nombre de la entidad de datos:Reco_ItemsAndVariants
Descripción: Todos los artículos y variantes de artículos
Atributos:
| Name | Tipo de datos | Obligatorio | Default value | Comportamiento de valor no válido | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | Sí | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. del artículo. | |
| ItemVariantId | String(16) | No | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. de variante de artículo. | |
| Nombre | String(256) | No | Valor de ajuste | Longitud limitada a 256 caracteres. | |
| Descripción | String(2048) | No | Valor de ajuste | Longitud limitada a 2048 caracteres. | |
| ReleaseDate | Fecha y hora | No | 1970-01-01T00:00:00.000Z | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para valores de DateTime. |
Directrices:
Las variantes de artículos heredan los atributos de su artículo maestro. Por ejemplo, si una variante de artículo no tiene título, hereda el título de su artículo maestro (es decir, la fila con el mismo ItemId pero con un ItemVariantId vacío), si existiera.
ItemIds puede tener una relación de uno a varios con ItemVariantIds. Es posible que un único ItemId esté asignado a más de un ItemVariantId para capturar la relación de un artículo maestro con sus variantes de artículos. Es posible tener una sola entrada para una determinada combinación de ItemId e ItemVariantId sin especificar otras combinaciones ItemId a ItemVariantId.
El atributo ReleaseDate representa la fecha en la que el artículo se lanzó (publicado, introducido) en el mercado. Esto es diferente de la disponibilidad de un artículo (cuando un artículo/producto se puede devolver en una llamada API), pero ReleaseDate podría usarse en escenarios como Nuevo y Tendencias, que se basan en fechas para pedir artículos.
Si esta entidad de datos está vacía (o falta), Intelligent Recommendations utilizará automáticamente todos los artículos y variantes de artículos que se encuentran en la entidad de datos Reco_Interacciones como conjunto de artículos del catálogo y asignará a cada artículo y variante de artículo el título, la descripción y la fecha de lanzamiento predeterminados. Estos artículos serán considerados como siempre disponible a menos que se les hayan asignado disponibilidades explícitas en la entidad de datos Reco_ItemAndVariantAvailabilities.
Las Intelligent Recommendations puede utilizar los atributos Title y Description para proporcionar recomendaciones basadas en texto. Debido a que Intelligent Recommendations actualmente solo admite la configuración regional en-us para recomendaciones textuales, Title y Description en cualquier otra configuración regional podrían degradar la calidad de las recomendaciones textuales.
Datos de ejemplo:
Los encabezados aparecen solo por conveniencia y no deben ser parte de los datos reales.
| ItemId | ItemVariantId | Nombre | Descripción | ReleaseDate |
|---|---|---|---|---|
| Item1 | 2018-05-15T13:30:00.000Z | |||
| Item1 | Item1Var1 | Gafas de sol negras | Gafas de sol negras para niños | 2018-08-01T10:45:00.000Z |
| Item1 | Item1Var2 | Gafas de sol marrones | Gafas de sol marrones para adultos | |
| Item2 | Paño de limpieza de gafas | 2019-09-20T18:00:00.000Z | ||
| Item3 | Item3Var1 |
Volver a la lista de entidades de datos de catálogo
Categorías producto
Nombre de la entidad de datos:Reco_ItemCategories
Descripción: todas las categorías de artículos.
Atributos:
| Name | Tipo de datos | Obligatorio | Default value | Comportamiento de valor no válido | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | Sí | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. del artículo. | |
| Category | String(64) | Sí | Valor de ajuste | Longitud limitada a 64 caracteres. |
Directrices:
Cada ItemId puede tener múltiples categorías, lo que significa que puede aparecer en múltiples entradas en los datos.
Si sus datos se construyen utilizando árboles de categorías, deberá proporcionar el conjunto completo de categorías (aplanadas) para cada artículo.
Datos de ejemplo:
Los encabezados aparecen solo por conveniencia y no deben ser parte de los datos reales.
| ItemId | Category |
|---|---|
| Item1 | Category1 |
| Item1 | Category1_subCategoryX |
| Item1 | Category1_subCategoryY |
| Item2 | Category1_subCategoryX |
Volver a la lista de entidades de datos de catálogo
Imágenes de artículos y variantes
Nombre de la entidad de datos:Reco_ItemAndVariantImages
Descripción: Todas las imágenes de artículos y variantes de artículos
Atributos:
| Name | Tipo de datos | Obligatorio | Default value | Comportamiento de valor no válido | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | Sí | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. del artículo. | |
| ItemVariantId | String(16) | No | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. de variante de artículo. | |
| ImageFullUrl | String(2048) | Sí | Anular entrada | Debe ser una URL absoluta. La URL debe estar codificada correctamente (usando codificación porcentual). Longitud limitada a 2048 caracteres. | |
| IsPrimaryImage | Booleano | Sí | Ver directrices | Vea Entidades de datos requeridas por escenario de recomendaciones para valores booleanos. |
Directrices:
Debe asignar imágenes explícitamente a un ItemId y a cada ItemVariantId relevante. Las imágenes asignadas a un artículo no se asignan automáticamente a todas las variantes del artículo y viceversa. Las imágenes asignadas a una variante de artículo no se asignan automáticamente al artículo maestro de la variante.
Si se especifica más de una imagen primaria para la misma combinación <ItemId, ItemVariantID>, solo una de estas imágenes se usará para el paso de inferencia de recomendaciones visuales, y las otras se usarán solo cuando se entrene todo el modelo visual.
Para cualquier imagen a la que Intelligent Recommendations no haya podido acceder, la URL de la imagen se ignorará y no se usará para el modelo de recomendación.
Si el valor IsPrimaryImage no es válido, un valor false se utilizará (por ejemplo, imagen no primaria).
Si solo se especificaron imágenes no primarias para un artículo o variante de artículo, Intelligent Recommendations usará una de las imágenes especificadas como imagen primaria para seguir brindando recomendaciones visuales para ese artículo o variante de artículo.
Hay dos tipos de URL admitidas:
- URL HTTPS disponibles públicamente: no requiere un encabezado de Autorización. Esto no incluye las direcciones URL de los blobs de Azure que están disponibles de forma pública/anónima, que no son compatibles.
-
URL de Azure Blob Storage que requieren autenticación: no están disponibles de forma pública/anónima. Los permisos para leer los blobs de imágenes se deben otorgar a Intelligent Recommendations, como se explica en Implementar Intelligent Recommendations). Las URL de blobs deben comenzar con el prefijo:
https://<StorageAccountName>.blob.core.windows.net/.
El tamaño máximo admitido de una única imagen es 512 KB. El sistema ignorará cualquier imagen de más de 512 KB.
El ContentType para la imagen debe tener un tipo de contenido de imagen (debe comenzar con imagen). Este requisito se aplica a todas las imágenes, tanto disponibles a través de HTTPS como blobs de imágenes (a través de la propiedad del blob ContentType).
Datos de ejemplo:
Los encabezados aparecen solo por conveniencia y no deben ser parte de los datos reales.
| ItemId | ItemVariantId | ImageFullUrl | IsPrimaryImage |
|---|---|---|---|
| Item1 | https://my.server.org/images/Item1_primary.jpg |
VERDADERO | |
| Item1 | https://my.server.org/images/Item1_secondary.jpg |
False | |
| Item1 | Item1Var1 | https://my.server.org/images/Item1Var1.jpg |
VERDADERO |
| Item2 | https://my.server.org/images/Item2.jpg |
VERDADERO |
Volver a la lista de tipos de entidades de catálogo
Filtros de artículos y variantes
Nombre de la entidad de datos:Reco_ItemAndVariantFilters
Descripción: propiedades de artículos y variantes de artículos utilizadas para el filtrado de resultados en tiempo de ejecución
Atributos:
| Name | Tipo de datos | Obligatorio | Default value | Comportamiento de valor no válido | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | Sí | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. del artículo. | |
| ItemVariantId | String(16) | No | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. de variante de artículo. | |
| FilterName | String(64) | Sí | Valor de ajuste | ||
| FilterValue | String(64) | Sí | Valor de ajuste | Longitud limitada a 64 caracteres. | |
| FilterType | String | Sí | Anular entrada | Los posibles valores incluyen: Textual, Numérico. |
Directrices:
Los artículos y las variantes de artículos tienen una relación primario-secundario. Esta directriz significa que las variantes de artículos heredarán los filtros de su maestro de artículos. Por ejemplo, si se declaró el filtro “Color” para un determinado ItemId, todas las variantes de artículo del mismo ItemId obtendrán el mismo valor de filtro “Color”, a menos que se haya especificado un valor de “Color” diferente para la variante del artículo.
Los tipos de filtros textuales admiten la operación de filtrado "igual". Por ejemplo, las solicitudes de API pueden filtrar artículos con "Color"="Blue".
Los tipos de filtros numéricos admiten operaciones de filtrado de "rango". Por ejemplo, las solicitudes de API pueden filtrar artículos con "Tamaño" > 40.
Puede asignar varios valores de filtro al mismo filtro. Por ejemplo, para el filtro "Color", puede proporcionar varios valores, como "Verde" y "Azul". En este ejemplo, el artículo relevante tendrá dos valores para el filtro "Color" y se devolverá cuando filtre por artículos "Verdes" o artículos "Azules". Para asignar varios valores al mismo filtro, agregue una entrada para cada valor de filtro que desee asignar, utilizando los mismos valores FilterName y FilterType.
Para cada FilterName, una variante de artículo puede heredar sus valores de filtro primario o anularlos. La fuión de ambos no se admite. De forma predeterminada, si la variante no tiene valores asignados a un filtro, heredará los valores de filtro del artículo primario. Si se asigna al menos un valor de filtro a un filtro para una variante de artículo, el modo de anulación se activa y solo los valores de filtro de variante son efectivos (solo para el filtro específico). Este valor significa que para lograr un comportamiento de "combinación", la variante del artículo debe repetir sus valores de filtro primarios. Por ejemplo, un artículo admite dos colores, Azul y Verde. Si una variante admite otro color, Rojo, entonces la variante debe enumerar los tres colores asignados al id. de variante: Azul, Verde y Rojo. En este ejemplo, la variante del artículo anuló los valores del filtro "Color", pero aún puede heredar los valores de otros filtros de su artículo principal.
Se ignorarán las entradas con tipos de filtro no admitidos.
Puede proporcionar hasta 20 FilterName diferentes.
Proporcionar múltiples entradas con el mismo FilterName pero diferente FilterType hará fallar el proceso de ingestión de datos de Intelligent Recommendations.
Los artículos o variantes de artículos no pueden tener filtros especificados. Si especifica cualquier filtro en la solicitud de la API, se filtrarán los elementos o variantes de elementos sin el filtro especificado.
Datos de ejemplo:
Los encabezados aparecen solo por conveniencia y no deben ser parte de los datos reales.
| ItemId | ItemVariantId | FilterName | FilterValue | FilterType |
|---|---|---|---|---|
| Item1 | Color | Rojo | Textual | |
| Item1 | Item1Var1 | Color | Borgoña | Textual |
| Item1 | Item1Var2 | Estilo | Rectangular | Textual |
| Item2 | Size | 38 | Numérico | |
| Item2 | Color | Azul | Textual | |
| Item2 | Color | Verde | Textual |
Volver a la lista de tipos de entidades de catálogo
Disponibilidades de artículos y variantes
Nombre de la entidad de datos:Reco_ItemAndVariantAvailabilities
Descripción: todas las disponibilidades de artículos y variantes de artículos
Atributos:
| Name | Tipo de datos | Obligatorio | Default value | Comportamiento de valor no válido | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | Sí | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. del artículo. | |
| ItemVariantId | String(16) | No | Anular entrada | Vea Entidades de datos requeridas por escenario de recomendaciones para conocer el id. de variante de artículo. | |
| StartDate | Fecha y hora | No | 0001-01-01T00:00:00.000Z | Ver directrices | Vea Entidades de datos requeridas por escenario de recomendaciones para valores de DateTime. |
| Fecha de finalización | Fecha y hora | No | 9999-12-31T23:59:59.999Z | Ver directrices | Vea Entidades de datos requeridas por escenario de recomendaciones para valores de DateTime. |
| Atributo doble | Doble | No | Un doble atributo que puede ser utilizado según las necesidades del negocio y no afecta el proceso de modelado. | ||
| Canal | Cadena (64) | No | 0 | Valor de ajuste | Longitud limitada a 64 caracteres. |
| Catálogo | String (64) | No | 0 | Valor de ajuste | Longitud limitada a 64 caracteres. |
Directrices:
Recordatorio: disponibilidades indica al sistema qué artículos o variantes de artículos se consideran candidatos para resultados de recomendaciones.
La disponibilidad de una variante de artículo es la unión de las disponibilidades de su artículo maestro con la disponibilidad de la propia variante de artículo. Incluso las variantes de artículos que no tienen entradas, heredarán sus disponibilidades de artículos maestros.
Un artículo que falta en esta entidad de datos se considerará siempre disponible en el canal y catálogo predeterminados. Más específicamente, Intelligent Recommendations se comportará exactamente como si ese artículo apareciera en los datos con valores predeterminados para todos los atributos.
ItemIds tiene una relación de uno a varios con ItemVariantIds. Mientras un ItemId no se requiere para tener un ItemVariantId, es posible que más de un ItemVariantId se pueda asignar a un solo ItemId. Por ejemplo, puede agregar una entrada para una combinación de ItemId e ItemVariantId sin agregar también explícitamente otra entrada para el ItemId Id (y un ItemVariantId vacío). Para determinar si las variantes de artículos tienen disponibilidades válidas, solo las variantes de artículos especificadas se considerarán disponibles (en los intervalos de tiempo especificados para cada variante).
Un catálogo sólo es relevante en el contexto de un canal (los catálogos son un subconjunto del canal). Por ejemplo, catálogo=MySale en canal=Europa es un catálogo diferente a catálogo=MySale en canal=Asia.
Si su conjunto de datos contiene varios canales y catálogos, deberá agregar una entrada para cada combinación de canal y catálogo relevante para cada artículo y variante de artículo relevantes.
Las fechas de disponibilidad solo son relevantes para el canal y el catálogo específicos especificados. Si desea especificar las mismas fechas de disponibilidad para diferentes canales y catálogos, deberá agregar explícitamente una entrada para cada canal y catálogo.
Si hay un valor no válido para cualquiera de los atributos StartDate o EndDate, toda la entrada se modificará para representar un artículo no disponible. Los valores de StartDate y EndDate se anularán con valores Fecha y hora que están en el pasado.
El 'Atributo doble' se puede dejar vacío.
No utilice "0" como valor para "Canal". Este valor está reservado para el sistema. El uso de "0" dará lugar a un error de procesamiento.
Datos de ejemplo:
Los encabezados aparecen solo por conveniencia y no deben ser parte de los datos reales.
| ItemId | ItemVariantId | StartDate | Fecha de finalización | Atributo doble | 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 |
Volver a la lista de tipos de entidades de catálogo
Consulte también
Descripción general del contrato de datos
Tabla de asignación de entidades de datos
Entidades de datos de interacciones
Entidades de datos de usuarios de baja
Entidades de datos de configuración Reco
Entidades de datos de listas externas
Entidades de datos de enriquecimiento de recomendaciones
Entidades de datos de asignación de imagen a elemento
API de Intelligent Recommendations
Guía de inicio rápido: configfurar y ejecutar Intelligent Recommendations con datos de ejemplo