Partager via

Meilleures pratiques pour l’utilisation de l’API catalogue Microsoft Learn

  • Article

Cet article décrit les meilleures pratiques pour l’utilisation de l’API Du catalogue Learn.

Comprendre les conditions d’utilisation

Bien que l’API Learn Catalog soit disponible publiquement et gratuite, 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 Du catalogue Learn et avant d’inclure la sortie dans n’importe quel environnement de production.

Comprendre les limitations de l’API du catalogue Learn

Consultez les limitations dans l'article Vue d'ensemble des fonctionnalités de l'API catalogue Learn.

Comprendre le modèle de contenu Learn

Pour utiliser efficacement la réponse de l’API catalogue Learn, il est important de comprendre les types de contenu disponibles dans Microsoft Learn et leurs relations entre eux. Pour plus d’informations, consultez l'article du modèle de contenu Apprendre.

Notamment:

  • 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 reste le même, le contenu est considéré comme un nouvel objet.
  • Les modules sont l’objet principal dans le catalogue d’apprentissage Learn. Ils sont tous capables d'être autonomes, dans le sens qu'ils enseignent un scénario ou un concept de bout en bout en leur sein et ne nécessitent pas de modules prérequis. Pour certains, c’est ça et ils ne font pas partie d’un parcours d’apprentissage. Pour d’autres, ils sont regroupés dans un ou plusieurs parcours d’apprentissage qui permettent à un utilisateur de créer des concepts plus avancés. Un module n’est pas obligé de faire partie d’un parcours d’apprentissage, ou il peut faire partie d’un ou plusieurs.
  • Les unités ne sont pas écrites en tant que contenu autonome. Ils sont destinés à être suivis 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 y démarrer et passer par le contenu.

Comprendre le fonctionnement de la localisation dans Learn et la façon dont 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 en 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 pas toutes les expériences de paramètres régionaux ont du contenu localisé disponible.

Lorsqu’un enregistrement de paramètres régionaux n’a pas la traduction associée disponible, le contenu sur le site et la réponse de l’API « revient » en anglais comme valeur par défaut. Dans la sortie de l’API, vous voyez des métadonnées en anglais dans les réponses d'autres paramètres régionaux quand il y a un retour en arrière. 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 la raison est de 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 qui a la traduction disponible).

Lorsque les mises à jour sont publiées sur le contenu anglais, nos pipelines de localisation fonctionnent pour obtenir les versions localisées mises à jour dès que possible , généralement dans quelques jours après 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 du catalogue Learn à l’aide du filtre locale.

Nos enregistrements de finalisation de contenu de formation sont indépendants des paramètres régionaux, ce qui signifie que nous ne différencions pas les versions localisées du contenu en tant qu’objets distincts dans nos enregistrements de finalisation de formation utilisateur. 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 il a été effectué. Cette indépendance vis-à-vis des paramètres régionaux signifie que si vous implémentez l’API Learn Catalog dans votre expérience d’apprentissage, vous devez en tenir compte et, si vous chargez les objets de contenu comme des objets distincts, implémentez une équivalence entre eux afin que, quelle que soit la langue dans laquelle l’utilisateur termine la formation, il obtienne un crédit pour celle-ci dans les autres langues et n’a pas besoin de le reprendre.

Comprendre comment fonctionne le 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 à tout moment. Nous publions les mises à jour disponibles deux fois par jour. Ils peuvent être mineurs, tels que les modifications de texte mineures ou les modifications majeures, telles que les révisions majeures, les ajouts ou les suppressions. En général, le portefeuille de contenu est géré en tant que projet open source massivement régi par des milliers de contributeurs et, par conséquent, des changements se produisent à tout le temps. Si vous utilisez l’API Learn Catalog dans votre système de production, vous devez être conscient de cela et avoir votre système en mesure de le gérer.

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 le contenu est modifié, vous pouvez le savoir en fonction de sa valeur de last_modified. Lorsque le contenu est supprimé, l’objet de contenu est supprimé de la réponse. Bien qu’il y ait parfois un léger retard sur le contenu mis à jour dans la réponse de l’API, lorsqu’un utilisateur suit l’URL du contenu, il voit toujours les informations les plus actuelles. Dans le cas de suppressions, l’ancienne URL redirige vers le nouveau contenu ou l’expérience, ou vers la meilleure option suivante.

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

Actualiser régulièrement les données

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

Notamment, le contenu est mis à jour à tout moment. Nous publions les mises à jour disponibles deux fois par jour. Ils peuvent être mineurs, tels que les modifications de texte mineures ou les modifications majeures, telles que les révisions majeures, les ajouts ou les suppressions. En général, le portefeuille de contenu est géré en tant que projet open source massivement régi par des milliers de contributeurs et, par conséquent, des changements se produisent à tout le temps. Si vous utilisez l’API Learn Catalog dans votre système de production, vous devez être conscient de cela et avoir votre système en mesure de le gérer.

Passez en revue les recommandations de la documentation du développeur

La documentation du développeur de l’API Learn Catalog contient une liste complète des données fournies dans le cadre de la réponse et des recommandations sur la façon dont chaque champ est recommandé pour prendre en charge des expériences d’apprentissage exceptionnelles.

Comprendre la logique de requête

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

Étapes suivantes

Pour obtenir plus d'informations pour vous aider avec l'API Learn Catalog, consultez les articles suivants :