A Microsoft Learn Platform API használatának első lépései

Ez a cikk segítséget nyújt a Microsoft Learn Platform API használatának első lépéseiben. Ha nem ismeri az API részleteit vagy a használati eseteket, javasoljuk, hogy először tekintse át a Microsoft Learn Platform API áttekintési cikkét .

Ismerje meg a platform API-hitelesítését

A Learn Platform REST API-k Microsoft Entra ID használnak hitelesítésre. API-hívások indítása előtt ki kell választania egy hozzáférési módszert, és az ügyfélalkalmazásnak érvényes hitelesítő adatokkal kell hitelesítenie magát.

Csak alkalmazáshoz való hozzáférés

Amikor az alkalmazás közvetlenül hozzáfér a Learnhez, a hozzáférése nincs egyetlen felhasználóhoz kötve. Az alkalmazás közvetlenül a saját identitásával hívja meg az API-kat, ez a forgatókönyv csak alkalmazásalapú hozzáférés. További információ a Microsoft identitásplatformról.

Első lépésként érvényes identitásra van szüksége a Microsoft Identity Platformon, amely lehet alkalmazásregisztráció vagy felügyelt identitás. Ideális esetben minden partnernek egyetlen identitással kell rendelkeznie a kvóta és a partnerkezelés egyszerűsítése érdekében. A felhasználó által hozzárendelt felügyelt identitások használata segíthet egyesíteni a felügyelt identitásokat a különböző szolgáltatásokban.

Miután beállította az Entra-azonosító identitását, szerezze be a hozzáférési jogkivonatot az Entra-azonosítóból, amelynek hatóköre hitelesítési igazolásként van beállítva . A hozzáférési jogkivonatot a HTTP-engedélyezés fejlécében kell szerepeltetni, amikor REST API-kéréseket küld a Learnnek.

Delegált hozzáférés

Amikor egy felhasználó bejelentkezik az alkalmazásba, és azt használja a Learn eléréséhez, az alkalmazásnak először engedélyt kell kérnie az erőforrás felhasználó nevében való eléréséhez. Ezt a forgatókönyvet delegált hozzáférésnek nevezzük. További információ a Microsoft identitásplatformról.

Első lépésként regisztrálnia kell egy alkalmazásregisztrációt. Az alkalmazásregisztráció beállítása után az alkalmazásnak meg kell kérnie a felhasználót, hogy adjon meg egy adott hatókört vagy hatókörkészletet a Learn felhasználó nevében való eléréséhez. A Learn a részletes erőforrás-hozzáférés hatóköreinek listáját tartalmazza. A hatókörök listája a következőket tartalmazza:

• : Ez a hatókör lehetővé teszi a felhasználók számára, hogy a learn nyilvános tartalmaihoz bejelentkezett felhasználóként megszemélyesítve férjenek hozzá.

A Microsoft Learn Platform API verziószámozásának ismertetése

Az API kompatibilitástörő módosításakor egy új, dátumozott verziót adunk ki. A kompatibilitástörő változások olyan változások, amelyek esetleg megszakíthatják az integrációt. A nem kompatibilitástörő (additív) módosítások minden támogatott API-verzióban elérhetők lesznek.

Az API-verzió az api-version lekérdezési paraméterként van megadva, és a stabil verziókhoz a yyyy-MM-dd formátumot, az előzetes verziókhoz pedig a yyyy-MM-dd-preview formátumot használja. Az API-verziójú lekérdezési paraméter minden API-kéréshez szükséges.

Új stabil API-verzió kiadásakor az előző stabil API-verzió legalább 24 hónapig támogatott az új API-verzió megjelenése után. Az előzetes verziójú API-k az új előzetes verziójú API-k megjelenésétől számított három hónappal rövidebb támogatási ciklussal rendelkeznek.

A jelenlegi verzió: 2023-11-01-preview.

A /v1/ URL-szegmens minden API előtt nem az API-verzió, hanem az alap URL-cím része. A jövőben jelentős API-protokoll- és mintamódosításokhoz van fenntartva.

A platform API sebességkorlátozásának megismerése

A Learn korlátozza a REST API-kérések számát, amelyeket meghatározott időn belül el tud végezni. Ez a korlát segít megelőzni a visszaéléseket és a szolgáltatásmegtagadási támadásokat, és biztosítja, hogy az API minden felhasználó számára elérhető maradjon.

Ismerje meg, hogy a hozzáférési jogkivonatban található oid jogcím alapján alkalmazza a sebességkorlátokat. Csak az alkalmazáshoz való hozzáférés esetén a korlát az alkalmazásra vonatkozik, delegált hozzáférés esetén a korlát az alkalmazásba bejelentkezett felhasználóra lesz alkalmazva.

Alapértelmezés szerint a sebességkorlát percenként 100 API-hívás, amely egy 5 perces időszakon keresztül van kiszámítva. Ha magasabb termelési korlátra van szüksége, a Növekedés kéréséhez forduljon a Learn integrációs támogatási szolgálatához.

Bizonyos API-k, például a tudáskeresési API is jogkivonatalapú sebességkorlátozást implementálnak. Ez a felhasznált Microsoft Azure OpenAI tokenek számán alapul, amelynek alapértelmezett korlátja percenként 10 000 token. Az éles üzemre vonatkozó korlát növeléséhez lépjen kapcsolatba a Learn integrációs támogatási szolgálatával.

Ismerje meg a Platform API oldalszámozását

Minden legfelső szintű API-erőforrás támogatja a tömeges lekérést a "lista" API-metódusokkal. Lekérheti például a modulok vagy vizsgák listáját. Ezek a metódusok szabványosított megközelítést követve többoldalas válaszokat adnak vissza.

A List API-metódusok kurzoralapú lapozást használnak, amelyet a válasz törzsének nextLink mezője jelez. Ez a mező egy átlátszatlan URL-címet tartalmaz, amely a következő találatoldal beolvasásához szükséges információkat tartalmazza. A lista API-k alapértelmezés szerint kérésenként 30 elemet adnak vissza, de a maxpagesize paraméterrel módosíthatja az oldalméretet.

Az ügyféloldali SDK-kódtárak autopaginációs segédeket kínálnak a lista összes oldalának bejárásához.

Kapcsolódó tartalom

• Rövid útmutató: A Microsoft Learn Platform API-katalógusadatainak beállítása és használata
• Learn Platform API Katalógus Adat Fejlesztői Referencia
• Learn Platform API – gyakori kérdések