Información general del contrato de datos
Este artículo explica cómo compartir datos con Intelligent Recommendations, para que pueda habilitarlos y proporcionar recomendaciones significativas.
La API de Intelligent Recommendations correspondiente a los contratos de datos descritos es API de Intelligent Recommendations.
Descargue el archivo model.json más reciente para contratos de datos de Intelligent Recommendations: modelo.json.
Requisitos previos
Para la integración de datos, Intelligent Recommendations utiliza Microsoft Azure Data Lake Storage. Este artículo describe la estructura lógica de los datos que Intelligent Recommendations espera utilizar de su cuenta de Azure Data Lake Storage.
Para permitir que Intelligent Recommendations encuentre fácilmente sus datos en la cuenta de Azure Data Lake Storage, debe crear una carpeta dedicada dentro de la cuenta de Azure Data Lake Storage y proporcionar la ruta de la carpeta (carpeta raíz de Intelligent Recommendations) a Intelligent Recommendations.
Para obtener información sobre cómo incorporar y crear su cuenta de Data Lake Storage, vaya a Implementar Intelligent Recommendations o visite nuestra Guía de inicio rápido.
Contratos de datos
Contratos de datos es un conjunto de definiciones y restricciones para la estructura de los datos que utiliza Intelligent Recommendations. Para permitir que Intelligent Recommendations ingiera los datos compartidos con él y ofrezca recomendaciones, debe cumplir con los contratos de datos como se describe en este artículo.
Archivo de modelo JSON
Los contratos de datos de Intelligent Recommendations se dividen lógicamente en un conjunto de entidades de datos. Cada entidad de datos comprende cero o más archivos CSV de entrada, que también se denominan particiones. Un archivo de texto JSON independiente llamado model.json describe el conjunto de entidades de datos. El archivo JSON del modelo viene preconfigurado y se puede agregar inmediatamente a la carpeta raíz de Intelligent Recommendations.
Descargar el modelo predeterminado
Descargue el último archivo JSON de modelo predeterminado para contratos de datos de Intelligent Recommendations: model.json.
[!NOTA]
Es necesario incluir el archivo model.json en la carpeta raíz de Intelligent Recommendations, además de los archivos de entidad de datos. Puede obtener información sobre cómo realizar ajustes en el model.json en la sección Modificar el archivo predeterminado de este Contrato de datos.
Modificar el archivo predeterminado
No se recomienda modificar el archivo JSON del modelo proporcionado hasta que se familiarice con el servicio de Intelligent Recomendations y solo cuando utilice una de las siguientes características:
Formato de entradas numéricas. El atributo cultura especifica qué utiliza Intelligent Recommendations como formato de entrada para los valores numéricos. El separador decimal puede ser un punto (.) o coma (,) en diferentes culturas. Para utilizar un separador decimal que no sea un punto (.), especifique la cultura adecuada en el atributo cultura.
Nota
Si estás usando una coma (,) como separador decimal, deberá señalar correctamente cada valor decimal en el archivo CSV de entrada. Para obtener más información sobre cómo señalar caracteres en los archivos de entrada CSV, vaya a la sección Formato de datos.
Ubicaciones de particiones explícitas. Para especificar ubicaciones explícitas de los archivos de partición de entidad de datos, puede utilizar el atributo particiones. Por defecto, el valor del atributo particiones es nulo, lo que significa que Intelligent Recommendations busca automáticamente los archivos de partición de entidad de datos relevantes. Para más información, vaya a Formato de datos. El atributo particiones es una matriz de particiones. Cada partición contiene los siguientes atributos:
- nombre: una representación de cadena de la partición, no utilizada por Intelligent Recommendations para ninguna lógica específica.
- ubicación: URI completo de la partición para el archivo de datos de partición (CSV). El URI debe ser accesible para Intelligent Recommendations (solo lectura), lo que puede requerir que proporcione los permisos adecuados para Intelligent Recommendations. Para obtener más información sobre cómo otorgar a Intelligent Recommendations acceso a los datos, vaya a Configurar Azure Data Lake Storage.
- fileFormatSettings: contiene el atributo siguiente:
- columnsHeaders: un valor booleano que especifica si los datos de la partición contienen una línea de encabezado. Intelligent Recommendations descarta automáticamente las líneas de encabezados cuando se ingieren los datos de entrada. El valor predeterminado es false, lo que significa que no hay encabezados.
Aquí hay una muestra del atributo partitions:
"partitions": [
{
"name": "Partition1",
"location": "https://myStorageAcount.blob.core.windows.net/intelligent-recommnedations-container/intelligent-recommendations-root-folder/partition1.csv",
"fileFormatSettings": {
"columnHeaders": true
}
}
]
Prácticas recomendadas para actualizar los datos de entrada
Evite una situación en la que los datos se modelen y actualicen al mismo tiempo, ya que puede generar el modelado de datos de versiones mixtas de conjunto de datos y resultados de recomendación no deseados. Algunas mejores prácticas para actualizar sus datos de entrada son las siguientes:
- Escriba todas las entidades de datos en una carpeta diferente. Esta carpeta no tiene que estar ubicada en el mismo contenedor o cuenta de almacenamiento en la que se encuentran sus datos de entrada actuales. Asegúrese de proporcionar permisos de recomendación inteligente para leer datos del contenedor de sus datos de entrada actualizados. Para más información, vaya a Configurar Azure Data Lake Storage.
- Para cada una de las entidades de datos que está utilizando, agregue el atributo 'particiones' a su archivo Model Json. Para cada partición, actualice el atributo 'ubicación' para que apunte a la nueva ubicación de datos. Puede encontrar una explicación sobre cómo agregar y editar el atributo 'particiones' aquí
- Puede eliminar los datos antiguos si ya no están en uso. Recomendamos eliminar los datos antiguos después de la duración estimada del ciclo de modelado (al menos 36 horas), con algo de búfer para evitar que se eliminen los datos mientras se modelan.
- Repita los pasos 1-3 cada vez que desee actualizar sus datos de entrada.
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. 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 por completo).
Intelligent Recommendations define los siguientes grupos de entidades de datos:
Formato de datos
Intelligent Recommendations espera que todos los archivos de entrada de partición de entidades de datos se ajusten al siguiente formato:
El contenido dentro del archivo de entrada de la partición debe estar en formato de archivos de texto delimitado por comas (CSV), usando solo texto codificado UTF-8.
Cada archivo CSV debe incluir todos los campos especificados en el contrato de datos de la entidad de datos relevante. Además, los campos deben mostrarse de acuerdo con el orden descrito en ese contrato.
Los archivos CSV deben contener solo entradas de datos, de acuerdo con RFC 4180.
Estos son algunos ejemplos comunes del comportamiento del formato de datos CSV en diferentes casos:
Cada campo puede o no estar encerrado entre comillas dobles.
Por ejemplo: aaa, "bbb", ccc
Los campos que contienen saltos de línea (CRLF), comillas dobles y comas deben estar entre comillas dobles.
Por ejemplo: aaa, “bbCRLFb”, “c, cc”
Una marca de comillas dobles que aparece dentro de un campo deben señalarse precediéndolas de otras comillas dobles.
Por ejemplo: aaa, “b””bb”, ccc
En el caso de que no haya declarado explícitamente el atributo particiones (en el archivo de modelo JSON) para una entidad de datos, Intelligent Recommendations busca los archivos de partición de la entidad de datos dentro de una subcarpeta (en la carpeta raíz de Intelligent Recommendations) que tenga el mismo nombre que la entidad de datos.
En este caso, todos los archivos de entrada de partición dentro de la subcarpeta de entidad de datos deben tener una extensión de archivo CSV, como MyData.csv y no deben contener línea de datos de encabezados.
Intelligent Recommendations busca y agrega datos de todos los archivos que usan la extensión CSV, mientras ignora el nombre del archivo en sí.
Ejemplo de estructura de carpetas de Intelligent Recommendations
Aquí hay un ejemplo de captura de pantalla de una estructura de carpeta raíz de Intelligent Recommendations. No es necesario que los CSV coincidan con los nombres de las carpetas:
Entidades de datos requeridas para cada escenario de recomendaciones
Los escenarios de recomendaciones pueden basarse en diferentes entidades de datos para funcionar correctamente. Para ver una tabla completa de asignación de escenarios y entidades de datos, consulte nuestra Tabla de asignación de entidades de datos.
Requisitos y limitaciones de contenido de datos
Todos los contenidos de las entidades de datos deben respetar los siguientes requisitos y limitaciones.
Cualquier fila de datos que no respete estos requisitos se tratan como se especifica en la columna Comportamiento de valor no válido para la entidad de datos y atributos relevantes:
Todos los id. de artículos y variantes de artículos deben cumplir exactamente una de estas restricciones (no puede mezclar los formatos de id. de artículos de ambas opciones):
- La longitud debe ser de 16 caracteres o menos y contener solo los siguientes caracteres: A-Z, 0-9, _, -, ~,.
- En formato GUID: una cadena de exactamente 36 caracteres que contiene caracteres hexadecimales y guiones; por ejemplo, 12345678-1234-5678-90ab-1234567890ab. Si desea usar este formato de GUID, agregue una entrada a la entidad de datos Reco_Config con los siguientes datos: Clave=ItemIdAsGuid, Valor=True (o sea, ItemIdAsGuid,True). De lo contrario, Intelligent Recommendations no genera recomendaciones.
Los id. de variantes de artículos deben ser únicos a nivel global (en todos los artículos y variantes de artículos).
El id. de variante del artículo debe dejarse vacío en las filas de datos que representan datos sobre un artículo maestro o un artículo independiente.
Los id. de artículo y los id. de variante de artículo no distinguen entre mayúsculas y minúsculas, lo que significa que:
- Los id. ABCD1234, abcd1234 y AbCd1234 se consideran todos el mismo.
- En las respuestas de la API de recomendaciones, los id. devueltos están todos en mayúsculas.
Los atributos de cadena tienen un límite de longitud. Los valores de cadena que superen su límite se recorta a su límite (se eliminan los caracteres en exceso) o se elimina toda la fila de datos (el comportamiento exacto se muestra en la tabla de entidades de datos para cada atributo).
Todos los valores Fecha y hora deben estar en UTC, en el siguiente formato: yyyy-MM-ddTHH:mm:ss.fffZ.
Todas las cadenas, excepto el artículo título y el artículo descripción, no distinguen entre mayúsculas y minúsculas. Por ejemplo, filtrar nombres Color y color se consideran iguales, y el valor del filtro Rojo es el mismo que el valor del filtro rojo.
Para cualquier atributo no obligatorio que esté vacío, se utiliza el valor predeterminado (si se especifica un valor predeterminado).
Los valores booleanos deben ser true o false y no distinguen entre mayúsculas y minúsculas (lo que significa que true se considera igual que True).
Cambios desde la versión anterior
Aquí está la lista de cambios en el contrato de datos entre la versión 1.3 y la versión 1.4:
| Entidad de datos | Resumen de cambios |
|---|---|
| Reco_ItemCategories | La entidad de datos ahora es compatible y puede no estar vacía. |
| Reco_ItemAndVariantFilters | FilterName admite el nombre de filtro personalizado.Ahora los filtros admiten el filtrado de valores múltiples (más de un valor de filtro). |
| Reco_ItemAndVariantAvailabilities | Canal y Catálogo ahora admiten cualquier valor de cadena (no solo 0). |
| Reco_Interactions | Canal y Catálogo ahora admiten cualquier valor de cadena (no solo 0). |
| Reco_ImagesInventory | Nueva entidad de datos. |
| Reco_ImageToItemMappings | Nueva entidad de datos. |
Consulte también
API de Intelligent RecommendationsGuía de inicio rápido: configurar y ejhecutar recomendaciones inteligentes con datos de ejemploCódigos de estado de APITabla de asignación de entidades de datosEntidades de datos de catálogoInteractions data entitiesEntidades de datos de reconfiguraciónEntidades de datos de listas externasEntidades de datos de usuarios dados de bajaEntidades de datos de enriquecimiento de recomendacionesEntidades de datos de asignación de imagen a elemento