Microsoft Learnin hakemiston ohjelmointirajapinnan käytön parhaat käytännöt
Tässä artikkelissa kuvataan Learn-hakemiston ohjelmointirajapinnan käytön parhaat käytännöt.
Käyttöehtojen ymmärtäminen
Vaikka Learnin hakemiston ohjelmointirajapinta on julkisesti saatavilla ja käytettävissä maksutta, käyttäjiä koskevat Microsoftin ohjelmointirajapinnan käyttöehdot. Lue ja ymmärrä ohjelmointirajapinnan käyttöehdot ennen Learnin hakemiston ohjelmointirajapinnan käyttöä ja ennen tulosten sisällyttäminen mihinkään tuotantoympäristöön.
Tutustu Learn-hakemiston ohjelmointirajapinnan rajoituksiin
Katso rajoitukset artikkelista Learnin hakemiston ohjelmointirajapinnan ominaisuuksien yleiskatsaus.
Learn-sisältömallin ymmärtäminen
Jotta voit käyttää Learnin hakemiston ohjelmointirajapinnan vastausta tehokkaasti, on tärkeää ymmärtää Microsoft Learnissa käytettävissä olevan sisällön tyypit ja niiden väliset suhteet. Lisätietoja on Learnin sisältömallia käsittelevässä artikkelissa.
Eritoten:
- UID tarkoittaa yksilöivää tunnusta, ja se on yksilöllinen kullekin sisältöobjektille. Jos UID-tunnus muuttuu, vaikka otsikko tai muut metatiedot pysyvät samoina, sisältöä pidetään uutena objektina.
- Moduulit ovat Learn-harjoitusluettelon ydinobjekti. He kaikki kykenevät seisomaan yksin siinä mielessä, että he opettavat skenaarioita tai käsitteitä niiden sisältä, eivätkä vaadi edellytettävien moduulien käyttöä. Joillekin tämä on se, eivätkä he ole osa oppimispolkua. Toisille taas ne kootaan yhteen yhteen tai useampaan oppimispolkuun, joiden avulla käyttäjä voi luoda edistyneempiä käsitteitä. Moduulin ei tarvitse olla osa oppimispolkua, tai se voi olla osa yhtä tai useampaa.
- Yksiköitä ei kirjoiteta erillisenä sisältönä. Ne on tarkoitettu moduulia varten tietyssä järjestyksessä. Tästä syystä lisäämme linkin moduulin tietosivulle ja ensimmäiseen osioon, jotta käyttäjät voivat aloittaa siitä ja jatkaa sisällön läpi.
Tutustu siihen, miten lokalisointi toimii Learnissa ja miten lokalisoitu sisältö näkyy ohjelmointirajapinnan tulosteessa
Microsoft Learn tukee yli 65 kieliasetusta sivustossa, ja suuri osa sisällöstä on käännetty näille kielialueille. Pyrimme siihen, että sisältö olisi saatavilla kaikilla kielillä, joilla sisällössä opetettavat tuotteet ovat saatavilla, mutta kaikissa kieliasetuksen kokemuksissa ei ole saatavilla lokalisoitua sisältöä.
Kun kieliasetustietueessa ei ole käytettävissä siihen liittyvää käännöstä, sivuston sisältö ja ohjelmointirajapinnan vastaus "palataan" oletukseksi kieleen. Ohjelmointirajapinnan tulosteessa näet englannin metatiedot muissa kieliasetusvastauksissa, kun peruuntuminen tapahtuu. Sisällön URL-osoite kuitenkin viittaa yhä kieliasetukseen, vaikka pääsisältö saattaa palata takaisin ja syy on se, että käyttäjä voi edelleen siirtyä sivustolla kyseisellä alueella (jossa ylä-/alatunniste on käännetty ja muut linkit, joiden käännös on käytettävissä).
Kun englanninkieliseen sisältöön julkaistaan päivityksiä, lokalisointijaksot pyrimme saamaan lokalisoidut versiot päivitettyä mahdollisimman pian – yleensä muutaman päivän kuluessa alkuperäisestä muutoksesta.
Näet luettelon kaikista tuetuista aluekohtaisista aluekohtaisista alueista Microsoft Learn -sivuston alatunnisteessa (valitse haluamasi kieli). Kaikille kieliasetukselle voidaan tehdä kyselyitä Learnin hakemiston ohjelmointirajapinnalla käyttämällä locale-suodatinta.
Koulutussisällön täydennystietueet ovat aluekohtaisia eli emme erota sisällön lokalisoituja versioita erillisinä objekteina käyttäjän koulutuksen täydennystietueissa. Riippumatta siitä, millä kielellä käyttäjä suorittaa koulutuksen, hän saa kunnian kokonaisobjektista, emmekä tallenna viittausta siihen, millä kielellä se suoritettiin. Tämä kieliasetuksen riippumaton suorittaminen tarkoittaa sitä, että jos otat Learnin hakemiston ohjelmointirajapinnan käyttöön oppimiskokemuksessasi, sinun on otettava se huomioon. Jos lataat sisältöobjektit erillisinä objekteina, toteuta vastaavuus niiden välillä niin, että riippumatta siitä, millä kielellä käyttäjä suorittaa koulutuksen, hän saa siitä kunnian muilla kielillä eikä hänen tarvitse ottaa sitä uudelleen.
Opit ymmärtämään, miten sisällön versioinnit toimivat Learnissa ja miten se heijastuu ohjelmointirajapinnan tulosteeseen
Erityisesti sisältöä päivitetään koko ajan. Saatavilla olevat päivitykset julkaistaan kahdesti päivässä. Ne voivat olla pieniä, kuten vähäisiä tekstimuutoksia tai merkittäviä, kuten merkittäviä muutoksia, lisäyksiä tai poistoja. Yleisesti ottaen sisältösalkkua hallitaan valtavana, hyvin hallittuna avoimen lähdekoodin projektina, jossa on tuhansia osallistujia, ja näin ollen muutoksia tapahtuu jatkuvasti. Jos käytät Learnin hakemiston ohjelmointirajapintaa tuotantojärjestelmässäsi, sinun on syytä olla tietoinen tästä ja antaa järjestelmäsi käsitellä sitä.
Kun uusia sisältöobjekteja lisätään, ne näkyvät vastauksessa uutena objektina (yksilöitynä YKSILÖIVÄN tunnisteen avulla). Kun sisältöä muokataan, näet sen last_modified arvon perusteella. Kun sisältö poistetaan, sisältöobjekti poistetaan vastauksesta. Vaikka API-vastauksessa päivittyvässä sisällössä on joskus pieni viive, käyttäjä näkee aina ajantasaisimmat tiedot, kun käyttäjä seuraa sisällön URL-osoitetta. Jos poistat kohteen, vanha URL-osoite uudelleenohjataan uuteen sisältöön tai kokemukseen tai seuraavaan parhaaseen vaihtoehtoon.
Tällä hetkellä sisältöversioihin ei ole viittauksia last_modified päivämäärän jälkeen.
Tietojen päivittäminen säännöllisesti
Jos käytät Learnin hakemiston ohjelmointirajapinnan luettelotietoja liiketoimintaprosessiesi tukemiseen tai näytetään asiakkaille osana sivuston käyttökokemusta, varmista, että päivität sisällön vähintään kerran päivässä.
Erityisesti sisältöä päivitetään koko ajan. Saatavilla olevat päivitykset julkaistaan kahdesti päivässä. Ne voivat olla pieniä, kuten vähäisiä tekstimuutoksia tai merkittäviä, kuten merkittäviä muutoksia, lisäyksiä tai poistoja. Yleisesti ottaen sisältösalkkua hallitaan valtavana, hyvin hallittuna avoimen lähdekoodin projektina, jossa on tuhansia osallistujia, ja näin ollen muutoksia tapahtuu jatkuvasti. Jos käytät Learnin hakemiston ohjelmointirajapintaa tuotantojärjestelmässäsi, sinun on syytä olla tietoinen tästä ja antaa järjestelmäsi käsitellä sitä.
Kehittäjien dokumentaation suositusten tarkistaminen
Learnin hakemiston ohjelmointirajapinnan kehittäjän dokumentaatiossa on täydellinen luettelo vastaukseen osana annetuista tiedoista sekä suosituksia siitä, miten kutakin kenttää suositellaan käytettäväksi erinomaisia oppimiskokemuksia tukevina.
Kyselyn logiikan ymmärtäminen
Vastauksen esisuodatukseen on käytettävissä useita suodattimia, joten saat vain etsimäsi ja pystyt käsittelemään pienempiä tiedostokokoja. Näet luettelon kaikista kyselysuodattimista artikkelista Learnin hakemiston ohjelmointirajapinnan kehittäjäviiteartikkelista. Sinun on muotoutettava kysely oikein, ja jos käytät pyynnössä useampaa kuin yhtä kyselyparametria, kysely arvioidaan AND-operaattorin avulla.
Seuraavat vaiheet
Jos haluat lisätietoja, jotka tukevat learn-hakemiston ohjelmointirajapintaa, tutustu seuraaviin artikkeleihin: