Aanbevolen procedures voor het gebruik van de Microsoft Learn Catalog-API
In dit artikel worden de aanbevolen procedures beschreven voor het gebruik van de Learn Catalog-API.
Inzicht in de servicevoorwaarden
Hoewel de Learn Catalog-API openbaar beschikbaar is en gratis te gebruiken is, zijn gebruikers onderworpen aan de gebruiksvoorwaarden van de Microsoft-API. Lees en begrijp de API-gebruiksvoorwaarden voordat u de Learn Catalog-API gebruikt en voordat u de uitvoer in een productieomgeving opneemt.
De beperkingen van de Learn Catalog-API begrijpen
Zie beperkingen in het overzichtsartikel over de Learn Catalog-API-functie.
Meer informatie over learn tentmodus l
Als u het antwoord van de Learn Catalog-API effectief wilt gebruiken, is het belangrijk om inzicht te krijgen in de typen inhoud die beschikbaar zijn in Microsoft Learn en hun relaties met elkaar. Raadpleeg het artikel Learn con tentmodus l voor meer informatie.
Met name:
- UID staat voor Unieke id en is uniek voor elk inhoudsobject. Als een UID wordt gewijzigd, zelfs als de titel of andere metagegevens hetzelfde blijven, wordt de inhoud beschouwd als een nieuw object.
- Modules zijn het kernobject in de Learn-trainingscatalogus. Ze zijn allemaal in staat om alleen te staan, in de zin dat ze een scenario of concept end-to-end binnen hen leren en geen vereiste modules hoeven te nemen. Voor sommigen is dit het en ze maken geen deel uit van een leertraject. Voor anderen zijn ze gebundeld in een of meer leertrajecten die een gebruiker begeleiden bij het bouwen van geavanceerdere concepten. Een module hoeft geen deel uit te maken van een leertraject of kan deel uitmaken van een of meer.
- Eenheden worden niet geschreven als zelfstandige inhoud. Ze zijn bedoeld om in een specifieke volgorde voor de module te worden genomen. Daarom voegen we de koppeling naar de detailpagina van de module en de eerste eenheid, zodat gebruikers daar kunnen beginnen en verder kunnen gaan met de inhoud.
Begrijpen hoe lokalisatie werkt in Learn en hoe gelokaliseerde inhoud wordt weergegeven in de API-uitvoer
Microsoft Learn ondersteunt meer dan 65 landinstellingen op de site en veel van de inhoud wordt vertaald naar deze landinstellingen. We streven ernaar om de inhoud beschikbaar te maken in alle talen waarin de producten die in de inhoud worden geleerd, beschikbaar zijn in, maar niet alle landinstellingen hebben gelokaliseerde inhoud beschikbaar.
Wanneer de bijbehorende vertaling niet beschikbaar is voor een landinstellingsrecord, valt de inhoud op de site en het API-antwoord terug naar het Engels als de standaardinstelling. In de API-uitvoer ziet u Engelse metagegevens in andere landinstellingen wanneer er een terugval plaatsvindt. De URL naar de inhoud verwijst echter nog steeds naar de landinstelling, ook al kan de hoofdinhoud terugvallen en de reden hiervoor is dat de gebruiker nog steeds naar de site in die landinstelling navigeert (waarin de kop- en voettekst wordt weergegeven en elke andere koppeling die beschikbaar is voor vertaling).
Wanneer updates worden gepubliceerd naar de Engelse inhoud, werken onze lokalisatiepijplijnen om de gelokaliseerde versies zo snel mogelijk bijgewerkt te krijgen, meestal binnen een paar dagen na de oorspronkelijke wijziging.
U ziet een volledige lijst met ondersteunde landinstellingen in de voettekst van de Microsoft Learn-site (selecteer de taal die u bekijkt). Elk van deze landinstellingen kan worden opgevraagd met de Learn Catalog-API met behulp van het locale filter.
Onze records voor het voltooien van trainingsinhoud zijn landinstellingen, wat betekent dat we geen gelokaliseerde versies van inhoud onderscheiden als afzonderlijke objecten in de voltooiingsrecords voor gebruikerstraining. Ongeacht in welke taal een gebruiker een training heeft voltooid, ontvangen ze tegoed voor het algemene object en we slaan geen verwijzing op naar de taal waarin deze is voltooid. Deze locale-agnostische voltooiing betekent dat als u de Learn Catalog-API implementeert in uw leerervaring, rekening moet worden gehouden met deze API en, als u de inhoudsobjecten als afzonderlijke objecten laadt, een equivalentie tussen deze objecten implementeert, zodat de gebruiker, ongeacht de taal waarin de gebruiker de training voltooit, het tegoed krijgt in de andere talen en deze niet opnieuw hoeft te nemen.
Begrijpen hoe versiebeheer van inhoud werkt in Learn en hoe deze wordt weergegeven in de API-uitvoer
Inhoud wordt met name steeds bijgewerkt. We publiceren beschikbare updates twee keer per dag. Ze kunnen secundair zijn, zoals kleine tekstwijzigingen of primaire wijzigingen, zoals primaire revisies, toevoegingen of verwijderingen. Over het algemeen wordt het inhoudsportfolio beheerd als een enorm, uiterst beheerd opensource-project met duizenden inzenders, en als zodanig gebeuren er voortdurend wijzigingen. Als u de Learn Catalog-API in uw productiesysteem gebruikt, moet u hiervan op de hoogte zijn en moet u ervoor zorgen dat uw systeem dit kan verwerken.
Wanneer er nieuwe inhoudsobjecten worden toegevoegd, worden ze weergegeven als een nieuw object (geïdentificeerd door UID) in het antwoord. Wanneer inhoud wordt gewijzigd, kunt u dit zien op basis van de last_modified waarde. Wanneer inhoud wordt verwijderd, wordt het inhoudsobject verwijderd uit het antwoord. Hoewel er soms een kleine vertraging optreedt bij het bijwerken van inhoud in het API-antwoord, ziet een gebruiker altijd de meest recente informatie wanneer een gebruiker de URL naar de inhoud volgt. In het geval van verwijderingen wordt de oude URL omgeleid naar de nieuwe inhoud of ervaring of naar de volgende beste optie.
Er zijn op dit moment geen verwijzingen naar inhoudsversies meer dan de last_modified datum.
De gegevens regelmatig vernieuwen
Als u de catalogusgegevens van de Learn Catalog-API gebruikt om uw bedrijfsprocessen te ondersteunen of als onderdeel van uw site-ervaring weer te geven voor klanten, moet u ervoor zorgen dat u de inhoud ten minste één keer per dag vernieuwt.
Inhoud wordt met name steeds bijgewerkt. We publiceren beschikbare updates twee keer per dag. Ze kunnen secundair zijn, zoals kleine tekstwijzigingen of primaire wijzigingen, zoals primaire revisies, toevoegingen of verwijderingen. Over het algemeen wordt het inhoudsportfolio beheerd als een enorm, uiterst beheerd opensource-project met duizenden inzenders, en als zodanig gebeuren er voortdurend wijzigingen. Als u de Learn Catalog-API in uw productiesysteem gebruikt, moet u hiervan op de hoogte zijn en moet u ervoor zorgen dat uw systeem dit kan verwerken.
Bekijk de aanbevelingen in de documentatie voor ontwikkelaars
De documentatie voor ontwikkelaars van de Learn Catalog-API bevat een volledige lijst met de gegevens die worden geleverd als onderdeel van het antwoord en aanbevelingen over hoe elk veld wordt aanbevolen om te worden gebruikt om geweldige leerervaringen te ondersteunen.
Inzicht in de querylogica
Er zijn veel filters beschikbaar om het antwoord vooraf te filteren, zodat u alleen krijgt wat u zoekt en kleinere bestandsgrootten kan verwerken. U kunt de volledige lijst met queryfilters bekijken in het naslagartikel over ontwikkelaars van de Learn Catalog-API. Met name moet u de query correct vormen en als u meer dan één queryparameter in de aanvraag gebruikt, wordt de query geëvalueerd met behulp van de AND-operator.
Volgende stappen
Raadpleeg de volgende artikelen voor meer informatie die u kunt ondersteunen met de Learn Catalog-API: