Aloita Microsoft Learn Platform API:n käyttö

Tämä artikkeli auttaa sinua aloittamaan Microsoft Learn Platform API:n käytön. Jos et tunne API:n yksityiskohtia tai käyttötapauksia, suosittelemme lukemaan ensin Microsoft Learn Platform API Overview -artikkelin.

Opi alustan API-todennus

Learn Platform REST API:t käyttävät tunnistautumiseen Microsoft Entra ID. Ennen API-kutsujen tekemistä sinun täytyy valita pääsytapa, ja asiakassovelluksesi täytyy tunnistautua voimassa olevilla tunnuksilla.

Pelkästään sovellusten käyttö

Kun sovelluksesi käyttää suoraan Learnia, sen käyttö ei ole sidottu yhteenkään yksittäiseen käyttäjään. Sovellus kutsuu API-rajapintoja suoraan omalla identiteettillään, tässä tilanteessa käytetään vain sovellusten kautta. Lue lisää Microsoftin identiteettialustasta.

Aloittaaksesi tarvitset voimassa olevan identiteetin Microsoft Identity Platformilla, joka voi olla sovellusrekisteröinti tai hallittu identiteetti. Ihanteellisesti jokaisella kumppanilla tulisi olla oma henkilöllisyys, jotta kiintiöiden ja kumppanien hallinta yksinkertaistuvat. Käyttäjän määrittämän hallitun identiteetin käyttö voi auttaa yhtenäistämään hallittuja identiteettejä eri palveluiden välillä.

Kun Entra ID -identiteettisi on asetettu, hanki Entra ID:ltä pääsytunnus , jonka laajuus on asetettu todennustodistukseksi. Sisällytä pääsytunnus HTTP Authorization -otsikkoon, kun teet REST API -pyyntöjä oppimiseen.

Delegoitu pääsy

Kun käyttäjä kirjautuu sovellukseesi ja käyttää sitä Learn-palveluun, sovelluksen täytyy ensin pyytää lupa käyttää tätä resurssia käyttäjän puolesta. Tätä skenaariota kutsutaan delegoiduksi pääsyksi. Lue lisää Microsoftin identiteettialustasta.

Aloittaaksesi sinun täytyy rekisteröidä sovellusrekisteröinti. Kun sovelluksen rekisteröinti on asetettu, sovelluksesi täytyy pyytää käyttäjää myöntämään tietty scope-alue tai joukko scopeja, jotta Learn-sovellus voi käyttää käyttäjän puolesta. Learn tarjoaa listan laajuuksista tarkkaan rakeiseen resurssien käyttöön. Scope-lista sisältää:

• : Tämä laajuus mahdollistaa käyttäjien pääsyn julkiseen sisältöön Learnissa kirjautuneena käyttäjänä.

Microsoft Learn Platformin API-versioiden ymmärtäminen

Kun API:iin tehdään rikkovia muutoksia, julkaisemme uuden, vanhentuneen version. Rikkovat muutokset ovat muutoksia, jotka voivat mahdollisesti rikkoa integraation. Kaikki ei-rikkomattomat (additiiviset) muutokset ovat saatavilla kaikissa tuetuissa API-versioissa.

API-versio määritellään API-version kyselyparametrina ja käyttää yyyy-MM-dd vakaille versioille ja yyyy-MM-dd-preview esikatseluversioille. API-version kyselyparametri vaaditaan jokaiselle API-pyynnölle.

Kun uusi vakaa API-versio julkaistaan, aiempi vakaa API-versio on tuettu vähintään 24 kuukautta uuden API-version julkaisun jälkeen. Esikatselurajapintojen tukisykli on lyhyempi, kolmen kuukauden lisää uusien esikatselurajapintojen julkaisun jälkeen.

Nykyinen versio on 2023-11-01-preview.

/v1/ URL-segmentti ennen jokaista API:ta on osa perus-URL-osoitetta, ei API-versiota. Se on varattu merkittäville API-protokollien ja mallien muutoksille tulevaisuudessa.

Opi alustan API:n nopeusrajoitus

Learn rajoittaa REST API -pyyntöjen määrää, joita voit tehdä tietyn ajan sisällä. Tämä rajoitus auttaa estämään väärinkäytökset ja palvelunestohyökkäykset sekä varmistaa, että API pysyy kaikkien käyttäjien käytettävissä.

Learn soveltaa nopeusrajoituksia access-tokenin oid-väitteen perusteella. Pelkästään sovelluksen käytössä rajoitus koskee itse sovellusta, kun taas delegoidussa käytössä rajoitus koskee käyttäjää, joka on kirjautunut sovellukseen.

Oletuksena nopeusrajoitus on 100 API-kutsua minuutissa, laskettu viiden minuutin ikkunan aikana. Jos tarvitset korkeampaa tuotantorajaa, voit ottaa yhteyttä Learn Integrations -tukeen pyytääksesi korotusta.

Tietyt API:t, kuten tietohakurajapinta, toteuttavat myös token-pohjaisen nopeusrajoituksen. Tämä perustuu käytettyjen Microsoft Azure OpenAI -tokenien määrään, ja oletusraja on 10 000 tokenia minuutissa. Tämän tuotannon rajan nostamiseksi ota yhteyttä Learn Integrations -tukeen.

Opi alustan API-sivuttamista

Kaikki ylimmän tason API-resurssit tukevat massahakua 'list'-API-menetelmien kautta. Esimerkiksi voit hakea listoja moduuleista tai kokeista. Nämä menetelmät tuottavat sivutettuja vasteita standardoidun lähestymistavan mukaisesti.

Lista API -menetelmät käyttävät kursoripohjaista sivuttamista, joka ilmaistaan vastausrunkossa olevalla nextLink-kentällä. Tämä kenttä sisältää läpinäkymättömän URL-osoitteen, jossa on tarvittavat tiedot seuraavan tulossivun hakemista. Oletuksena listan API:t palauttavat 30 kohdetta per pyyntö, mutta sivun kokoa voi säätää maxpagesize-parametrilla.

Asiakas-SDK-kirjastomme tarjoavat autopaginointiavustajia, joilla voi käydä läpi listan kaikkia sivuja.

Liittyvä sisältö

• Pikakäynnistys: Aseta ja käytä Microsoft Learn Platform API Catalog Data
• Learn Platform API Catalog Data Developer Reference
• Lue Platform API:n UKK