Bewährte Methoden für die Verwendung der Microsoft Learn-Katalog-API
In diesem Artikel werden die bewährten Methoden für die Verwendung der Learn Catalog-API beschrieben.
Grundlegendes zu den Nutzungsbedingungen
Obwohl die Learn Catalog-API öffentlich verfügbar und kostenlos zu verwenden ist, unterliegen Benutzer den Microsoft-API-Nutzungsbedingungen. Lesen und verstehen Sie die API-Nutzungsbedingungen, bevor Sie die Learn-Katalog-API verwenden, und bevor Sie die Ausgabe in eine beliebige Produktionsumgebung einschließen.
Grundlegendes zu den Einschränkungen der Learn Catalog-API
Siehe Einschränkungen im Artikel Übersicht über das Lernkatalog-API-Feature.
Grundlegendes zum Lerninhaltsmodell
Um die Learn Catalog API-Antwort effektiv zu verwenden, ist es wichtig, die Typen von Inhalten zu verstehen, die in Microsoft Learn verfügbar sind, und deren Beziehungen zueinander. Weitere Informationen finden Sie im Artikel Learn Content Model.
Bemerkenswert:
- UID steht für Unique ID und ist für jedes Inhaltsobjekt eindeutig. Wenn eine UID geändert wird, auch wenn der Titel oder andere Metadaten gleich bleiben, wird der Inhalt als neues Objekt betrachtet.
- Module sind das Kernobjekt im Schulungskatalog "Learn". Sie sind alle unabhängig nutzbar, im Sinne davon, dass sie ein Szenario oder Konzept von Anfang bis Ende vollständig lehren und keine Vorkenntnisse erfordern. Für einige ist dies der Fall, und sie sind nicht Teil eines Lernpfads. Für andere werden sie in einem oder mehreren Lernpfaden gebündelt, die einen Benutzer durch die Erstellung komplexerer Konzepte führen. Ein Modul muss nicht Teil eines Lernpfads sein, oder es kann Teil eines oder mehrerer sein.
- Einheiten werden nicht als eigenständiger Inhalt geschrieben. Sie sollen in einer bestimmten Reihenfolge für das Modul eingenommen werden. Aus diesem Grund fügen wir den Link zur Moduldetailseite und die erste Einheit ein, damit Benutzer dort beginnen und den Inhalt durchlaufen können.
Verstehen, wie die Lokalisierung in Learn funktioniert und wie lokalisierte Inhalte in der API-Ausgabe widerspiegelt werden
Microsoft Learn unterstützt mehr als 65 Gebietsschemas auf der Website, und ein Großteil der Inhalte wird in diese Gebietsschemas übersetzt. Wir wollen die Inhalte in allen Sprachen verfügbar machen, in denen die in den Inhalten behandelten Produkte angeboten werden, aber nicht alle lokalen Umgebungen haben lokalisierte Inhalte zur Verfügung.
Wenn für einen Gebietsschemadatensatz die zugehörige Übersetzung nicht verfügbar ist, fällt der Inhalt der Website und die API-Antwort standardmäßig auf Englisch zurück. In der API-Ausgabe werden englische Metadaten in anderen Lokalisierungsantworten angezeigt, wenn ein Fallback auftritt. Die URL zu den Inhalten verweist jedoch weiterhin auf das Gebietsschema, obwohl der Hauptinhalt zurückfallen kann, und der Grund besteht darin, dem Benutzer die Navigation auf der Website in diesem Gebietsschema zu ermöglichen (die die übersetzte Kopf-/Fußzeile und alle anderen Links mit übersetzungsfähiger Übersetzung anzeigt).
Wenn Updates für den englischen Inhalt veröffentlicht werden, arbeiten unsere Lokalisierungspipelinen daran, die lokalisierten Versionen so schnell wie möglich zu aktualisieren – in der Regel innerhalb weniger Tage nach der ursprünglichen Änderung.
Sie können eine vollständige Liste der unterstützten Sprachen in der Fußzeile der Microsoft Learn-Website sehen (wählen Sie die Sprache aus, die Sie gerade ansehen). Jedes dieser Orte kann mithilfe der Learn Catalog API und dem locale-Filter abgefragt werden.
Unsere Aufzeichnungen zum Abschluss von Schulungsinhalten sind gebietsschemaunabhängig, was bedeutet, dass wir lokalisierte Versionen von Inhalten nicht als separate Objekte in unseren Aufzeichnungen zur Benutzerschulung unterscheiden. Unabhängig davon, in welcher Sprache ein Benutzer eine Schulung abgeschlossen hat, erhält er eine Gutschrift für das Gesamtobjekt, und wir speichern keinen Verweis darauf, in welcher Sprache er abgeschlossen wurde. Dieser abschlussunabhängige Ansatz bedeutet, dass, wenn Sie die Lernkatalog-API in Ihrer Lernerfahrung implementieren, Sie diese berücksichtigen müssen. Wenn Sie Inhaltsobjekte als separate Objekte laden, implementieren Sie eine Äquivalenz zwischen ihnen, damit der Benutzer unabhängig von der Sprache, in der er die Schulung abgeschlossen hat, eine Anerkennung in den anderen Sprachen erhält und sie nicht erneut absolvieren muss.
Verstehen Sie, wie die Inhaltsversionierung in Learn funktioniert und wie sie in der API-Ausgabe wiedergespiegelt wird.
Insbesondere werden Inhalte ständig aktualisiert. Wir veröffentlichen verfügbare Updates zweimal täglich. Sie können entweder geringfügig sein, z. B. geringfügige Textänderungen, oder bedeutend, z. B. Hauptänderungen, Ergänzungen oder Löschungen. Im Allgemeinen wird das Inhaltsportfolio als massives, stark reguliertes Open-Source-Projekt mit Tausenden von Mitwirkenden verwaltet, und als solche werden Änderungen ständig ausgeführt. Wenn Sie die Learn Catalog-API in Ihrem Produktionssystem verwenden, sollten Sie dies beachten und ihr System in der Lage sein, sie zu verarbeiten.
Wenn neue Inhaltsobjekte hinzugefügt werden, werden sie als neues Objekt (durch UID identifiziert) in der Antwort angezeigt. Wenn Inhalte geändert werden, können Sie anhand des last_modified Werts feststellen. Wenn Inhalte gelöscht werden, wird das Inhaltsobjekt aus der Antwort entfernt. Obwohl es manchmal eine leichte Verzögerung bei der Aktualisierung von Inhalten in der API-Antwort gibt, wird beim Folgen der URL zu den Inhalten immer die aktuellsten Informationen angezeigt. Bei Löschungen wird die alte URL an den neuen Inhalt oder die neue Oberfläche oder zur nächsten besten Option umgeleitet.
Derzeit gibt es keine Verweise auf Inhaltsversionen, die über das last_modified Datum hinausgehen.
Regelmäßiges Aktualisieren der Daten
Wenn Sie die Kataloginformationen aus der Learn Catalog-API verwenden, um Ihre Geschäftsprozesse zu unterstützen oder kunden als Teil Ihrer Websiteerfahrung anzuzeigen, stellen Sie sicher, dass Sie den Inhalt mindestens einmal pro Tag aktualisieren.
Insbesondere werden Inhalte ständig aktualisiert. Wir veröffentlichen verfügbare Updates zweimal täglich. Sie können entweder geringfügig sein, wie z. B. geringfügige Textänderungen, oder bedeutend, wie z. B. große Revisionen, Ergänzungen oder Löschungen. Im Allgemeinen wird das Inhaltsportfolio als massives, stark reguliertes Open-Source-Projekt mit Tausenden von Mitwirkenden verwaltet, und als solche werden Änderungen ständig ausgeführt. Wenn Sie die Learn Catalog-API in Ihrem Produktionssystem verwenden, sollten Sie dies beachten und ihr System in der Lage sein, sie zu verarbeiten.
Lesen Sie die Empfehlungen der Entwicklerdokumentation.
Die Lernkatalog-API-Entwicklerdokumentation enthält eine vollständige Liste der Daten, die als Teil der Antwort bereitgestellt werden, und Empfehlungen dazu, wie jedes Feld empfohlen wird, um großartige Lernerfahrungen zu unterstützen.
Grundlegendes zur Abfragelogik
Es stehen viele Filter zur Verfügung, um die Antwort vorab zu filtern, sodass Sie nur das gewünschte Element erhalten und kleinere Dateigrößen verarbeiten können. Die vollständige Liste der Abfragefilter finden Sie im Entwicklerreferenzartikel des Learn Catalog API . Insbesondere müssen Sie die Abfrage richtig bilden und wenn Sie mehrere Abfrageparameter in der Anforderung verwenden, wird die Abfrage mit dem AND-Operator bewertet.
Nächste Schritte
Weitere Informationen zur Unterstützung der Learn Catalog-API finden Sie in den folgenden Artikeln: