Commencez avec l'API de la plateforme Microsoft Learn

Cet article vous aide à commencer à utiliser l’API de plateforme Microsoft Learn. Si vous n’êtes pas familiarisé avec les détails de l’API ou les cas d’usage pour celui-ci, nous vous recommandons d’examiner d’abord l’article Vue d’ensemble de l’API de plateforme Microsoft Learn .

Authentification de l'API Learn Platform

Les API REST Learn Platform utilisent Microsoft Entra ID pour l’authentification. Avant d’effectuer des appels d’API, vous devez choisir une méthode d’accès, et votre application cliente doit s’authentifier avec des informations d’identification valides.

Accès uniquement par application

Lorsque votre application accède directement à Learn, son accès n’est lié à aucun utilisateur unique. L’application appelle des API directement à l’aide de sa propre identité, ce scénario est un accès à l’application uniquement. En savoir plus sur la plateforme d’identités Microsoft.

Pour commencer, vous avez besoin d’une identité valide sur la plateforme d’identités Microsoft, qui peut être une inscription d’application ou une identité managée. Dans l’idéal, chaque partenaire doit avoir une identité unique pour simplifier le quota et la gestion des partenaires. L’utilisation d’une identité managée affectée par l’utilisateur peut aider à unifier les identités managées entre différents services.

Une fois votre identité Entra ID configurée, obtenez un jeton d’accès auprès de Entra ID avec l’étendue définie comme preuve d’authentification. Incluez le jeton d’accès dans l’en-tête d’autorisation HTTP lors de l’établissement de requêtes d’API REST à Learn.

Accès délégué

Lorsqu’un utilisateur se connecte à votre application et l’utilise pour accéder à Learn, l’application doit d’abord demander l’autorisation d’accéder à cette ressource au nom de l’utilisateur. Ce scénario est appelé accès délégué. En savoir plus sur la plateforme d’identités Microsoft.

Pour commencer, vous devez inscrire une inscription d’application. Une fois l’inscription de votre application configurée, votre application doit demander à l’utilisateur d’accorder une étendue spécifique ou un ensemble d’étendues pour accéder à Learn au nom de l'utilisateur. Learn fournit une liste de périmètres pour l’accès granulaire aux ressources. La liste des portées comprend :

•  : cette étendue permet aux utilisateurs d’accéder au contenu public sur Learn en étant usurpés comme l’utilisateur connecté.

Présentation du contrôle de version de l’API de plateforme Microsoft Learn

Lorsque des modifications de rupture sont apportées à l’API, nous publions une nouvelle version datée. Les changements cassants sont des modifications qui peuvent potentiellement arrêter une intégration. Toutes les modifications additives (non destructives) seront disponibles dans toutes les versions d’API prises en charge.

La version de l’API est spécifiée en tant que paramètre de requête api-version et utilise aaaa-MM-jj pour les versions stables et aaaa-MM-jj-preview pour les versions préliminaires. Le paramètre de requête api-version est requis pour chaque requête d’API.

Lorsqu’une nouvelle version d’API stable est publiée, la version précédente de l’API stable est prise en charge pendant au moins 24 mois après la publication de la nouvelle version de l’API. Les API en préversion ont un cycle de support plus court de trois mois supplémentaires après la publication de nouvelles API en préversion.

La version actuelle est 2023-11-01-preview.

Le segment d'URL /v1/ placé avant chaque API fait partie de l'URL de base, et non de la version de l'API. Il est réservé aux modifications substantielles du protocole d’API et des modèles à l’avenir.

Limitation de la vitesse de l'API Learn Platform

Learn limite le nombre de demandes d’API REST que vous pouvez effectuer dans un délai spécifique. Cette limite permet d’éviter les abus et les attaques par déni de service, et garantit que l’API reste disponible pour tous les utilisateurs.

Learn applique des limites de débit en fonction de la revendication oid dans le jeton d’accès. Pour l’accès à l’application uniquement, la limite est appliquée à l’application elle-même, tandis que pour l’accès délégué, la limite est appliquée à l’utilisateur connecté à l’application.

Par défaut, la limite de débit est de 100 appels d’API par minute, calculés sur une fenêtre de 5 minutes. Si vous avez besoin d’une limite plus élevée pour la production, vous pouvez contacter le support Learn Integrations pour demander une augmentation.

Certaines API, telles que l’API de recherche de connaissances, implémentent également la limitation du débit basé sur les jetons. Cela est basé sur le nombre de jetons OpenAI consommés Microsoft Azure, avec une limite par défaut de 10 000 jetons par minute. Pour augmenter cette limite de production, contactez le support Learn Integrations.

Pagination de l’API Learn Platform

Toutes les ressources d’API de niveau supérieur prennent en charge la récupération en bloc via les méthodes d’API « list ». Par exemple, vous pouvez récupérer des listes de modules ou d’examens. Ces méthodes retournent des réponses paginées suivant une approche standardisée.

Les méthodes d’API de liste utilisent la pagination basée sur le curseur, indiquée par le champ nextLink dans le corps de la réponse. Ce champ contient une URL opaque avec les informations nécessaires pour extraire la page suivante des résultats. Par défaut, les API de liste retournent 30 éléments par requête, mais vous pouvez ajuster la taille de la page à l’aide du paramètre maxpagesize.

Nos bibliothèques de sdk client offrent des assistances d’autopagination pour parcourir toutes les pages d’une liste.

Contenu connexe

• Démarrage rapide : Configurer et utiliser les données du catalogue d’API de la plateforme Microsoft Learn
• Référence du développeur de données du catalogue API de Learn Platform
• FAQ sur l’API Learn Platform