Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Dieser Artikel unterstützt Sie bei den ersten Schritten mit der Microsoft Learn Platform-API. Wenn Sie nicht mit den Details der API oder den Anwendungsfällen dafür vertraut sind, empfehlen wir Ihnen, zuerst den Artikel "Übersicht über die Microsoft Learn Platform-API" zu lesen.
Plattform-API-Authentifizierung erlernen
Die Learn Platform-REST-APIs verwenden die Microsoft Entra-ID für die Authentifizierung. Bevor Sie API-Aufrufe ausführen, müssen Sie eine Zugriffsmethode auswählen, und Ihre Clientanwendung muss sich mit gültigen Anmeldeinformationen authentifizieren.
Nur App-Zugriff
Wenn Ihre App direkt auf Learn zugreift, ist der Zugriff nicht an einen einzelnen Benutzer gebunden. Die App ruft APIs direkt mit ihrer eigenen Identität auf, dieses Szenario ist ein reiner App-Zugriff. Erfahren Sie mehr über die Microsoft Identity Platform.
Um zu beginnen, benötigen Sie eine gültige Identität auf der Microsoft Identity Platform, bei der es sich um eine App-Registrierung oder eine verwaltete Identität handeln kann. Im Idealfall sollte jeder Partner über eine einzige Identität verfügen, um die Kontingent- und Partnerverwaltung zu vereinfachen. Die Verwendung einer vom Benutzer zugewiesenen verwalteten Identität kann dazu beitragen, verwaltete Identitäten über verschiedene Dienste hinweg zu vereinheitlichen.
Nachdem Ihre Entra ID-Identität eingerichtet wurde, rufen Sie bei Entra ID ein Zugriffstoken ab, dessen Scope auf https://learn.microsoft.com/.default festgelegt ist, als Nachweis der Authentifizierung. Schließen Sie das Zugriffstoken in den HTTP-Autorisierungsheader ein, wenn Sie REST-API-Anforderungen an Learn erstellen.
Delegierter Zugriff
Wenn sich ein Benutzer bei Ihrer App anmeldet und sie verwendet, um auf "Learn" zuzugreifen, muss die App zuerst die Berechtigung im Namen des Benutzers anfordern, um auf diese Ressource zuzugreifen. Dieses Szenario wird als delegierter Zugriff bezeichnet. Erfahren Sie mehr über die Microsoft Identity Platform.
Zunächst müssen Sie eine App-Registrierung registrieren. Nachdem Ihre App-Registrierung eingerichtet wurde, muss die App den Benutzer auffordern, eine bestimmte Berechtigung oder einen Satz von Berechtigungen für den Zugriff auf die Learn-Plattform im Auftrag des Benutzers anzufordern. Learn bietet eine Liste der Bereiche für den feinkörnigen Ressourcenzugriff. Die Liste der Bereiche umfasst:
-
https://learn.microsoft.com/PublicContent.Read.All: Dieser Bereich ermöglicht Benutzern den Zugriff auf öffentliche Inhalte auf Learn bei Imitierung des angemeldeten Benutzers.
Grundlegendes zur Versionsverwaltung der Microsoft Learn Platform-API
Wenn einschneidende Änderungen an der API vorgenommen werden, veröffentlichen wir eine neue, datierte Version. Breaking Changes sind Änderungen, die möglicherweise eine Integration unterbrechen können. Alle strukturerhaltenden (additiven) Änderungen sind in allen unterstützten API-Versionen verfügbar.
DIE API-Version wird als Api-Version-Abfrageparameter angegeben und verwendet yyyy-MM-dd für stabile Versionen und yyyy-MM-dd-preview für Vorschauversionen. Der Api-Version-Abfrageparameter ist für jede API-Anforderung erforderlich.
Wenn eine neue stabile API-Version veröffentlicht wird, wird die vorherige stabile API-Version mindestens 24 weitere Monate nach der Veröffentlichung der neuen API-Version unterstützt. Vorschau-APIs haben einen kürzeren Supportzyklus von drei weiteren Monaten nach der Veröffentlichung neuer Vorschau-APIs.
Die aktuelle Version ist 2023-11-01-preview.
Das /v1/-URL-Segment vor jeder API ist Teil der Basis-URL, nicht der API-Version. Es ist für wesentliche API-Protokoll- und Musteränderungen in Zukunft reserviert.
Plattform-API-Geschwindigkeitsbeschränkung erlernen
Learn beschränkt die Anzahl der REST-API-Anfragen, die Sie innerhalb eines bestimmten Zeitraums stellen können. Dieses Limit trägt dazu bei, Missbrauch und Denial-of-Service-Angriffe zu verhindern, und stellt sicher, dass die API für alle Benutzer*innen verfügbar bleibt.
Learn wendet Geschwindigkeitsbegrenzungen basierend auf dem OID-Anspruch im Zugriffstoken an. Bei Nur-App-Zugriff wird der Grenzwert auf die App selbst angewendet, während der delegierte Zugriff auf den Benutzer angewendet wird, der bei der App angemeldet ist.
Standardmäßig beträgt der Satzgrenzwert 100 API-Aufrufe pro Minute, berechnet über ein 5-Minuten-Fenster. Wenn Sie einen höheren Grenzwert für die Produktion benötigen, können Sie sich an den Learn Integrations-Support wenden, um eine Erhöhung anzufordern.
Bestimmte APIs, z. B. die Wissenssuch-API, implementieren auch tokenbasierte Ratenbeschränkungen. Dies basiert auf der Anzahl der verbrauchten Microsoft Azure OpenAI-Token mit einem Standardgrenzwert von 10.000 Token pro Minute. Um diesen Grenzwert für die Produktion zu erhöhen, wenden Sie sich an den Learn-Integrationen-Support.
Plattform-API-Paginierung erlernen
Alle API-Ressourcen der obersten Ebene unterstützen den Massenabruf über "list"-API-Methoden. Sie können beispielsweise Listen von Modulen oder Prüfungen abrufen. Diese Methoden geben paginierte Antworten nach einem standardisierten Ansatz zurück.
Listen-API-Methoden verwenden cursorbasierte Paginierung, angegeben durch das nextLink-Feld im Antworttext. Dieses Feld enthält eine undurchsichtige URL mit den Informationen, die zum Abrufen der nächsten Seite mit Ergebnissen erforderlich sind. Standardmäßig geben Listen-APIs 30 Elemente pro Anforderung zurück, aber Sie können die Seitengröße mithilfe des Parameters "maxpagesize" anpassen.
Unsere Client-SDK-Bibliotheken bieten Autopaginationshilfsprogramme, um alle Seiten einer Liste zu durchlaufen.