Procedure consigliate per l'uso dell'API catalogo di Microsoft Learn

Articolo
05/19/2024

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 dell'APIMicrosoft. Leggere e comprendere le condizioni per l'utilizzo delle API prima di usare l'API 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à 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 altre informazioni, vedere l'articolo Sul modello di contenuto di Learn.

Considerevolmente:

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. In alcuni casi si tratta di moduli completi che non fanno parte di alcun percorso di apprendimento. In altri casi i moduli vengono aggregati in uno o più percorsi di apprendimento per consentire a un utente di acquisire concetti più avanzati. Un modulo non deve necessariamente far parte di un percorso di apprendimento oppure può far parte di uno o più percorsi.
Le unità non vengono scritte come contenuto autonomo. Devono essere eseguite in un ordine specifico per il modulo. Per questo motivo viene incluso il collegamento alla pagina dei dettagli del modulo e alla prima unità in modo che gli utenti possano iniziare da tale punto e procedere esplorando tutti i contenuti.

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 è tradotto in queste impostazioni locali. Il nostro obiettivo è rendere disponibile il contenuto in tutte le lingue in cui sono disponibili i prodotti insegnati nel contenuto, ma non tutte le esperienze locali hanno contenuto localizzato disponibile.

Quando un record delle impostazioni locali non ha la traduzione associata disponibile, il contenuto nel sito e la risposta API "esegue il fallback" all'inglese come impostazione predefinita. In caso di fallback, nell'output dell'API vengono visualizzati metadati in lingua inglese in risposte di altre impostazioni locali. L'URL del contenuto, tuttavia, punta comunque alle impostazioni locali, anche se è possibile che si verifichi il fallback del contenuto principale. Questo approccio viene adottato per consentire all'utente di esplorare comunque il sito in tali impostazioni locali, mostrando quindi la traduzione per intestazione/piè di pagina ed eventuali altri collegamenti per cui è disponibile una traduzione.

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 locale filtro.

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 ha completato un corso di formazione, l'utente riceve il credito per l'oggetto complessivo e non viene archiviato alcun riferimento alla lingua in cui è stato completata la formazione. Poiché il completamento è indipendente dalle impostazioni locali, se si implementa l'API Catalogo di Learn nell'esperienza di apprendimento, è necessario tenere presente questo aspetto e, se si caricano oggetti contenuto come oggetti separati, occorre implementare un'equivalenza tra gli oggetti, in modo che l'utente ottenga il credito per il completamento del corso di formazione nelle altre lingue, indipendentemente dalla lingua in cui è stato completato, e non sia obbligato a completare di nuovo il corso di formazione.

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 estremamente regolamentato e altamente regolamentato con migliaia di collaboratori e, di conseguenza, le modifiche stanno accadendo sempre. 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, questi verranno visualizzati come nuovo oggetto (identificato dall'UID) nella risposta. Quando il contenuto viene modificato, è possibile indicare in base al relativo 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 reindirizzerà al nuovo contenuto o alla nuova esperienza oppure all'opzione migliore successiva.

Non sono presenti riferimenti alle versioni del contenuto in questo momento oltre la last_modified data.

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.

Esaminare le raccomandazioni della documentazione per sviluppatori

La documentazione per sviluppatori dell'API Learn Catalog include un elenco completo dei dati forniti come parte della risposta e raccomandazioni su come usare ogni campo per supportare esperienze di apprendimento eccezionali.

Informazioni sulla logica di 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 Informazioni di riferimento per gli sviluppatori dell'APIdel catalogo di Learn. In particolare, è necessario formare correttamente la query e, se si usa più di un parametro 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:

Condividi tramite