Začínáme s rozhraním API platformy Microsoft Learn

Tento článek vám pomůže začít používat rozhraní API platformy Microsoft Learn. Pokud neznáte podrobnosti rozhraní API nebo případy použití, doporučujeme nejprve projít si článek Přehled rozhraní API platformy Microsoft Learn .

Ověřování rozhraní API platformy Learn

Rozhraní REST API platformy Learn používají k ověřování Microsoft Entra ID. Před voláním rozhraní API musíte zvolit metodu přístupu a klientská aplikace se musí ověřit pomocí platných přihlašovacích údajů.

Přístup jen pro aplikace

Když vaše aplikace přistupuje přímo k aplikaci Learn, její přístup není svázaný s žádným uživatelem. Aplikace volá rozhraní API přímo pomocí vlastní identity. Tento scénář je přístup jen pro aplikace. Další informace najdete na platformě Microsoft Identity Platform.

Abyste mohli začít, potřebujete platnou identitu na platformě Microsoft Identity Platform, což může být registrace aplikace nebo spravovaná identita. V ideálním případě by měl mít každý partner jednu identitu, aby zjednodušil kvótu a správu partnerů. Použití spravované identity přiřazené uživatelem může pomoct sjednotit spravované identity napříč různými službami.

Jakmile nastavíte svou identitu v Entra ID, získejte z Entra ID přístupový token, jehož obor je nastaven pro jako důkaz ověření. Při vytváření požadavků rozhraní REST API na Learn zahrňte přístupový token do hlavičky autorizace HTTP.

Delegovaný přístup

Když se uživatel přihlásí k aplikaci a použije ji pro přístup k aplikaci Learn, musí nejprve požádat o oprávnění pro přístup k tomuto prostředku jménem uživatele. Tento scénář se nazývá delegovaný přístup. Další informace najdete na platformě Microsoft Identity Platform.

Abyste mohli začít, musíte zaregistrovat registraci aplikace. Po nastavení registrace aplikace musí vaše aplikace požádat uživatele, aby udělil konkrétní obor nebo sadu oborů pro přístup k programu Learn jménem uživatele. Learn poskytuje seznam oborů pro jemně odstupňovaný přístup k prostředkům. Seznam oborů zahrnuje:

• : Tento obor umožňuje uživatelům přistupovat k veřejnému obsahu v aplikaci Learn zosobněným jako přihlášený uživatel.

Principy správy verzí rozhraní API platformy Microsoft Learn

Při zásadních změnách rozhraní API vydáváme novou datovanou verzi. Změny, které mohou narušit integraci, jsou známé jako breaking changes. Všechny nepřerušující (přídavné) změny budou dostupné ve všech podporovaných verzích rozhraní API.

Verze rozhraní API je určena jako parametr dotazu api-version a používá yyyy-MM-ddd pro stabilní verze a yy-MM-dd-preview pro verze Preview. K každému požadavku API je vyžadován parametr verze API.

Po vydání nové stabilní verze rozhraní API se předchozí stabilní verze rozhraní API podporuje minimálně 24 měsíců po vydání nové verze rozhraní API. Rozhraní API verze Preview mají kratší cyklus podpory, který trvá tři měsíce po vydání nových rozhraní API ve verzi Preview.

Aktuální verze je 2023-11-01-preview.

Segment adresy URL /v1/ před každým rozhraním API je součástí základní adresy URL, nikoli verze rozhraní API. Je vyhrazeno pro podstatné změny protokolu a vzorů API do budoucna.

Omezení rychlosti rozhraní API platformy Learn

Informace o omezení počtu požadavků rozhraní REST API, které můžete provést v určitém časovém intervalu. Tento limit pomáhá zabránit útokům na zneužití a odepření služby a zajišťuje, že rozhraní API zůstane dostupné pro všechny uživatele.

Learn aplikuje omezení rychlosti na základě oid deklarace v přístupovém tokenu. U přístupu jen pro aplikace se limit použije u samotné aplikace, zatímco pro delegovaný přístup se limit použije pro uživatele přihlášeného k aplikaci.

Ve výchozím nastavení je limit rychlosti 100 volání rozhraní API za minutu vypočítané přes 5minutové okno. Pokud požadujete vyšší limit pro produkci, můžete kontaktovat podporu Learn Integrations, abyste požádali o zvýšení.

Některá rozhraní API, jako je rozhraní API pro vyhledávání znalostí, také implementují omezování rychlosti založené na tokenech. Vychází z počtu spotřebovaných Microsoft Azure tokenů OpenAI s výchozím limitem 10 000 tokenů za minutu. Pokud chcete tento limit zvýšit pro produkční prostředí, obraťte se na podporu integrace Learn.

Stránkování rozhraní API platformy Learn

Všechny prostředky rozhraní API nejvyšší úrovně podporují hromadné načítání prostřednictvím metod API 'list'. Můžete například načíst seznamy modulů nebo zkoušek. Tyto metody vrací stránkované odpovědi po standardizovaném přístupu.

Metody rozhraní API seznamu používají stránkování založené na kurzoru označené polem nextLink v textu odpovědi. Toto pole obsahuje neprůhlenou adresu URL s informacemi potřebnými k načtení další stránky výsledků. Ve výchozím nastavení rozhraní API seznamu vrací 30 položek na požadavek, ale velikost stránky můžete upravit pomocí parametru maxpagesize.

Naše klientské knihovny SDK nabízejí pomocníky pro automatickou stránkování k procházení všemi stránkami seznamu.

Související obsah

• Rychlý start: Nastavení a použití dat katalogu rozhraní API platformy Microsoft Learn
• Referenční příručka pro vývojáře k datovému katalogu rozhraní API platformy
• Nejčastější dotazy k rozhraní API platformy Learn