Anbefalte fremgangsmåter for bruk av Katalog-API for Microsoft Learn

Artikkel
05/15/2024

Denne artikkelen beskriver de anbefalte fremgangsmåtene for bruk av API-en for Learn-katalogen.

Forstå vilkårene for bruk

Selv om API-en for Learn-katalogen er offentlig tilgjengelig og gratis å bruke, er brukere underlagt vilkårene for bruk av Microsoft API. Les og forstå API-vilkårene for bruk før du bruker Learn-katalog-API-en og før du inkluderer utdataene i et produksjonsmiljø.

Forstå begrensningene i Learn-katalog-API-en

Se begrensninger i oversiktsartikkelen Learn Catalog API Feature.

Forstå Learn con teltmodus l

Hvis du vil bruke Learn Catalog API-svaret effektivt, er det viktig å forstå hvilke typer innhold som er tilgjengelig i Microsoft Learn og deres relasjoner til hverandre. Se artikkelen Learn con teltmodus l hvis du vil ha mer informasjon.

Spesielt:

UID står for unik ID og er unik for hvert innholdsobjekt. Hvis en UID endres, selv om tittelen eller andre metadata forblir den samme, regnes innholdet som et nytt objekt.
Moduler er kjerneobjektet i Learn-opplæringskatalogen. De er alle i stand til å stå alene, i den forstand at de underviser et scenario eller konsept ende-til-ende i dem og ikke krever å ta nødvendige moduler. For noen er dette det, og de er ikke en del av et læringsforløp. For andre er de samlet i ett eller flere læringsforløp som tar en bruker gjennom å bygge mer avanserte konsepter. En modul trenger ikke å være en del av et læringsforløp, eller den kan være en del av én eller flere.
Enheter skrives ikke som frittstående innhold. De er ment å bli tatt i en bestemt rekkefølge for modulen. Av denne grunn inkluderer vi koblingen til modulens detaljside og den første enheten slik at brukerne kan starte der og fortsette gjennom innholdet.

Forstå hvordan lokalisering fungerer i Learn og hvordan lokalisert innhold gjenspeiles i API-utdataene

Microsoft Learn støtter over 65 nasjonale innstillinger på nettstedet, og mye av innholdet oversettes til disse nasjonale innstillingene. Vi tar sikte på å gjøre innholdet tilgjengelig på alle språkene som produktene som undervises i innholdet, er tilgjengelige i, men ikke alle nasjonale innstillinger har lokalisert innhold tilgjengelig.

Når en nasjonal innstillingspost ikke har den tilknyttede oversettelsen tilgjengelig, faller innholdet på nettstedet og API-svaret «tilbake» til engelsk som standard. I API-utdataene ser du engelske metadata i andre nasjonale svar når tilbakefall skjer. URL-adressen til innholdet peker imidlertid fortsatt til den nasjonale innstillingen, selv om hovedinnholdet kan falle tilbake, og årsaken er å la brukeren fortsatt navigere området i den nasjonale innstillingen (som viser toppteksten/bunnteksten oversatt, og eventuelle andre koblinger som har oversettelse tilgjengelig).

Når oppdateringer publiseres til det engelske innholdet, fungerer lokaliseringssamlebåndene våre for å få de lokaliserte versjonene oppdatert så snart som mulig – vanligvis innen noen få dager etter den opprinnelige endringen. Du kan se en fullstendig liste over støttede nasjonale innstillinger i microsoft Learn-bunnteksten (velg språket du viser). Hver av disse nasjonale innstillingene kan spørres med Learn-katalog-API-en ved hjelp av filteret locale .

Fullføringspostene for opplæringsinnhold er nasjonale agnostiske, noe som betyr at vi ikke skiller lokaliserte versjoner av innhold som separate objekter i fullføringspostene for brukeropplæring. Uansett hvilket språk en bruker fullfører en opplæring i, mottar de kreditt for det generelle objektet, og vi lagrer ikke en referanse til hvilket språk den ble fullført i. Denne nasjonale agnostiske fullføringen betyr at hvis du implementerer Learn-katalog-API-en i læringsopplevelsen, må du ta hensyn til den, og hvis du laster inn innholdsobjektene i som separate objekter, implementerer du en likhet mellom dem, slik at uansett hvilket språk brukeren fullfører opplæringen i, får de æren for det på de andre språkene og slipper å ta det på nytt.

Forstå hvordan versjonskontroll av innhold fungerer i Learn og hvordan det gjenspeiles i API-utdataene

Innhold oppdateres spesielt hele tiden. Vi publiserer tilgjengelige oppdateringer to ganger om dagen. De kan enten være underordnede, for eksempel mindre tekstendringer eller hovedendringer, for eksempel store revisjoner, tillegg eller slettinger. Generelt behandles innholdsporteføljen som et massivt, høyt styrt åpen kildekode-prosjekt med tusenvis av bidragsytere, og derfor skjer endringer hele tiden. Hvis du bruker learn-katalog-API-en i produksjonssystemet, bør du være oppmerksom på dette og få systemet til å håndtere det.

Når nye innholdsobjekter legges til, vises de som et nytt objekt (identifisert av UID) i svaret. Når innholdet endres, kan du se basert på den last_modified verdien. Når innhold slettes, fjernes innholdsobjektet fra svaret. Selv om det noen ganger er en liten forsinkelse på innhold som oppdateres i API-svaret, vil de alltid se den nyeste informasjonen når en bruker følger nettadressen til innholdet. Når det gjelder slettinger, omdirigeres den gamle nettadressen til det nye innholdet eller opplevelsen, eller til det nest beste alternativet.

Det finnes ingen referanser til innholdsversjoner på dette tidspunktet utover last_modified datoen.

Oppdater dataene regelmessig

Hvis du bruker kataloginformasjonen fra Learn-katalog-API-en til å støtte forretningsprosesser eller vise for kunder som en del av nettstedsopplevelsen, må du kontrollere at du oppdaterer innholdet minst én gang om dagen.

Se gjennom anbefalingene utviklerdokumentasjonen

Utviklerdokumentasjonen for Learn Catalog API har en fullstendig liste over dataene som er angitt som en del av svaret, og anbefalinger om hvordan hvert felt anbefales å brukes til å støtte gode læringsopplevelser.

Forstå spørringslogikken

Det finnes mange filtre som kan brukes til å forhåndsfiltrere svaret, slik at du bare får det du leter etter og kan håndtere mindre filstørrelser. Du kan se den fullstendige listen over spørringsfiltre i referanseartikkelen Learn Catalog API Developer. Spesielt må du danne spørringen riktig, og hvis du bruker mer enn én spørringsparameter i forespørselen, vurderes spørringen ved hjelp av AND-operatoren.

Neste trinn

Hvis du vil ha mer informasjon for å støtte deg med API-en for Learn-katalogen, kan du se følgende artikler:

Del via