Dela via

Metodtips för att använda Microsoft Learn Catalog-API:et

  • Artikel

I den här artikeln beskrivs metodtipsen för att använda LEARN Catalog-API:et.

Förstå användarvillkoren

Även om Learn Catalog-API:et är offentligt tillgängligt och kostnadsfritt att använda, omfattas användarna av Användningsvillkor för Microsoft API. Läs och förstå användningsvillkoren för API:et innan du använder Learn Catalog API och innan du inkluderar utdata i en produktionsmiljö.

Förstå begränsningarna i Learn Catalog-API:et

Se Begränsningar i artikeln Learn Catalog API-funktionsöversikt.

Förstå Learn-innehållsmodellen

För att kunna använda svaret från Learn Catalog API på ett effektivt sätt är det viktigt att förstå vilka typer av innehåll som finns tillgängliga i Microsoft Learn och deras förhållanden till varandra. Mer information finns i artikeln Learn-innehållsmodell.

Särskilt:

  • UID står för Unikt ID och är unikt för varje innehållsobjekt. Om ett UID ändras, även om rubriken eller andra metadata förblir desamma, betraktas innehållet som ett nytt objekt.
  • Moduler är kärnobjektet i Utbildningskatalogen för Learn. De kan alla stå ensamma, i den meningen att de lär ut ett scenario eller koncept från början till slut inom sig och inte kräver några förkunskapsmoduler. För vissa är det här allt och de är inte en del av en lärandebana. För andra är de paketerade tillsammans i en eller flera utbildningsvägar som leder användaren genom att utveckla mer avancerade koncept. En modul behöver inte vara en del av en utbildningsväg, eller så kan den vara en del av en eller flera.
  • Enheter skrivs inte som fristående innehåll. De är avsedda att tas i en specifik ordning för modulen. Därför inkluderar vi länken till modulinformationssidan och den första enheten så att användarna kan börja där och fortsätta genom innehållet.

Förstå hur lokalisering fungerar i Learn och hur lokaliserat innehåll återspeglas i API-utdata

Microsoft Learn stöder över 65 nationella inställningar på webbplatsen och mycket av innehållet översätts till dessa nationella inställningar. Vi strävar efter att göra innehållet tillgängligt på alla språk som produkterna som lärs ut i innehållet är tillgängligt i, men inte alla språkupplevelser har lokaliserat innehåll tillgängligt.

När en lokalpost inte har den associerade översättningen tillgänglig, faller innehållet på webbplatsen och API-svaret tillbaka till engelska som standard. I API-resultat ser du engelska metadata i andra lokaliserade svar när fallback inträffar. Url:en till innehållet pekar dock fortfarande på språkvarianten, även om huvudinnehållet kan falla tillbaka och orsaken är att användaren fortfarande kan navigera på webbplatsen i det nationella språket (som visar sidhuvud/sidfot översatt och alla andra länkar som har översättning tillgänglig).

När uppdateringar publiceras till det engelska innehållet fungerar våra lokaliseringspipelines för att få de lokaliserade versionerna uppdaterade så snart som möjligt – vanligtvis inom några dagar efter den ursprungliga ändringen. Du kan se en fullständig lista över språk som stöds i sidfoten på webbplatsen Microsoft Learn (välj det språk du använder). Var och en av dessa nationella inställningar kan frågas med Learn Catalog API med hjälp av filtret locale.

Våra slutförandeposter för utbildningsinnehåll är platsspecifika, vilket innebär att vi inte särskiljer lokaliserade versioner av innehåll som separata objekt i våra användarutbildningars slutförandeposter. Oavsett vilket språk en användare slutför en utbildning i får de kredit för det övergripande objektet och vi lagrar inte någon referens till vilket språk det har slutförts i. Detta språkoberoende slutförande innebär att om du implementerar LEARN Catalog API i din inlärningsupplevelse måste du ta hänsyn till det och, om du läser in innehållsobjekten i som separata objekt, implementerar en likvärdighet mellan dem så att användaren, oavsett vilket språk som användaren slutför utbildningen i, får kredit för det på de andra språken och inte behöver göra om det.

Förstå hur versionshantering av innehåll fungerar i Learn och hur det återspeglas i API-utdata

I synnerhet uppdateras innehållet hela tiden. Vi publicerar tillgängliga uppdateringar två gånger om dagen. De kan antingen vara mindre, till exempel mindre textändringar eller större, till exempel större revisioner, tillägg eller borttagningar. I allmänhet hanteras innehållsportföljen som ett massivt, starkt styrt projekt med öppen källkod med tusentals deltagare, och därför sker ändringar hela tiden. Om du använder Learn Catalog-API:et i produktionssystemet bör du vara medveten om detta och låta systemet hantera det.

När nya innehållsobjekt läggs till visas de som ett nytt objekt (identifieras av UID) i svaret. När innehållet ändras kan du se baserat på dess last_modified värde. När innehållet tas bort tas innehållsobjektet bort från svaret. Även om det ibland uppstår en liten fördröjning på innehåll som uppdateras i API-svaret, visas alltid den senaste informationen när en användare följer URL:en till innehållet. När det gäller borttagningar omdirigeras den gamla URL:en till det nya innehållet eller upplevelsen, eller till det näst bästa alternativet.

Det finns inga referenser till innehållsversioner just nu efter last_modified datum.

Uppdatera data regelbundet

Om du använder kataloginformationen från Learn Catalog-API:et för att stödja dina affärsprocesser, eller om du visar för kunder som en del av din webbplatsupplevelse, kontrollerar du att du uppdaterar innehållet minst en gång om dagen.

I synnerhet uppdateras innehållet hela tiden. Vi publicerar tillgängliga uppdateringar två gånger om dagen. De kan antingen vara mindre, till exempel mindre textändringar eller större, till exempel större revisioner, tillägg eller borttagningar. I allmänhet hanteras innehållsportföljen som ett massivt, starkt styrt projekt med öppen källkod med tusentals deltagare, och därför sker ändringar hela tiden. Om du använder Learn Catalog-API:et i produktionssystemet bör du vara medveten om detta och låta systemet hantera det.

Granska rekommendationerna i utvecklardokumentationen

Utvecklardokumentationen för Learn Catalog API har en fullständig lista över data som tillhandahålls som en del av svaret och rekommendationer om hur varje fält rekommenderas för att användas för att stödja fantastiska inlärningsupplevelser.

Förstå frågelogik

Det finns många filter att använda för att förfiltrera svaret, så att du bara får det du letar efter och kan hantera mindre filstorlekar. Du kan se den fullständiga listan med frågefilter i referensartikeln Learn Catalog API Developer. I synnerhet måste du skapa frågan korrekt och om du använder mer än en frågeparameter i begäran utvärderas frågan med hjälp av AND-operatorn.

Nästa steg

Mer information om hur du stöder dig med Learn Catalog-API:et finns i följande artiklar: