Best Practices für die Verwendung der Microsoft Learn-Katalog-API

Artikel
05/17/2024

In diesem Artikel werden die Best Practices für die Verwendung der Learn-Katalog-API beschrieben.

Grundlegendes zu den Nutzungsbedingungen

Obwohl die Learn-Katalog-API öffentlich verfügbar ist und kostenlos verwendet werden kann, unterliegen die Benutzer*innen den Nutzungsbedingungen für Microsoft-APIs. Lesen und akzeptieren Sie die API-Nutzungsbedingungen, bevor Sie die Learn-Katalog-API verwenden und die Ausgabe in einer Produktionsumgebung übernehmen.

Grundlegendes zu den Einschränkungen der Learn-Katalog-API

Weitere Informationen finden Sie unter „Einschränkungen“ im Artikel Katalog-API von Microsoft Learn.

Grundlegendes zum Learn-Inhaltsmodell

Um die Antwort der Learn-Katalog-API effektiv nutzen zu können, ist es wichtig, die in Microsoft Learn verfügbaren Inhaltstypen und deren Zusammenhänge zu verstehen. Weitere Informationen finden Sie im Artikel Learn-Inhaltsmodell.

Es gilt:

UID steht für Unique ID (eindeutiger Bezeichner) und ist für jedes Inhaltsobjekt eindeutig. Wenn sich eine UID ändert, wird der Inhalt als neues Objekt betrachtet, auch wenn der Titel oder andere Metadaten identisch bleiben.
Module sind das wichtigste Objekt im Learn-Schulungskatalog. Sie können in dem Sinne eigenständig sein, dass sie ein Szenario oder ein Konzept komplett vermitteln und die Absolvierung von Vorgängermodulen nicht erforderlich ist. In manchen Fällen ist das alles, und die Module gehören nicht zu einem Lernpfad. In anderen Fällen sind Module zu einem Lernpfad (oder mehreren Lernpfaden) gebündelt, bei denen fortgeschrittene Konzepte vermittelt werden. Ein Modul ist nicht zwingend Teil eines Lernpfads, aber es kann in einem oder mehreren Lernpfaden vorkommen.
Die Lerneinheiten sind nicht als eigenständige Inhalte konzipiert. Sie sollen in der im Modul vorgesehenen Reihenfolge absolviert werden. Deswegen haben wir den Link auf der Moduldetailseite und in der ersten Einheit hinzugefügt. Benutzer können an dieser Stelle beginnen und dann mit den weiteren Inhalten fortfahren.

Funktionsweise der Lokalisierung in Learn und der Wiedergabe lokalisierter Inhalte in der API-Ausgabe

Microsoft Learn unterstützt mehr als 65 Gebietsschemas auf der Website, und ein Großteil der Inhalte wird in diese Gebietsschemas übersetzt. Ziel ist es, die Inhalte in allen Sprachen verfügbar zu machen, in denen die jeweils beschriebenen Produkte erhältlich sind, noch sind jedoch nicht in allen Gebietsschemas sämtliche lokalisierte Inhalte verfügbar.

Wenn für einen Gebietsschemadatensatz die zugehörige Übersetzung nicht verfügbar ist, werden die Inhalte auf der Website und die API-Antwort standardmäßig auf Englisch angezeigt. In der API-Ausgabe werden in Antworten in anderen Gebietsschemas bei einem Fallback englische Metadaten angezeigt. Die URL zu den Inhalten verweist jedoch weiterhin auf das Gebietsschema, obwohl der Hauptinhalt in diesem nicht verfügbar sein kann. Der Grund ist, dass Benutzerinnen und Benutzern die Navigation auf der Website in diesem Gebietsschema (mit übersetzten Kopf-/Fußzeilen und Links zu Inhalten mit verfügbaren Übersetzungen) ermöglicht werden soll.

Wenn Updates des englischsprachigen Inhalts veröffentlicht werden, arbeiten unsere Lokalisierungspipelines daran, die lokalisierten Versionen so schnell wie möglich zu aktualisieren – in der Regel innerhalb weniger Tage nach der ursprünglichen Änderung. Eine vollständige Liste der unterstützten Gebietsschemas wird in der Fußzeile der Website angezeigt (wählen Sie die aktuelle Sprache aus). Jedes dieser Gebietsschemas kann mit der Learn-Katalog-API mithilfe des locale-Filters abgefragt werden.

Unsere Datensätze zur Absolvierung von Schulungsinhalten sind unabhängig vom Gebietsschema, was bedeutet, dass wir lokalisierte Versionen von Inhalten nicht als separate Objekte in unseren Datensätzen zur Absolvierung von Benutzerschulungen unterscheiden. Unabhängig davon, in welcher Sprache Benutzerinnen und Benutzer eine Schulung abgeschlossen haben, erhalten sie einen Abschluss für das allgemeine Thema. Es werden auch keine Hinweise darauf gespeichert, in welcher Sprache sie abgeschlossen wurde. Sie müssen diesen gebietsschemaunabhängigen Abschluss bei einer Implementierung der Learn-Katalog-API in Ihrer Lernerfahrung berücksichtigen. Wenn Sie Inhaltsobjekte als separate Objekte laden, müssen Sie außerdem einen Abgleich zwischen ihnen implementieren, damit Ihre Benutzerinnen und Benutzer unabhängig von der Sprache, in der sie die Schulung abschließen, auch einen Abschluss in den anderen Sprachen erhalten und sie nicht erneut absolvieren müssen.

Funktionsweise der Inhaltsversionsverwaltung in Learn und Wiedergabe in der API-Ausgabe

Die Inhalte werden ständig aktualisiert. Verfügbare Updates werden zweimal täglich veröffentlicht. Dabei kann es sich entweder um geringfügige Änderungen (z. B. kleinere Änderungen am Text) oder um umfangreiche Änderungen (z. B. größere Überarbeitungen, Ergänzungen oder Löschungen) handeln. Allgemein wird das Inhaltsportfolio wie ein umfangreiches, stark reglementiertes Open-Source-Projekt mit Tausenden von Mitwirkenden verwaltet, weshalb ständig Änderungen vorgenommen werden. Wenn Sie die Learn-Katalog-API in Ihrem Produktionssystem verwenden, sollten Sie sich darüber im Klaren sein. Außerdem sollte Ihr System in der Lage sein, damit umzugehen.

Wenn neue Inhaltsobjekte hinzugefügt werden, werden sie in der Antwort (anhand der UID) als neues Objekt angezeigt. Wenn Inhalte geändert werden, können Sie dies anhand des Werts „last_modified“ feststellen. Wenn Inhalte gelöscht werden, wird das Inhaltsobjekt aus der Antwort entfernt. Obwohl es manchmal eine leichte Verzögerung beim Aktualisieren von Inhalten in der API-Antwort gibt, werden immer die aktuellsten Informationen angezeigt, wenn Benutzer*innen der URL zum Inhalt folgen. Bei Löschungen wird die alte URL an die neuen Inhalte oder Umgebungen oder zur nächstbesten Option umgeleitet.

Derzeit gibt es keine Hinweise auf Inhaltsversionen, die über das Datum last_modified hinausgehen.

Regelmäßiges Aktualisieren der Daten

Wenn Sie die Kataloginformationen aus der Learn-Katalog-API verwenden, um Ihre Geschäftsprozesse zu unterstützen oder um sie Kunden als Teil Ihrer Website anzuzeigen, stellen Sie sicher, dass Sie den Inhalt mindestens einmal am Tag aktualisieren.

Überprüfen der Empfehlungen in der Entwicklerdokumentation

Die Entwicklerdokumentation zur Learn-Katalog-API enthält eine vollständige Liste der Daten, die als Teil der Antwort bereitgestellt werden, sowie Empfehlungen, wie jedes Feld zur Unterstützung des Lernprozesses verwendet werden sollte.

Grundlegendes zur Abfragelogik

Es stehen zahlreiche Filter zur Verfügung, mit denen die Antworten vorab gefiltert werden können, sodass Sie nur das erhalten, wonach Sie suchen, und kleinere Dateigrößen verarbeitet werden können. Die vollständige Liste der Abfragefilter finden Sie im Artikel Entwicklerreferenz zur Learn-Katalog-API. Insbesondere müssen Sie die Abfrage richtig bilden. Falls Sie mehrere Abfrageparameter in der Anforderung verwenden, wird die Abfrage mit dem UND-Operator ausgewertet.

Nächste Schritte

Weitere Informationen zur Learn-Katalog-API finden Sie in den folgenden Artikeln:

Freigeben über