Osvědčené postupy pro používání rozhraní API katalogu Microsoft Learn

Článek
10/05/2023

Tento článek popisuje osvědčené postupy pro používání rozhraní API katalogu Learn.

Vysvětlení podmínek služby

I když je rozhraní API katalogu Learn veřejně dostupné a bezplatné, uživatelé podléhají podmínkám použití rozhraní MICROSOFT API. Před použitím rozhraní API Catalog API a před zahrnutím výstupu do libovolného produkčního prostředí si přečtěte a seznamte se s podmínkami použití rozhraní API.

Vysvětlení omezení rozhraní API katalogu Learn

Viz Omezení v článku Přehled funkcí rozhraní API katalogu Learn.

Vysvětlení con learn režim stanu l

Aby bylo možné efektivně používat odpověď rozhraní API katalogu Learn, je důležité porozumět typům obsahu, které jsou k dispozici v Microsoft Learn, a jejich vztahům mezi sebou. Další informace najdete v článku Learn con režim stanu l.

Zejména:

UID je zkratka "Unique ID" (Jedinečné ID) a je jedinečná pro každý objekt obsahu. Pokud se UID změní, i když název nebo jiná metadata zůstanou stejná, považuje se obsah za nový objekt.
Moduly jsou základním objektem v katalogu školení Learn. Všichni jsou schopni stát sám, v tom smyslu, že učí scénář nebo koncept v nich a nevyžadují přijetí požadovaných modulů. Pro některé je to a nejsou součástí studijního programu. Pro ostatní jsou seskupené do jednoho nebo více studijních programů, které uživatele provedou vytvářením pokročilejších konceptů. Modul nemusí být součástí studijního programu nebo může být součástí jednoho nebo více modulů.
Jednotky nejsou napsané jako samostatný obsah. Mají být převzaty v určitém pořadí pro modul. Z tohoto důvodu zahrneme odkaz na stránku podrobností modulu a první lekci, aby uživatelé mohli začít tam a pokračovat v obsahu.

Vysvětlení toho, jak lokalizace funguje ve funkci Learn a jak se lokalizovaný obsah odráží ve výstupu rozhraní API

Microsoft Learn podporuje více než 65 národních prostředí na webu a velká část obsahu byla přeložena do těchto národních prostředí. Snažíme se zpřístupnit obsah ve všech jazycích, ve kterých jsou produkty, které se učí v obsahu, k dispozici, ale ne všechny prostředí národního prostředí mají k dispozici přeložený obsah.

Pokud záznam národního prostředí nemá k dispozici přidružený překlad, obsah na webu a odpověď rozhraní API se jako výchozí vrátí do angličtiny. V případě výstupu rozhraní API uvidíte anglická metadata v jiných odpovědích národního prostředí, když dojde k návratu. Adresa URL obsahu ale bude stále odkazovat na národní prostředí, i když se hlavní obsah může vrátit a důvodem je umožnit uživateli, aby stále přecházel na web v tomto národním prostředí (který bude zobrazovat přeložené záhlaví/zápatí a jakýkoli jiný odkaz, který má k dispozici překlad).

Když jsou aktualizace publikovány v anglickém obsahu, naše lokalizační kanály fungují tak, aby se lokalizované verze co nejdříve aktualizovaly – obvykle do několika dnů od původní změny. Úplný seznam podporovaných národních prostředí můžete zobrazit v zápatí webu Microsoft Learn (vyberte jazyk, který si prohlížíte). Každé z těchto národních prostředí se dá dotazovat pomocí rozhraní API katalogu Learn pomocí locale filtru.

Naše záznamy dokončení trénovacího obsahu jsou nezávislé na národním prostředí, což znamená, že v záznamech dokončení trénování uživatelů nerozlišujeme lokalizované verze obsahu jako samostatné objekty. Bez ohledu na to, v jakém jazyce uživatel dokončí trénování, obdrží kredit pro celkový objekt a neukládáme odkaz na jazyk, ve který byl dokončen. Toto doplňování nezávislé na národním prostředí znamená, že pokud ve svém výukovém prostředí implementujete rozhraní API služby Learn Catalog, budete ho muset vzít v úvahu a pokud načtete objekty obsahu jako samostatné objekty, implementujte mezi nimi ekvivalenci, aby bez ohledu na jazyk, ve kterém uživatel dokončí trénování, získal kredit v ostatních jazycích a nemusel ho znovu využívat.

Vysvětlení toho, jak funguje správa verzí obsahu ve službě Learn a jak se odráží ve výstupu rozhraní API

Obsah se zejména neustále aktualizuje. Aktualizace publikujeme obvykle dvakrát denně. Můžou se jednat buď o menší změny textu, nebo o hlavní změny, jako jsou hlavní revize, doplňky nebo odstranění. Obecně platí, že portfolio obsahu se spravuje jako masivní opensourcový opensourcový projekt s tisíci přispěvatelů a jako takové se neustále mění. Pokud ve svém produkčním systému používáte rozhraní API katalogu Learn, měli byste o tom vědět a mít systém schopný ho zpracovat.

Když se přidají nové objekty obsahu, zobrazí se v odpovědi jako nový objekt (identifikovaný UID). Při úpravě obsahu můžete zjistit na základě jeho last_modified hodnoty. Když se obsah odstraní, odebere se z odpovědi. I když v odpovědi rozhraní API občas dochází k mírnému zpoždění při aktualizaci obsahu, když uživatel sleduje adresu URL obsahu, vždy uvidí nejaktuálnější informace. V případě odstranění se stará adresa URL přesměruje na nový obsah nebo prostředí.

V tuto chvíli neexistují žádné odkazy na verze obsahu nad datem last_modified .

Pravidelně aktualizujte data.

Pokud k podpoře obchodních procesů nebo zobrazení pro zákazníky v rámci prostředí webu používáte informace o katalogu z rozhraní API pro katalog Learn, ujistěte se, že obsah aktualizujete alespoň jednou denně.

Projděte si doporučení v dokumentaci pro vývojáře.

Dokumentace pro vývojáře rozhraní API služby Learn Catalog obsahuje úplný seznam dat, která jsou součástí odpovědi, a doporučení týkající se toho, jak se každé pole doporučuje použít k podpoře skvělých výukových prostředí.

Vysvětlení logiky dotazu

K dispozici je mnoho filtrů, které můžete použít k předběžnému filtrování odpovědi, abyste získali jenom to, co hledáte, a mohli zpracovat menší velikosti souborů. Úplný seznam filtrů dotazů najdete v referenčním článku k rozhraní API služby Learn Catalog. Zejména budete muset správně vytvořit dotaz a pokud v požadavku používáte více než jeden parametr dotazu, bude dotaz vyhodnocen pomocí operátoru AND.

Další kroky

Další informace, které vám pomůžou s rozhraním API katalogu Learn, najdete v následujících článcích: