Manuale per sviluppatori di applicazioni

Panoramica overview

Adobe Learning Manager è una soluzione di gestione dell’apprendimento self-service ospitata nel cloud e incentrata sugli Allievi. I clienti possono accedere alle risorse di Learning Manager a livello di programmazione utilizzandone l’API per integrarle con altre applicazioni aziendali. Inoltre, l’API può essere utilizzata dai partner di Adobe per migliorare la proposta di valore di Learning Manager, estendendone le funzionalità o integrandola con altri servizi o applicazioni.

Scenario di utilizzo usagescenario

Grazie all’API di Learning Manager, gli sviluppatori possono creare applicazioni autonome che estendono le funzionalità di Learning Manager o che integrino Learning Manager con i flussi di lavoro di altre applicazioni aziendali. Puoi sviluppare un’applicazione Web, un client desktop o un’app per dispositivi mobili utilizzando qualsiasi tecnologia a tua scelta. In qualità di sviluppatore, puoi accedere ai dati delle applicazioni da Learning Manager. La distribuzione dell’applicazione sviluppata è esterna alla piattaforma Learning Manager e avrai il pieno controllo sul ciclo di vita dello sviluppo del software man mano che l’applicazione si evolve. In genere, le applicazioni vengono sviluppate da un’organizzazione cliente per l’utilizzo con il proprio account di Learning Manager e sono quindi private. Inoltre, i partner di Adobe possono creare delle applicazioni generiche con l’API di Learning Manager, utilizzabili da un’ampia gamma di clienti.

API di Learning Manager apidescription

L’API di Learning Manager si basa sui principi di REST ed espone gli elementi chiave del modello a oggetti di Learning Manager agli sviluppatori di applicazioni tramite HTTP. Prima di conoscere i dettagli degli endpoint API e dei metodi HTTP, gli sviluppatori possono acquisire dimestichezza con i vari oggetti di Learning Manager, i relativi attributi e le interrelazioni. Una volta compresi i modelli, sarà utile comprendere la struttura delle richieste e delle risposte API e alcuni termini di programmazione comuni utilizzati genericamente nell’API.

Per informazioni dettagliate sui vari metodi ed endpoint API, consulta la documentazione delle API di Learning Manager.

API Allievo

Adobe Learning Manager: le API degli Allievi consentono di creare un’esperienza di apprendimento personalizzata per gli utenti. L’utilizzo di queste API richiede un token utente valido e deve essere utilizzato solo per lo scopo dei flussi di lavoro in cui è presente un Allievo con licenza o registrazione completa.

I casi d’uso senza registrazione richiedono una gestione speciale.

Rivolgersi al team dell'architettura della soluzione per eventuali domande sull'utilizzo appropriato di queste API e verificare che un architetto della soluzione abbia verificato una soluzione prima di distribuirla.

Autenticazione API apiauthentication

Quando programmi un’applicazione che effettua chiamate API a Learning Manager, devi registrare l’applicazione utilizzando l’app Amministratore dell’integrazione.

Le API di Learning Manager utilizzano il framework OAuth 2.0 per autenticare e autorizzare le applicazioni client.

Procedura

1. Configura applicazione

Puoi configurare l’applicazione con ID client e segreto client per utilizzare gli endpoint corretti. Una volta registrata l’applicazione, puoi ottenere clientId e clientSecret. È necessario utilizzare GET URL nel browser in quanto autentica gli utenti di Learning Manager che usano i loro account preconfigurati, ad esempio SSO, Adobe ID e così via.

GET https://learningmanager.adobe.com/oauth/o/authorize?client_id=<Enter your clientId>&redirect_uri=<Enter a url to redirect to>&state=<Any String data>&scope=<one or more comma separated scopes>&response_type=CODE.

Una volta completata l’autenticazione, il browser reindirizza al redirect_uri indicato nell’URL precedente. Insieme all’URI di reindirizzamento viene aggiunto un codice di parametro.

2. Richiedere un token di aggiornamento dal codice

POST https://learningmanager.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded

Corpo della richiesta post:

client_id:
<enter your clientid>
 &
 client_secret:
 <enter your clientsecret>
  &
  code:
  <code from step 1></code>
 </enter>
</enter>

3. Ottenere un token di accesso dal token di aggiornamento

URL per ottenere il token di accesso:

POST https://learningmanager.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded

Corpo della richiesta post:

client_id:
<enter your clientid>
 &
 client_secret:
 <enter your clientsecret>
  &
  refresh_token:
  <refresh token>

  </refresh>
 </enter>
</enter>

URL per verificare i dettagli del token di accesso

GET https://learningmanager.adobe.com/oauth/token/check?access_token=<access_token>

Limitazione di utilizzo

Un token di accesso è valido per sette giorni. Dopo un giorno, devi generare un nuovo token di accesso utilizzando il token di aggiornamento. Se generi un nuovo token di accesso dal token di aggiornamento mentre un token di accesso esistente è ancora valido, verrà restituito il token esistente.

Alcuni dei termini utilizzati più di frequente nell’API di Learning Manager sono spiegati come riferimento qui di seguito.

Include

Gli sviluppatori possono accedere a un singolo modello a oggetti dell’API e a più modelli associati a tale modello. Per accedere ai modelli correlati successivi, devi comprendere la relazione di ciascun modello con gli altri. Il parametro Include consente agli sviluppatori di accedere ai modelli dipendenti. È possibile utilizzare il separatore di virgole per accedere a più modelli. Per informazioni sull'utilizzo di esempio e ulteriori dettagli su include, consulta la sezione del modello API di esempio in questa pagina.

Richiesta API

Le richieste API possono essere effettuate tramite una richiesta HTTP. A seconda dell’endpoint e del metodo, lo sviluppatore può scegliere tra vari verbi HTTP come GET, PUT, POST, DELETE, PATCH e così via. Per alcune richieste è possibile passare i parametri di query. Quando si effettua una richiesta per un modello di dati specifico, l’utente può anche richiedere modelli correlati come descritto nelle specifiche delle API in JSON. La struttura di una tipica richiesta API è descritta nell’utilizzo del modello di esempio.

Risposta API

Quando una richiesta API viene effettuata da un client, si ottiene un documento SON in base alla specifica dell’API in JSON. La risposta contiene anche il codice di stato HTTP che lo sviluppatore può verificare per eseguire i passaggi successivi appropriati nella logica dell'applicazione. La struttura di una risposta API tipica è descritta in utilizzo modello di esempio.

Errori

Quando una richiesta API ha esito negativo, si ottiene una risposta di errore. Il codice di stato HTTP contenuto nella risposta indica la natura dell’errore. I codici di errore sono rappresentati da dei numeri per ogni modello presente nel riferimento API. 200, 204, 400 e 404 sono alcuni degli errori più comuni rappresentati nelle API che indicano problemi di accesso HTTP.

Fields

Gli attributi dell’oggetto API e le relative relazioni sono chiamati collettivamente Fields. Per ulteriori informazioni, consulta le API in JSON. È possibile utilizzare Fields come parametro durante le chiamate API per recuperare uno o più attributi specifici dal modello. In assenza del parametro Fields, la chiamata API recupera tutti gli attributi disponibili dal modello. Ad esempio, nella seguente chiamata API, fields[skill]=name recupera solo l’attributo name del modello di abilità.

https://learningmanager.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name

Paginazione

A volte, una richiesta API genera un lungo elenco di oggetti da presentare nella risposta. In questi casi, l’attributo di paginazione consente allo sviluppatore di recuperare i risultati in modo sequenziale in termini di più pagine, in cui ogni pagina contiene un intervallo di record. Ad esempio, l’attributo di paginazione in Learning Manager ti consente di impostare il numero massimo di record da visualizzare in una pagina. Inoltre, puoi definire il valore dell’intervallo dei record da visualizzare sulla pagina.

Ordinamento

L’ordinamento è consentito nei modelli API. In base al modello, scegliere il tipo di ordinamento da applicare ai risultati. L'ordinamento può essere applicato in ordine crescente o decrescente. Se, ad esempio, si specifica code sort=name, l'ordinamento sarà crescente per nome. Se si specifica code sort=-name, l'ordinamento è decrescente in base al nome. Per ulteriori informazioni, fai riferimento alla specifica API JSON.

Descrizione dell’uso delle API samplemodel

Consideriamo uno scenario in cui uno sviluppatore desidera ottenere il nome dell’abilità, il numero massimo di punti assegnati per il livello di abilità e i punti guadagnati dall’Allievo per tale abilità.

Un modello userSkill nelle API di Learning Manager è costituito da id, type, dateAchieved, dateCreated e pointsEarned come attributi predefiniti. Pertanto, quando uno sviluppatore utilizza un metodo GET per acquisire i dettagli del modello userSkill, i dati correnti relativi agli attributi predefiniti vengono visualizzati nell’output di risposta.

Tuttavia, in questo scenario lo sviluppatore vuole ottenere il nome dell’abilità e i punti del livello di abilità per l’utente. L’API di Learning Manager ti consente di accedere a queste informazioni correlate utilizzando i campi delle relazioni e di includere i parametri. I modelli associati a userSkill vengono ottenuti nel tag delle relazioni. Puoi ottenere i dettagli di ciascun modello associato chiamando questi modelli insieme a userSkill. Per ottenere queste informazioni, utilizzare il parametro code include con valori separati da punto (punto) per ciascuno dei modelli associati. Puoi usare la virgola come separatore per richiedere un altro modello come user include=skillLevel.skill,course

Chiamata API

https://learningmanagerqe1.adobe.com/primeapi/v1/users/%7buserId%7d/userSkills/%7bid%7d?include=skillLevel.skill&fields%5bskill%5d=name&fields%5bskillLevel%5d=maxCredits&fields%5buserSkill%5d=pointsEarned

Ad esempio, userId può essere 746783 e ID userSkills 746783_4426_1.

Risposta alla chiamata API

\{
 "links": {"self": "https://learningmanager.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1?include=skillLevel.skill&fields[userSkill]=pointsEarned&fields[skillLevel]=maxCredits&fields[skill]=name"},
 "data": {
 "id": "746783_4426_1",
 "type": "userSkill",
 "attributes": {"pointsEarned": 5},
 "links": {"self": "https://learningmanager.adobe.com/primeapi/v2/users/746783/userSkills/746783_4426_1"}
 },
 "included": [
 {
 "id": "4426",
 "type": "skill",
 "attributes": {"name": "Java"},
 "links": {"self": "https://learningmanager.adobe.com/primeapi/v2/skills/4426"}
 },
 {
 "id": "4426_1",
 "type": "skillLevel",
 "attributes": {"maxCredits": 10}
 }
 ]
}

Modelli di Learning Manager models

L’API di Learning Manager consente agli sviluppatori di accedere agli oggetti di Learning Manager come risorse RESTful. Ogni endpoint API rappresenta una risorsa, in genere un’istanza di oggetto come un Badge o una raccolta di tali oggetti. Gli sviluppatori quindi utilizzano i verbi HTTP quali PUT, GET, POST e DELETE per eseguire le operazioni CRUD su tali oggetti (raccolte).

Elenco degli attributi e delle relazioni degli oggetti.

Processo di sviluppo delle applicazioni registration

Prerequisiti prerequisites

Come sviluppatore, devi creare un account di prova su Learning Manager per avere un accesso completo a tutti i ruoli all’interno di tale account. Per poter scrivere un’applicazione, uno sviluppatore deve creare alcuni utenti e corsi e portare l’account a uno stato ragionevole in modo che l’applicazione in fase di sviluppo possa avere accesso ad alcuni dati di esempio.

Creare ID client e segreto client createclientidandsecret

Sviluppo e test delle applicazioni applicationdevelopmentandtesting

L’API di Learning Manager può essere utilizzata dagli sviluppatori per creare qualsiasi applicazione. Gli sviluppatori devono assicurarsi che i propri account siano composti da alcuni utenti e corsi validi. Possono creare alcuni utenti e corsi fittizi e simulare l’attività nell’account di prova per testare la funzionalità dell’applicazione.

Distribuzione delle applicazioni applicationdeployment

È consigliabile che l’Amministratore di Learning Manager, o un Amministratore dell’integrazione per l’account di produzione, renda l’applicazione disponibile agli utenti all’interno della propria organizzazione. Una volta testata l’applicazione, informa l’amministratore dell’account di produzione. Idealmente, gli amministratori desiderano generare un nuovo ID client e un segreto client per l’applicazione nell’account di produzione ed eseguire i passaggi necessari per integrarli nell’applicazione in modo sicuro. La procedura effettiva di distribuzione delle applicazioni varia da azienda ad azienda e l’Amministratore Learning Manager della tua organizzazione deve ricevere il supporto del reparto IT/IS per poterla completare.

Approvazione delle applicazioni esterne externalapplicationapproval

Puoi aggiungere applicazioni esterne facendo clic su Approva nell'angolo superiore destro della pagina Applicazioni. Fornisci l’ID dell’applicazione esterna e fai clic su Salva.

Aggiungere e approvare un'applicazione esterna

Domande frequenti