Ajánlott eljárások a Microsoft Learn Catalog API használatához
Ez a cikk a Learn Catalog API használatának ajánlott eljárásait ismerteti.
A szolgáltatási feltételek ismertetése
Bár a Learn Catalog API nyilvánosan elérhető és ingyenesen használható, a felhasználókra a Microsoft API használati feltételei vonatkoznak. A Learn Catalog API használata előtt és a kimenet bármely éles környezetben való felvétele előtt olvassa el és ismerje meg az API használati feltételeit.
A Learn Catalog API korlátainak megismerése
Lásd a Learn Catalog API-funkció áttekintési cikkben található korlátozásokat.
A Learn-tartalommodell ismertetése
A Learn Catalog API-válasz hatékony használatához fontos tisztában lenni a Microsoft Learnben elérhető tartalomtípusokkal és az egymással való kapcsolatukkal. További információért tekintse át a Learn tartalommodell- című cikket.
Különösen:
- Az UID az Egyedi azonosítót jelenti, és minden tartalomobjektum esetében egyedi. Ha egy UID megváltozik, még akkor is, ha a cím vagy más metaadatok változatlanok maradnak, a tartalom új objektumnak minősül.
- A modulok a Learn betanítási katalógusának alapvető objektumai. Képesek önállóan működni, úgy, hogy teljes körűen bemutatnak egy forgatókönyvet vagy koncepciót, és nem igényelnek előzetes modulokat. Egyesek számára ez az, és nem részei a képzési tervnek. Mások számára egy vagy több képzési tervben vannak összecsomagolva, amelyek a felhasználót speciálisabb fogalmak kialakításán keresztül vezetik. Egy modulnak nem kell egy képzési terv részét képeznie, vagy egy vagy több része is lehet.
- Az egységek nem önálló tartalomként lesznek megírva. Ezeket a modulhoz meghatározott sorrendben kell megadni. Ezért a modul részletes lapjára és az első egységre mutató hivatkozást is mellékeljük, hogy a felhasználók ott kezdjenek, és végighaladjanak a tartalomon.
A honosítás működésének megismerése a Learnben, és hogy a honosított tartalom hogyan jelenik meg az API-kimenetben
A Microsoft Learn több mint 65 területi beállítás használatát támogatja a webhelyen, és a tartalom nagy része ezekre a területi beállításokra van lefordítva. Célunk, hogy a tartalom elérhető legyen az összes olyan nyelven, amelyen a tartalomban tanítandó termékek elérhetők, de nem minden területi felület rendelkezik elérhető honosított tartalommal.
Ha egy területi rekord nem rendelkezik a társított fordítással, a webhely tartalma és az API-válasz alapértelmezés szerint angolra "visszaesik". Az API-kimenetben angol metaadatok jelennek meg más helyi válaszokban, amikor visszaállás történik. A tartalom URL-címe azonban továbbra is a területi beállításra mutat, annak ellenére, hogy a fő tartalom visszaeshet, és ennek az az oka, hogy a felhasználó továbbra is navigálhat a webhelyen az adott területi beállításban (amely megjeleníti a lefordított élőfejet/élőlábat, valamint bármely más olyan hivatkozást, amely rendelkezik fordítással).
Amikor frissítéseket tesznek közzé az angol tartalomban, a honosítási folyamataink azon dolgoznak, hogy a honosított verziókat a lehető leghamarabb frissítsük – általában az eredeti módosítást követő néhány napon belül.
A támogatott területi beállítások teljes listáját a Microsoft Learn webhely láblécében tekintheti meg (válassza ki a megtekintett nyelvet). Ezen területi beállítások mindegyike lekérdezhető a Learn Catalog API-val a locale szűrő használatával.
A betanítási tartalom befejezési rekordjai területi alapúak, vagyis nem különböztetjük meg a tartalom honosított verzióit külön objektumként a felhasználói betanítási befejezési rekordokban. Függetlenül attól, hogy a felhasználó milyen nyelven végez betanítást, kreditet kap a teljes objektumért, és nem tárolunk hivatkozást arra, hogy milyen nyelven fejeződött be. Ez a helyfüggetlen befejezés azt jelenti, hogy ha a Learn Catalog API-t megvalósítja a tanulási élmény során, figyelembe kell vennie ezt, és ha külön objektumként tölti be a tartalomobjektumokat, egyenértékűséget kell megvalósítania közöttük. Így függetlenül attól, hogy a felhasználó melyik nyelven végzi el a képzést, a többi nyelven is kreditet kapjon, és ne kelljen újra teljesítenie.
A tartalom verziószámozásának működése a Learnben, és annak az API-kimenetben való tükröződése
A tartalom folyamatosan frissül. Naponta kétszer tesszük közzé az elérhető frissítéseket. Lehetnek kisebbek, mint például kisebb szövegmódosítások, vagy nagyobbak, mint például jelentős átdolgozások, kiegészítések vagy törlések. Általánosságban elmondható, hogy a tartalomportfólió egy hatalmas, szigorúan szabályozott nyílt forráskódú projekt, több ezer közreműködővel, és mint ilyen, folyamatosan változnak. Ha a Learn Catalog API-t használja az éles rendszerében, tisztában kell lennie ezzel, és biztosítania kell, hogy a rendszer képes legyen kezelni.
Új tartalomobjektumok hozzáadásakor a válaszban új (UID által azonosított) objektumként jelennek meg. Amikor a tartalmat módosítják, a last_modified értékéből lehet megállapítani. A tartalom törlésekor a rendszer eltávolítja a tartalomobjektumot a válaszból. Bár az API-válaszban néha némi késés tapasztalható a tartalom frissítésével kapcsolatban, amikor egy felhasználó követi a tartalom URL-címét, mindig a legfrissebb információkat fogja látni. Törlés esetén a régi URL-cím át lesz irányítva az új tartalomra vagy felületre, vagy a következő legjobb megoldásra.
A tartalomverziókra jelenleg nincs hivatkozás a last_modified dátumon túl.
Az adatok rendszeres frissítése
Ha a Learn Catalog API katalógusadatait használja az üzleti folyamatok támogatásához, vagy az ügyfelek számára a webhelyélmény részeként jeleníti meg őket, győződjön meg arról, hogy naponta legalább egyszer frissíti a tartalmat.
A tartalom folyamatosan frissül. Naponta kétszer tesszük közzé az elérhető frissítéseket. Lehetnek kisebbek, például kisebb szövegmódosítások, vagy nagyobbak, például nagyobb átdolgozások, kiegészítések vagy törlések. Általánosságban elmondható, hogy a tartalomportfólió egy hatalmas, szigorúan szabályozott nyílt forráskódú projekt, több ezer közreműködővel, és mint ilyen, folyamatosan változnak. Ha a Learn Catalog API-t használja az éles rendszerben, tisztában kell lennie ezzel, és meg kell győződnie arról, hogy a rendszer képes kezelni.
Tekintse át a fejlesztői dokumentáció ajánlásait
A Learn Catalog API fejlesztői dokumentációja a válasz részeként megadott adatok teljes listáját tartalmazza, valamint javaslatokat tartalmaz arra vonatkozóan, hogy az egyes mezők hogyan használhatók a nagyszerű tanulási élmények támogatására.
A lekérdezési logika ismertetése
A válasz előszűréséhez számos szűrő használható, így csak a keresett fájlokat kapja meg, és kisebb fájlméreteket kezelhet. A lekérdezésszűrők teljes listáját a Learn Catalog API Developer referenciacikkében. Nevezetesen helyesen kell létrehoznia a lekérdezést, és ha egynél több lekérdezési paramétert használ a kérelemben, a lekérdezés kiértékelése az AND operátor használatával történik.
Következő lépések
A Learn Catalog API-val való támogatásról az alábbi cikkekben olvashat bővebben: