Procedure consigliate per l'uso dell'API catalogo di Microsoft Learn
Questo articolo descrive le procedure consigliate per l'uso dell'API del catalogo di Learn.
Informazioni sulle condizioni per il servizio
Anche se l'API del catalogo di Learn è disponibile pubblicamente e gratuita per l'uso, gli utenti sono soggetti alle condizioni per l'utilizzo API Microsoft. Leggere e comprendere le Condizioni per l'utilizzo dell'API prima di usare l'API Del Catalogo di Learn e prima di includere l'output in qualsiasi ambiente di produzione.
Informazioni sulle limitazioni dell'API Learn Catalog
Vedere Limitazioni nell'articolo Panoramica delle funzionalità dell'API del catalogo di Learn.
Informazioni sul modello di contenuto Learn
Per usare in modo efficace la risposta dell'API Learn Catalog, è importante comprendere i tipi di contenuto disponibili in Microsoft Learn e le relative relazioni tra loro. Per ulteriori informazioni, consultare l'articolo del modello di contenuto di Learn.
In particolare
- UID è l'acronimo di Unique ID ed è univoco per ogni oggetto contenuto. Se un UID cambia, anche se il titolo o altri metadati rimangono invariati, il contenuto viene considerato un nuovo oggetto.
- I moduli sono l'oggetto principale all'interno del catalogo di training di Learn. Sono tutti in grado di stare da soli, nel senso che insegnano uno scenario o un concetto end-to-end all'interno di essi e non richiedono moduli prerequisiti. Per alcuni, questo è tutto e non fanno parte di un percorso di apprendimento. Per gli altri utenti, vengono raggruppati in uno o più percorsi di apprendimento che consentono a un utente di creare concetti più avanzati. Un modulo non deve far parte di un percorso di apprendimento o può far parte di uno o più.
- Le unità non vengono scritte come contenuto autonomo. Devono essere svolte in un ordine specifico per il modulo. Per questo motivo, è incluso il collegamento alla pagina dei dettagli del modulo e la prima unità in modo che gli utenti possano iniziare da lì e procedere con il contenuto.
Informazioni sul funzionamento della localizzazione in Learn e sul modo in cui il contenuto localizzato si riflette nell'output dell'API
Microsoft Learn supporta più di 65 impostazioni locali nel sito e gran parte del contenuto viene convertito in queste impostazioni locali. L'obiettivo è rendere disponibile il contenuto in tutte le lingue in cui sono disponibili i prodotti in corso di insegnamento nel contenuto, ma non tutte le esperienze locali hanno contenuto localizzato.
Quando un record delle impostazioni locali non ha disponibile la traduzione associata, il contenuto sul sito e la risposta API ritornano all'inglese come impostazione predefinita. Nell'output dell'API vengono visualizzati i metadati in lingua inglese nelle risposte per altri locali quando si verifica il fallback. Tuttavia, l'URL del contenuto punta ancora alle impostazioni locali, anche se il contenuto principale può eseguire il fallback e il motivo è consentire all'utente di spostarsi ancora nel sito in tali impostazioni locali (che mostra l'intestazione/piè di pagina tradotta e qualsiasi altro collegamento con traduzione disponibile).
Quando gli aggiornamenti vengono pubblicati nel contenuto in lingua inglese, le pipeline di localizzazione funzionano per aggiornare le versioni localizzate il prima possibile, in genere entro pochi giorni dalla modifica originale.
È possibile visualizzare un elenco completo delle impostazioni locali supportate nel piè di pagina del sito di Microsoft Learn (selezionare la lingua visualizzata). È possibile eseguire query su ognuna di queste impostazioni locali con l'API Learn Catalog usando il filtro locale.
I record di completamento del contenuto di training sono indipendenti dalle impostazioni locali, ovvero non si differenziano le versioni localizzate del contenuto come oggetti separati nei record di completamento del training utente. Indipendentemente dalla lingua in cui un utente completa un training, riceve il credito per l'oggetto complessivo e non viene archiviato un riferimento alla lingua in cui è stato completato. Questo completamento indipendente dalle impostazioni locali significa che se si implementa l'API del Catalogo Learn nell'esperienza di apprendimento, è necessario tenerlo in considerazione e, se si caricano gli oggetti di contenuto come oggetti separati, implementare un'equivalenza tra essi in modo che, indipendentemente dalla lingua in cui l'utente completa il training, ottenga il riconoscimento per esso nelle altre lingue e non debba ripeterla.
Informazioni sul funzionamento del controllo delle versioni del contenuto in Learn e sul modo in cui si riflette nell'output dell'API
In particolare, il contenuto viene aggiornato sempre. Gli aggiornamenti disponibili vengono pubblicati due volte al giorno. Possono essere minori, ad esempio modifiche di testo secondarie o importanti, ad esempio revisioni, aggiunte o eliminazioni principali. In generale, il portfolio di contenuti viene gestito come un progetto open source altamente regolamentato con migliaia di collaboratori e, di conseguenza, i cambiamenti avvengono costantemente. Se si usa l'API Learn Catalog nel sistema di produzione, è necessario essere a conoscenza di questo e avere il sistema in grado di gestirlo.
Quando vengono aggiunti nuovi oggetti contenuto, vengono visualizzati come nuovo oggetto (identificato dall'UID) nella risposta. Quando il contenuto viene modificato, si può capire in base al valore last_modified. Quando il contenuto viene eliminato, l'oggetto contenuto viene rimosso dalla risposta. Anche se a volte si verifica un lieve ritardo nell'aggiornamento del contenuto nella risposta dell'API, quando un utente segue l'URL del contenuto, visualizzerà sempre le informazioni più aggiornate. In caso di eliminazioni, l'URL precedente verrà reindirizzato al nuovo contenuto o esperienza o all'opzione migliore successiva.
Al momento non sono presenti riferimenti alle versioni del contenuto oltre la data di last_modified.
Aggiornare regolarmente i dati
Se si usano le informazioni sul catalogo dell'API di Learn Catalog per supportare i processi aziendali o visualizzare i clienti come parte dell'esperienza del sito, assicurarsi di aggiornare il contenuto almeno una volta al giorno.
In particolare, il contenuto viene aggiornato sempre. Gli aggiornamenti disponibili vengono pubblicati due volte al giorno. Possono essere minori, ad esempio modifiche di testo secondarie o importanti, ad esempio revisioni, aggiunte o eliminazioni principali. In generale, il portfolio di contenuti viene gestito come un progetto open source altamente regolamentato con migliaia di collaboratori e, di conseguenza, i cambiamenti avvengono continuamente. Se si usa l'API Learn Catalog nel sistema di produzione, è necessario essere a conoscenza di questo e avere il sistema in grado di gestirlo.
Esaminare le raccomandazioni della documentazione per sviluppatori
La documentazione per sviluppatori dell'API del catalogo learn include un elenco completo dei dati forniti come parte della risposta e consigli su come usare ogni campo per supportare esperienze di apprendimento eccezionali.
Comprendere la logica delle query
Sono disponibili molti filtri da usare per filtrare in modo preliminare la risposta, in modo da ottenere solo ciò che si sta cercando e gestire dimensioni di file più piccole. È possibile visualizzare l'elenco completo dei filtri di query nell'articolo di riferimento Learn Catalog API Developer. In particolare, è necessario formare correttamente la query e, se si usano più parametri di query nella richiesta, la query viene valutata usando l'operatore AND.
Passaggi successivi
Per altre informazioni sul supporto dell'API Learn Catalog, vedere gli articoli seguenti: