Meilleures pratiques d’utilisation de l’API Catalog Microsoft Learn

Article
05/17/2024

Cet article décrit les meilleures pratiques d’utilisation de l’API Catalog Learn.

Comprendre les conditions d’utilisation

Bien que l’API Catalog Learn soit disponible publiquement et libre d’utilisation, les utilisateurs sont soumis aux conditions d’utilisation de l’API Microsoft. Lisez et comprenez les conditions d’utilisation de l’API avant d’utiliser l’API Learn Catalog et avant d’inclure la sortie dans n’importe quel environnement de production.

Comprendre les limitations de l’API Catalog Learn

Consultez la section Limitations de l’article Présentation des fonctionnalités de l’API Catalog Learn.

Comprendre le modèle de contenu Learn

Pour utiliser efficacement la réponse de l’API Catalog Learn, il est important de comprendre les types de contenu disponibles dans Microsoft Learn et leurs relations les uns avec les autres. Pour plus d’informations, consultez l’article Types de modèle de contenu Learn.

Notamment :

L’UID représente l’ID unique et est unique pour chaque objet de contenu. Si un UID change, même si le titre ou d’autres métadonnées restent identiques, le contenu est considéré comme un nouvel objet.
Les modules sont l’objet principal du catalogue de formations Learn. Ils sont tous autonomes, dans le sens où ils enseignent un scénario ou un concept de bout en bout et ne nécessitent pas de suivre des modules prérequis. Certaines se suffisent à elles-mêmes et elles ne font pas partie d’un parcours d’apprentissage. D’autres sont regroupées dans un ou plusieurs parcours d’apprentissage qui présentent à l’utilisateur des concepts plus avancés. Un module ne doit pas nécessairement faire partie d’un parcours d’apprentissage, ou il peut faire partie d’un ou de plusieurs parcours d’apprentissage.
Les unités ne sont pas écrites en tant que contenu autonome. Elles sont destinées à être utilisées dans un ordre spécifique pour le module. Pour cette raison, nous incluons le lien vers la page de détails du module et la première unité afin que les utilisateurs puissent démarrer à cet endroit-là et poursuivre la lecture du contenu.

Comprendre le fonctionnement de la localisation dans Learn et comment le contenu localisé est reflété dans la sortie de l’API

Microsoft Learn prend en charge plus de 65 paramètres régionaux sur le site et la majeure partie du contenu est traduite dans ces paramètres régionaux. Nous voulons rendre le contenu disponible dans toutes les langues dans lesquelles les produits enseignés dans le contenu sont disponibles, mais toutes les expériences de paramètres régionaux n’ont pas de contenu localisé disponible.

Quand aucune traduction associée n’est disponible pour un enregistrement de paramètres régionaux, le contenu sur le site et la réponse de l’API reviennent à l’anglais par défaut. Dans la sortie de l’API, vous voyez les métadonnées anglaises dans d’autres réponses de paramètres régionaux lorsque la restauration se produit. Toutefois, l’URL du contenu pointe toujours vers les paramètres régionaux, même si le contenu principal peut revenir en arrière, et ceci pour permettre à l’utilisateur de naviguer toujours sur le site dans ces paramètres régionaux (qui affiche l’en-tête/pied de page traduit et tout autre lien dont la traduction est disponible).

Lorsque des mises à jour sont publiées dans le contenu en anglais, nos pipelines de localisation font en sorte que les versions localisées soient mises à jour dès que possible, généralement dans les quelques jours suivant la modification d’origine. Vous pouvez voir la liste complète des paramètres régionaux pris en charge dans le pied de page du site Microsoft Learn (sélectionnez la langue que vous affichez). Chacun de ces paramètres régionaux peut être interrogé avec l’API Catalog Learn à l’aide du filtre locale.

Nos enregistrements relatifs à l’achèvement du contenu des formations sont indépendants des paramètres régionaux. En d’autres termes, nous ne différencions pas les versions localisées du contenu en tant qu’objets distincts dans nos enregistrements d’achèvement de formation des utilisateurs. Quelle que soit la langue dans laquelle un utilisateur effectue une formation, il reçoit un crédit pour l’objet global, et nous ne stockons pas de référence à la langue dans laquelle la formation a été effectuée. Cet achèvement indépendant des paramètres régionaux signifie que si vous implémentez l’API Learn Catalog dans votre expérience d’apprentissage, vous devez la prendre en compte et, si vous chargez les objets de contenu en tant qu’objets distincts, implémenter une équivalence entre eux afin que, quelle que soit la langue dans laquelle l’utilisateur termine la formation, il obtient un crédit pour celle-ci dans les autres langues et n’a pas à la suivre de nouveau.

Comprendre le fonctionnement du contrôle de version de contenu dans Learn et comment il est reflété dans la sortie de l’API

Notamment, le contenu est mis à jour en permanence. Nous publions les mises à jour disponibles deux fois par jour. Elles peuvent être mineures (p. ex. des modifications de texte mineures) ou majeures (p. ex. des révisions, des ajouts ou des suppressions majeurs). En général, le portefeuille de contenu est géré comme un projet open source massif et hautement régi ayant des milliers de contributeurs, et par conséquent, des changements se produisent tout le temps. Si vous utilisez l’API Catalog Learn dans votre système de production, vous devez en être conscient et faire en sorte que votre système soit en mesure de gérer ces changements.

Lorsque de nouveaux objets de contenu sont ajoutés, ils apparaissent sous la forme d’un nouvel objet (identifié par UID) dans la réponse. Lorsque du contenu est modifié, vous pouvez le déterminer en vous référant à sa valeur last_modified. Lorsque du contenu est supprimé, l’objet de contenu est supprimé de la réponse. Bien qu’il y ait parfois un léger retard sur la mise à jour du contenu dans la réponse de l’API, lorsqu’un utilisateur suit l’URL pointant vers le contenu, il voit toujours les informations les plus actualisées. Dans le cas de suppressions, l’ancienne URL redirige vers le nouveau contenu ou la nouvelle expérience, ou vers la meilleure option suivante.

Il n’existe aucune référence aux versions de contenu pour l’instant au-delà de la date last_modified.

Actualiser les données régulièrement

Si vous utilisez les informations du catalogue provenant de l’API Catalog Learn pour prendre en charge vos processus métier, ou si vous les affichez pour les clients dans le cadre de votre expérience de site, veillez à actualiser le contenu au moins une fois par jour.

Passer en revue les recommandations de la documentation pour les développeurs

La documentation sur l’API Catalog Learn destinée aux développeurs contient une liste complète des données fournies dans le cadre de la réponse, ainsi que des recommandations sur la façon dont chaque champ doit être utilisé pour prendre en charge des expériences d’apprentissage exceptionnelles.

Comprendre la logique de requête

Il existe de nombreux filtres disponibles pour préfiltrer la réponse, de sorte que vous obtenez uniquement ce que vous recherchez et que vous pouvez gérer des tailles de fichiers plus petites. Vous pouvez voir la liste complète des filtres de requête dans l’article d’informations de référence sur l’API Catalog Learn destinées aux développeurs. Notamment, vous devez former la requête correctement et si vous utilisez plusieurs paramètres de requête dans la requête, celle-ci est évaluée à l’aide de l’opérateur AND.

Étapes suivantes

Pour plus d’informations sur la prise en charge de l’API Catalog Learn, consultez les articles suivants :

Share via