Vue d’ensemble du contrat de données
Cet article explique comment partager des données avec Recommandations intelligentes afin que vous puissiez l’activer et fournir des recommandations significatives.
L’API Recommandations intelligentes correspondante pour les contrats de données décrits est l’API Recommandations intelligentes.
Téléchargez le dernier fichier model.json pour les contrats de données Recommandations intelligentes : model.json.
Conditions préalables
Pour l’intégration des données, Recommandations intelligentes, utilisez Microsoft Azure Data Lake Storage. Cet article décrit la structure logique des données que Recommandations intelligentes prévoit de consommer de votre compte Azure Data Lake Storage.
Pour permettre à Recommandations intelligentes de trouver facilement vos données dans le compte Azure Data Lake Storage, vous devez créer un dossier dédié dans le compte Azure Data Lake Storage et fournissez le chemin du dossier (dossier racine de Recommandations intelligentes) à Recommandations intelligentes.
Pour plus d’informations sur l’intégration et la création de votre compte Data Lake Storage, accédez à Déployer des recommandations intelligentes ou visitez notre Guide de démarrage rapide.
Contrats de données
Les Contrats de données sont un ensemble de définitions et de contraintes pour la structure des données que Recommandations intelligentes consomme. Pour permettre à Recommandations intelligentes d’ingérer les données partagées avec elle et de fournir des recommandations, vous devez respecter les contrats de données décrits dans cet article.
Modèle de fichier JSON
Les contrats de données Recommandations intelligentes sont logiquement divisés en un ensemble d’entités de données. Chaque entité de données comprend zéro ou plusieurs fichiers CSV d’entrée, également appelés partitions. Un fichier texte JSON séparé appelé model.json décrit l’ensemble des entités de données. Le fichier modèle JSON est préconfiguré et peut être immédiatement ajouté au dossier racine Recommandations intelligentes.
Télécharger le modèle par défaut
Téléchargez le dernier modèle de fichier JSON par défaut pour les contrats de données Recommandations intelligentes : model.json.
[!NOTE]
Le fichier modèle.json doit être inclus dans le dossier racine des recommandations intelligentes en plus des fichiers d’entité de données. Vous pouvez apprendre à faire des ajustements à model.json sous la section Modifier le fichier par défaut du présent contrat de données.
Modifiez le fichier par défaut
La modification du fichier JSON de modèle fourni n’est pas recommandée tant que vous n’êtes pas familiarisé avec le service Recommandations intelligentes et uniquement quand vous utilisez l’une des fonctionnalités suivantes :
Format des entrées numériques. L’attribut culture spécifie ce que Recommandations intelligentes utilise comme format d’entrée pour les valeurs numériques. Le séparateur décimal peut être un point (.) ou une virgule (,) dans différentes cultures. Pour utiliser un séparateur décimal autre qu’un point (.), spécifiez la culture appropriée dans l’attribut culture.
Note
Si vous utilisez une virgule (,) comme séparateur décimal, vous devrez échapper correctement chaque valeur décimale dans le fichier CSV d’entrée. Pour plus d’informations sur la façon d’échapper les caractères dans les fichiers d’entrée CSV, accédez à la section Format des données.
Emplacements des partitions explicites. Pour spécifier des emplacements explicites des fichiers de partition d’entité de données, vous pouvez utiliser l’attribut partitions. Par défaut, la valeur de l’attribut partitions est nulle, ce qui signifie que Recommandations intelligentes recherche automatiquement les fichiers de partition d’entité de données pertinents. Pour plus d’informations, voir Format des données. L’attribut partitions est un tableau de partitions. Chaque partition contient les attributs suivants :
- name : représentation sous forme de chaîne de la partition, non utilisée par Recommandations intelligentes pour une logique spécifique.
- location : URI complète vers le fichier de données de partition (CSV). L’URI doit être accessible à Recommandations intelligentes (lecture seule), ce qui peut nécessiter que vous fournissiez les autorisations appropriées pour Recommandations intelligentes. Pour plus d’informations sur la manière d’autoriser Recommandations intelligentes à accéder aux données, accédez à Configurer Azure Data Lake Storage.
- fileFormatSettings : Contient l’attribut suivant :
- columnsHeaders : valeur booléenne spécifiant si les données de partition contiennent une ligne d’en-tête. Les Recommandations intelligentes ignorent automatiquement les lignes d’en-tête quand les données d’entrée sont ingérées. La valeur par défaut est false, ce qui signifie pas d’en-têtes.
Voici un échantillon de l’attribut partitions :
"partitions": [
{
"name": "Partition1",
"location": "https://myStorageAcount.blob.core.windows.net/intelligent-recommnedations-container/intelligent-recommendations-root-folder/partition1.csv",
"fileFormatSettings": {
"columnHeaders": true
}
}
]
Meilleures pratiques pour mettre à jour vos données d’entrée
Évitez une situation dans laquelle les données sont modélisées et mises à jour en même temps, car cela peut entraîner la modélisation de données provenant de versions mixtes jeu de données et des résultats de recommandation indésirables. Parmi certaines meilleures pratiques pour mettre à jour vos données d’entrée figurent les suivantes :
- Écrivez toutes les entités de données dans un dossier différent. Ce dossier ne doit pas nécessairement se trouver dans le même conteneur ou compte de stockage dans lequel se trouvent vos données d’entrée actuelles. Assurez-vous de fournir des autorisations de Recommandation intelligente pour lire les données du conteneur de vos données d’entrée mises à jour. Pour plus d’informations, voir Configurer Azure Data Lake Storage.
- Pour chacune des entités de données que vous utilisez, ajoutez l’attribut « partitions » à votre modèle de fichier Json. Pour chaque partition, mettez à jour l’attribut « location » afin qu’il pointe vers le nouvel emplacement des données. Une explication sur la façon d’ajouter et de modifier l’attribut « partitions » est disponible ici
- Vous pouvez supprimer les anciennes données si elles ne sont plus utilisées. Nous vous recommandons de supprimer les anciennes données après la durée estimée du cycle de modélisation (au moins 36 heures), avec une certaine mémoire tampon pour éviter que les données ne soient supprimées pendant la modélisation.
- Répétez les étapes 1 à 3 chaque fois que vous souhaitez mettre à jour vos données d’entrée.
Entités de données
Une entité de données est un ensemble d’un ou plusieurs fichiers texte de données, chacun ayant une liste de colonnes (également appelée attributs) et des lignes contenant les valeurs de données réelles.
Recommandations intelligentes définit des groupes logiques d’entités de données, chacun ayant son propre objectif. Les entités de données sont considérées comme facultatives (sauf indication contraire explicite), ce qui signifie que leurs données peuvent être vides (ou entièrement manquantes).
Les Recommandations intelligentes définissent les groupes d’entités de données suivants :
Format de données
Recommandations intelligentes s’attend à ce que tous les fichiers d’entrée de partition d’entités de données soient conformes au format suivant :
Le contenu du fichier d’entrée de la partition doit être au format de fichiers texte délimités par des virgules (CSV), en utilisant uniquement du texte encodé UTF-8.
Chaque fichier CSV doit inclure tous les champs spécifiés dans le contrat de données de l’entité de données concernée. De plus, les champs doivent être affichés selon l’ordre décrit dans ce contrat.
Les fichiers CSV ne doivent contenir que des entrées de données, selon RFC 4180.
Voici quelques exemples courants de comportement du format de données CSV dans différents cas :
Chaque champ peut ou non être entouré de guillemets doubles.
Par exemple : aaa, "bbb", ccc
Les champs contenant des sauts de ligne (CRLF), des guillemets doubles et des virgules doivent être placés entre guillemets doubles.
Par exemple : aaa, “bbCRLFb”, “c, cc”
Un guillemet double apparaissant à l’intérieur d’un champ doit être échappé en le faisant précéder d’un autre guillemet double.
Par exemple : aaa, “b””bb”, ccc
Si vous n’avez pas explicitement indiqué l’attribut partitions (dans le modèle de fichier JSON) pour une entité de données, Recommandations intelligentes recherche les fichiers de partition d’entité de données dans un sous-dossier (sous le dossier racine Recommandations intelligentes) portant le même nom que l’entité de données.
Dans ce cas, tous les fichiers d’entrée de partition dans le sous-dossier d’entité de données doivent avoir une extension de fichier CSV, telle que MyData.csv, et ne doit pas contenir de ligne de données d’en-tête.
Recommandations intelligentes recherche et agrège les données de tous les fichiers qui utilisent l’extension CSV, tout en ignorant le nom de fichier lui-même.
Exemple de structure de dossier de recommandations intelligentes
Voici un exemple de capture d’écran d’une structure de dossier racine Recommandations intelligentes. Il n’est pas nécessaire que les CSV correspondent aux noms de dossier :
Entités de données requises pour chaque scénario de recommandation
Les scénarios de recommandations peuvent s’appuyer sur différentes entités de données pour fonctionner correctement. Pour voir une table complet mappant des scénarios et des entités de données, consultez notre Tableau de mappage des entités de données.
Configuration requise et restrictions du contenu des données
Tous les contenus des entités de données doivent respecter les exigences et limitations suivantes.
Toute ligne de données qui ne respecte pas ces exigences est traitée comme spécifié dans la colonne Comportement de valeur non valide pour l’entité de données et les attributs pertinents :
Tous les ID d’article et de variante d’article doivent respecter exactement l’une de ces restrictions (vous ne pouvez pas mélanger les formats d’ID d’article des deux options) :
- La longueur doit être inférieure ou égale à 16 caractères et contenir uniquement les caractères suivants : A-Z, 0-9, _, -, ~,.
- Au format GUIDune chaîne d’exactement 36 caractères contenant des caractères hexadécimaux et des tirets ; par exemple 12345678-1234-5678-90ab-1234567890ab. Si vous souhaitez utiliser ce format GUID, ajoutez une entrée à l’entité de données Reco_Config avec les données suivantes : Key=ItemIdAsGuid, Value=True (c’est, ItemIdAsGuid,True). Sinon, Recommandations intelligentes ne parvient pas à générer des recommandations.
Les ID de variante d’article doivent être globalement uniques (pour tous les articles et variantes d’article).
L’ID de variante d’article doit être laissé vide pour les lignes de données qui représentent des données sur un article principal ou un article autonome.
Les ID d’article et les ID de variante d’article ne sont pas sensibles à la casse, ce qui signifie que :
- Les ID ABCD1234, abcd1234, et AbCd1234 sont tous considérés comme identiques.
- Dans les réponses de l’API de recommandations, les ID renvoyés sont tous en majuscules.
Les attributs de chaîne ont une limite de longueur. Les valeurs de chaîne qui dépassent leur limite sont réduites (les caractères en excès sont supprimés) ou la ligne de données entière est supprimée (le comportement exact est répertorié dans le tableau des entités de données pour chaque attribut).
Toutes les valeurs DateTime doivent être au format UTC, au format suivant : aaaa-MM-jjTHH:mm:ss.fffZ.
Toutes les chaînes, à l’exception de l’élément Titre et l’élément Description, sont insensibles à la casse. Par exemple, filtrer les noms Couleur et couleur sont considérés comme identiques et la valeur du filtre Rouge est la même que la valeur du filtre rouge.
Pour tout attribut non obligatoire qui est vide, la valeur par défaut est utilisée (si une valeur par défaut est spécifiée).
Les valeurs booléennes doivent être soit true ou false et sont insensibles à la casse (ce qui signifie que true est considéré comme le même que True).
Modifications par rapport à la version précédente
Voici la liste des changements de contrat de données entre la version 1.3 et la version 1.4 :
| Entité de données | Résumé des modifications |
|---|---|
| Reco_ItemCategories | L’entité de données est désormais prise en charge et peut être non vide. |
| Reco_ItemAndVariantFilters | FilterName prend en charge un nom de filtre personnalisé.Les filtres prennent désormais en charge le filtrage à plusieurs valeurs (plus d’une valeur de filtre). |
| Reco_ItemAndVariantAvailabilities | Channel et Catalog prennent désormais en charge n’importe quelle valeur de chaîne (pas seulement 0). |
| Reco_Interactions | Channel et Catalog prennent désormais en charge n’importe quelle valeur de chaîne (pas seulement 0). |
| Reco_ImagesInventory | Nouvelle entité de données. |
| Reco_ImageToItemMappings | Nouvelle entité de données. |
Voir aussi
API Recommandations intelligentesGuide de démarrage rapide : configurer et exécuter des recommandations intelligentes avec des exemples de donnéesCodes de statuts APITable de mappage d’entités de donnéesEntités de données du catalogueEntités de données d’interactionsEntités de données de configuration de recommandationEntités de données de listes externesEntités de données d’utilisateurs désabonnésEntités de données d’enrichissement des recommandationsEntités de données de mappage image-élément