Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Questo articolo illustra come iniziare a usare l'API della piattaforma Microsoft Learn. Se non si ha familiarità con i dettagli dell'API o dei casi d'uso, è consigliabile consultare prima l'articolo Panoramica dell'API di Microsoft Learn Platform .
Autenticazione API della piattaforma Learn
Le API REST della piattaforma Learn usano l'ID Entra Microsoft per l'autenticazione. Prima di effettuare chiamate API, è necessario scegliere un metodo di accesso e l'applicazione client deve eseguire l'autenticazione con credenziali valide.
Accesso solo tramite app
Quando l'app accede direttamente a Learn, l'accesso non è associato a un singolo utente. L'app utilizza le API direttamente usando la propria identità; questo scenario è l'accesso esclusivamente per app. Altre informazioni su Microsoft Identity Platform.
Per iniziare, è necessaria un'identità valida in Microsoft Identity Platform, che può essere una registrazione dell'app o un'identità gestita. Idealmente, ogni partner deve avere una singola identità per semplificare la gestione delle quote e dei partner. L'uso di un'identità gestita assegnata dall'utente consente di unificare le identità gestite tra servizi diversi.
Dopo aver configurato l'identità dell'ID Entra, ottenere un token di accesso dall'ID Entra con ambito impostato su https://learn.microsoft.com/.default come prova dell'autenticazione. Includere il token di accesso nell'intestazione autorizzazione HTTP quando si effettuano richieste API REST a Learn.
Accesso delegato
Quando un utente accede all'app e lo usa per accedere a Learn, l'app deve prima richiedere l'autorizzazione per accedere a questa risorsa per conto dell'utente. Questo scenario è denominato accesso delegato. Altre informazioni su Microsoft Identity Platform.
Per iniziare, è necessario registrare una registrazione dell'app. Dopo aver configurato la registrazione dell'app, l'app deve chiedere all'utente di concedere un ambito specifico o di un set di ambiti per accedere a Learn per conto dell'utente. Learn fornisce un elenco di ambiti per l'accesso alle risorse con granularità fine. L'elenco di scopi include:
-
https://learn.microsoft.com/PublicContent.Read.All: questo ambito consente agli utenti di accedere al contenuto pubblico su Learn impersonando l'utente connesso.
Informazioni sul controllo delle versioni delle API della piattaforma Microsoft Learn
Quando vengono apportate modifiche di rilievo all'API, viene rilasciata una nuova versione datata. Le modifiche disruptive sono modifiche che possono interrompere un'integrazione. Tutte le modifiche non di rilievo (additive) saranno disponibili in tutte le versioni dell'API supportate.
La versione dell'API viene specificata come parametro di query api-version e usa aaaa-MM-gg per le versioni stabili e aaaa-MM-dd-preview per le versioni di anteprima. Il parametro di query api-version è obbligatorio per ogni richiesta API.
Quando viene rilasciata una nuova versione stabile dell'API, la versione precedente dell'API stabile è supportata per almeno 24 mesi dopo il rilascio della nuova versione dell'API. Le API di anteprima hanno un ciclo di supporto più breve di tre mesi dopo il rilascio delle nuove API di anteprima.
La versione corrente è 2023-11-01-preview.
Il segmento /v1/ nell'URL prima di ogni API fa parte dell'URL di base, non della versione dell'API. È riservata ai cambiamenti sostanziali del protocollo API e del modello in futuro.
Learn Platform Limitazione della velocità dell'API
Learn limita il numero di richieste API REST che è possibile effettuare entro un periodo di tempo specifico. Questo limite consente di prevenire attacchi impropri e Denial of Service e garantisce che l'API rimanga disponibile per tutti gli utenti.
Learn applica limiti di frequenza basati sull'attestazione OID nel token di accesso. Per l'accesso solo app, il limite viene applicato all'app stessa, mentre per l'accesso delegato, il limite viene applicato all'utente che ha eseguito l'accesso all'app.
Per impostazione predefinita, il limite di frequenza è 100 chiamate API al minuto, calcolato in un intervallo di 5 minuti. Se è necessario un limite superiore per la produzione, è possibile contattare il supporto di Learn Integrations per richiedere un aumento.
Alcune API, come l'API di ricerca delle informazioni, implementano anche la limitazione della frequenza basata su token. Si basa sul numero di token OpenAI di Microsoft Azure usati, con un limite predefinito di 10.000 token al minuto. Per aumentare questo limite per la produzione, contattare il supporto di Learn Integrations.
Paginazione dell'API Learn Platform
Tutte le risorse API di primo livello supportano il recupero bulk tramite metodi API 'list'. Ad esempio, è possibile recuperare elenchi di moduli o esami. Questi metodi restituiscono risposte impaginate seguendo un approccio standardizzato.
I metodi api elenco usano la paginazione basata su cursore, indicata dal campo nextLink nel corpo della risposta. Questo campo contiene un URL opaco con le informazioni necessarie per recuperare la pagina successiva dei risultati. Per impostazione predefinita, le API elenco restituiscono 30 elementi per richiesta, ma è possibile modificare le dimensioni della pagina usando il parametro maxpagesize.
Le librerie dell'SDK client offrono strumenti di autopaginazione per percorrere tutte le pagine di un elenco.