Bedste fremgangsmåder til brug af Microsoft Learn Catalog-API'en
I denne artikel beskrives de bedste fremgangsmåder til brug af Learn Catalog-API'en.
Forstå servicebetingelserne
Selvom Learn Catalog-API'en er offentligt tilgængelig og gratis at bruge, er brugerne underlagt Vilkår for anvendelse af Microsoft API. Læs og forstå API'ens vilkår for anvendelse, før du bruger Learn Catalog-API'en, og før du inkluderer outputtet i et hvilket som helst produktionsmiljø.
Forstå begrænsningerne i Learn Catalog-API'en
Se Begrænsninger i artiklen Oversigt over funktionsoversigten for Api-kataloget til Learn.
Forstå learn con telttilstand l
Hvis du vil bruge API-svaret til Learn-kataloget effektivt, er det vigtigt at forstå de typer indhold, der er tilgængelige i Microsoft Learn, og deres relationer til hinanden. Se artiklen Learn con telttilstand l for at få flere oplysninger.
Især:
- UID står for Entydigt id og er entydigt for hvert indholdsobjekt. Hvis et UID ændres, selvom titlen eller andre metadata forbliver det samme, betragtes indholdet som et nyt objekt.
- Moduler er kerneobjektet i læringskataloget. De er alle i stand til at stå alene i den forstand, at de underviser i et scenarie eller et koncept fra ende til anden i dem og ikke kræver, at de tager forudsætningsmoduler. For nogle er dette det hele, og de er ikke en del af et læringsforløb. For andre er de samlet i et eller flere læringsforløb, der fører en bruger gennem opbygning af mere avancerede koncepter. Et modul behøver ikke at være en del af et læringsforløb, eller det kan være en del af et eller flere.
- Enheder skrives ikke som separat indhold. De er beregnet til at blive taget i en bestemt rækkefølge for modulet. Derfor inkluderer vi linket til siden med moduloplysninger og den første enhed, så brugerne kan starte der og fortsætte gennem indholdet.
Forstå, hvordan lokalisering fungerer i Learn, og hvordan lokaliseret indhold afspejles i API-outputtet
Microsoft Learn understøtter mere end 65 landestandarder på webstedet, og meget af indholdet oversættes til disse landestandarder. Vi tilstræber at gøre indholdet tilgængeligt på alle de sprog, som de produkter, der undervises i i indholdet, er tilgængelige i, men ikke alle landestandardoplevelser har lokaliseret indhold tilgængeligt.
Når en landestandardpost ikke har den tilknyttede oversættelse tilgængelig, falder indholdet på webstedet og API-svaret "tilbage" til engelsk som standard. I API-outputtet kan du se engelske metadata i andre landestandardsvar, når der opstår tilbagefald. URL-adressen til indholdet peger dog stadig på landestandarden, selvom hovedindholdet kan falde tilbage, og årsagen er, at brugeren stadig skal kunne navigere på webstedet i den pågældende landestandard (som viser det oversatte sidehoved/sidefod og alle andre links, hvor oversættelse er tilgængelig).
Når der publiceres opdateringer til det engelske indhold, arbejder vores lokaliseringspipelines på at få de oversatte versioner opdateret så hurtigt som muligt – normalt inden for et par dage efter den oprindelige ændring.
Du kan se en komplet liste over understøttede landestandarder i microsoft Learn-webstedsfoden (vælg det sprog, du får vist). Hver af disse landestandarder kan forespørges med Learn Catalog-API'en ved hjælp af locale filteret.
Vores poster for fuldførelse af oplæringsindhold er landestandardagnostiske, hvilket betyder, at vi ikke skelner oversatte versioner af indhold som separate objekter i vores poster for fuldførelse af brugertræning. Uanset hvilket sprog en bruger fuldfører en oplæring på, modtager vedkommende kredit for det overordnede objekt, og vi gemmer ikke en reference til, hvilket sprog den blev fuldført på. Denne fuldførelse af landestandardagnostisk betyder, at hvis du implementerer Learn Catalog-API'en i din læringsoplevelse, skal du tage den i betragtning, og hvis du indlæser indholdsobjekterne som separate objekter, skal du implementere en ækvivalens mellem dem, så uanset hvilket sprog brugeren fuldfører træningen på, får vedkommende kredit for den på de andre sprog og ikke behøver at tage den igen.
Forstå, hvordan versionsstyring af indhold fungerer i Learn, og hvordan det afspejles i API-outputtet
Især opdateres indhold hele tiden. Vi publicerer tilgængelige opdateringer to gange om dagen. De kan enten være mindre, f.eks. mindre tekstændringer eller større, f.eks. større ændringer, tilføjelser eller sletninger. Indholdsporteføljen administreres generelt som et massivt, højt styret projekt med åben kildekode med tusindvis af bidragydere, og som sådan sker der ændringer hele tiden. Hvis du bruger Learn Catalog-API'en i dit produktionssystem, skal du være opmærksom på dette og have dit system i stand til at håndtere det.
Når der tilføjes nye indholdsobjekter, vises de som et nyt objekt (identificeret af UID) i svaret. Når indhold ændres, kan du se det på baggrund af dens last_modified værdi. Når indhold slettes, fjernes indholdsobjektet fra svaret. Selvom der nogle gange er en lille forsinkelse i indhold, der opdateres i API-svaret, når en bruger følger URL-adressen til indholdet, får vedkommende altid vist de mest aktuelle oplysninger. I tilfælde af sletninger omdirigerer den gamle URL-adresse til det nye indhold eller den nye oplevelse eller til den næste bedste mulighed.
Der er ingen referencer til indholdsversioner på nuværende tidspunkt efter last_modified datoen.
Opdater dataene regelmæssigt
Hvis du bruger katalogoplysningerne fra Learn Catalog-API'en til at understøtte dine forretningsprocesser eller vise for kunder som en del af din webstedsoplevelse, skal du sørge for at opdatere indholdet mindst én gang om dagen.
Især opdateres indhold hele tiden. Vi publicerer tilgængelige opdateringer to gange om dagen. De kan enten være mindre, f.eks. mindre tekstændringer eller større, f.eks. større ændringer, tilføjelser eller sletninger. Indholdsporteføljen administreres generelt som et massivt, højt styret projekt med åben kildekode med tusindvis af bidragydere, og som sådan sker der ændringer hele tiden. Hvis du bruger Learn Catalog-API'en i dit produktionssystem, skal du være opmærksom på dette og have dit system i stand til at håndtere det.
Gennemse anbefalingerne i udviklerdokumentationen
Udviklerdokumentationen til Learn Catalog API indeholder en komplet liste over de data, der er angivet som en del af svaret, og anbefalinger til, hvordan hvert felt anbefales at blive brugt til at understøtte gode læringsoplevelser.
Forstå forespørgselslogikken
Der er mange tilgængelige filtre, der kan bruges til at filtrere svaret på forhånd, så du kun får det, du leder efter, og kan håndtere mindre filstørrelser. Du kan se den komplette liste over forespørgselsfiltre i artiklen Udviklerreference til Learn Catalog API. Du skal især oprette forespørgslen korrekt, og hvis du bruger mere end én forespørgselsparameter i anmodningen, vurderes forespørgslen ved hjælp af operatoren AND.
Næste trin
Du kan finde flere oplysninger om, hvordan du bruger API'en til Learn Catalog, i følgende artikler: