Bruksanvisning for apputvikler

Adobe Learning Manager en skybasert, opplæringsfokusert og selvstyrt løsning for læringsadministrasjon. Kundene har programmatisk tilgang til Learning Manager-ressurser med Learning Manager API for å integrere det med andre forretningsapplikasjoner. API-en kan også brukes av Adobe-partnere for å øke verdiløftet til Learning Manager ved å utvide funksjonaliteten eller ved å integrere det med andre programmer og tjenester.

Bruksscenario

Ved å bruke Learning Manager API kan utviklere bygge selvstyrte programmer som utvider funksjonaliteten i Learning Manager eller integrerer Learning Manager med arbeidsflyter i andre forretningsapplikasjoner. Du kan utvikle en webapplikasjon, en skrivebordsklient eller en mobilapp med din ønskede teknologi. Som utvikler har du tilgang til applikasjonsdata fra Learning manager. Distribusjonen av applikasjonen du utvikler, ligger utenfor Learning Manager-plattformen, og du har full kontroll over programvarens utviklingssyklus underveis i utviklingen. Vanligvis utvikles applikasjoner av en kundeorganisasjon for bruk med deres Learning Manager-konto, og disse applikasjonene er private for den bestemte kundeorganisasjonen. Adobe-partnere kan også bygge generiske applikasjoner med Learning Manager API, som kan brukes av et stort antall Learning Manager-kunder.

Learning Manager API

Learning Manager API er basert på REST-prinsipper og eksponerer nøkkelelementer i Learning Manager-objektmodellen til applikasjonsutviklere gjennom HTTP. Utviklere kan, før de kjenner detaljene i API-endepunkter og HTTP-metoder, gjøre seg kjent med de ulike Learning Manager-objektene, deres egenskaper og indre relasjoner. Når man har en forståelse av modellene, er det nyttig å få en grunnleggende forståelse av strukturen i API-forespørsler og -svar, og noen få vanlige programmeringsbegreper som vi bruker generisk på tvers av API-et.

For mer informasjon om ulike API-endepunkter og -metoder kan du se Learning Manager API-dokumentasjon.

API-autentisering

Når du skriver en applikasjon som gjør API-kall til Prime, må du registrere applikasjonen med Integration Admin-appen. 

Learning Manager API bruker OAuth 2.0-rammeverket til autentisering og autorisering av klientprogrammer. 

Fremgangsmåte

1. Konfigurer applikasjonen din

Du kan konfigurere applikasjonen med klient-ID og klienthemmelighet for å bruke de riktige endepunktene. Når du har registrert applikasjonen mottar du clientId og clientSecret. Get-URL må brukes i nettleseren, da den autentiserer Learning Manager-brukere med deres forhåndskonfigurerte kontoer, som SSO, Adobe ID og så videre. 

GET https://captivateprime.adobe.com/oauth/o/authorize?client_id=<Angi din clientID>&redirect_uri=<Angi en url-adresse for videresending&state=<Strengdata>&scope=<et eller flere kommaseparerte omfang>&response_type=CODE.

Etter vellykket autentisering videresendes nettleseren til redirect_uri som er nevnt i URL-adressen over. Parameteret code legges til sammen med omdirigeringsadressen.

2. Få oppdateringstoken fra kode

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

Innhold i post-forespørselen:

3. Motta et tilgangstoken fra gjenoppfriskningstokenet

URL-adresse for å motta tilgangstoken:

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

Innhold i post-forespørselen:

URL-adresse for å bekrefte tokendetaljer

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

URL-adresse for å bekrefte tokendetaljer

En hodeløs LMS-applikasjon henter inn refresh_token ved første pålogging. Deretter brukes refresh_token til å generere et access_token slik at klientapplikasjoner kan gjøre API-anrop. På samme måte bruker avspilling av innhold et oauth-endepunkt til å generere en informasjonskapsler for å håndtere avspillingen, som involverer flere innholdsfiler og api-anrop som initieres av disse filene ved hjelp av informasjonskapselen. Informasjonskapselen som genereres av oauth har samme gyldighet som access_token, som er syv dager. Når informasjonskapselen er generert kan den ikke slettes, i motsetning til vanlig utlogging fra nettapplikasjoner. Oauth-informasjonskapselen og informasjonskapselen for nettapplikasjonen er to ulike informasjonskapsler, og er ikke klar over hverandre.

For å fjerne informasjonskapselen har vi introdusert et nytt endepunkt, som trekker tilbake refresh_token, informasjonskapselen, og både informasjonskapselen og refresh_token.

DETALJER

Bruksgrense

Et tilgangstoken er gyldig i syv dager. Etter en dag må du generere et nytt tilgangstoken ved hjelp av et gjenoppfriskningstoken. Hvis du genererer et ny tilgangstoken fra et gjenoppfriskningstoken mens et eksisterende tilgangstoken fortsatt er gyldig, returneres eksisterende token. 

Noen av de mest brukte begrepene i Learning Manager API forklares under som referanse. 

Inkluderinger

Utviklere har tilgang til en enkelt API-objektmodell, og også flere modeller knyttet til den første modellen. For å få tilgang til påfølgende tilknyttede modeller, må du forstå relasjonen hver modell har med andre modeller. Paremeteret Includes lar utviklere få tilgang til de avhengige modellene. Du kan bruke kommaseparasjon for å få tilgang til flere modeller. For brukseksempler og mer informasjon om includes, kan du se eksempelet på en API-modellseksjon på denne siden.

API-forespørsel

API-forespørsler kan gjøres ved hjelp av en HTTP-forespørsel. Avhengig av endepunkt og metode kan utvikleren muligens velge mellom ulike HTTP-verb som GET, PUT, POST, DELETE, PATCH osv. For noen forespørsler kan det sendes spørringsparametere. Når man gjør en forespørsel for en bestemt datamodell, kan brukeren også be om relaterte modeller som beskrevet i JSON API-spesifikasjonene. Strukturen i en typisk API-forespørsel forklares i eksempel på modellbruk.

API-respons

Når det gjøres en API-forespørsel fra en kunde, hentes et SON-dokument i henhold til JSON API-spesifikasjonen. Responsen inneholder også en HTTP Status-kode, som utvikleren kan bekrefte for å utføre de nødvendige neste trinnene i applikasjonslogikken. Strukturen i en typisk API-respons beskrives i eksempel på modellbruk.

Feil

Når en API-forespørsel feiler, mottas en feilrespons. HTTP Status-koden som returneres i responsen indikerer feiltype. Feilkodene representeres med tall for hver modell i API-referansen. 200, 204, 400 og 404 er noen av de vanlige feilene som vises i API-er for å indikere problemer med HTTP-tilgang.  

Felter

API-objektets egenskaper og dets relasjoner kalles samlet for Fields. Se JSON API for mer informasjon. Du kan bruke Fields som et parameter når du gjør API-kall for å hente én eller flere bestemte egenskaper fra modellen. I mangel av Fields-parameteret vil API-kallet hente alle tilgjengelige egenskaper fra modellen. I følgende API-kall henter for eksempel fields[skill]=name kun name-egenskapen i skill-modellen.

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

Paginering

Noen ganger resulterer en API-forespørsel i en lang liste med objekter som returneres. I slike tilfeller lar egenskapen pagination utvikleren hente resultatene i sekvens over flere sider, der hver side inneholder et intervall med oppføringer. Pagination-egenskapen i Learning Manager lar deg for eksempel angi maksimalt antall oppføringer som skal vises på en side. Du kan også definere områdeverdien for oppføringene som skal vises på siden. 

Sortere

Sortering er tillatt i API-modeller. Velg type sortering som skal brukes på resultatene basert på modellen. Sortering kan brukes i stigende eller synkende rekkefølge. Hvis du for eksempel angir sort=name, vil sorteringen være stigende etter navn. Hvis du angir sort=-name vil sorteringen være synkende etter navn. Se JSON API-spesifikasjonen for mer informasjon.

Illustrasjon av API-bruk

La oss se for oss et scenario der en utvikler ønsker å hente et ferdighetsnavn, maksimalt antall poeng tilordnet ferdighetsnivået og elevens oppnådde poeng for denne ferdigheten.

En userSkill-modell i Learning Manager API-er inneholder id, type, dateAchieved, dateCreated, pointsEarned som standardegenskaper. Når en utvikler bruker GET-metoden for å hente opplysninger om userSkill-modellen, vil gjeldende opplysninger for standardegenskapene vises i responsen. 

I dette scenariet ønsker imidlertid utvikleren å hente ferdighetsnavn og ferdighetspoeng for brukeren. Learning Manager API lar deg hente denne relaterte informasjonen ved bruk av relasjonsfelter og inkluderingsparameteret. De tilknyttede modellene for userSkill hentes med relationships-taggen. Du kan hente opplysninger for hver tilknyttede modell ved å kalle disse modellene sammen med userSkill. For å hente denne informasjonen, kan du bruke include-parameteret med punktumseparerte verdier for hver av de tilknyttede modellene. Du kan bruke komma som separator for å be om en annen modell, som user include=skillLevel.skill,course

API-kall

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

UserId kan for eksempel være 746783 og userSkills id: 746783_4426_1. 

Respons på API-kall

Learning Manager-modeller

Learning Manager API gir utviklere tilgang til Learning Manager-objekter som RESTful-ressurser. Hvert API-endepunkt representerer en ressurs, typisk en objektforekomst som Merke, eller en samling av slike objekter. Utviklere kan så bruke HTTP-verb som PUT, GET, POST og DELETE for å utføre CRUD-operasjoner på disse objektene (samlinger).

Utviklingsprosessen for en applikasjon

Forhåndskrav

Som utvikler må du opprette en prøvekonto i Prime, slik at du har full tilgang til alle roller i kontoen. For å kunne skrive en applikasjon må utvikleren opprette noen brukere og kurs, og sette opp kontoen til en viss stand slik at applikasjonen som utvikles får tilgang til eksempeldata.

Opprett klient-id og hemmelighet

Utvikling og testing av applikasjoner

Learning Manager API kan brukes av utviklere til å bygge alle slags applikasjoner. Utviklere må sikre at kontoene deres inneholder gyldige brukere og kurs. De kan opprette noen testbrukere og -kurs, og simulere aktivitet i prøvekontoen, slik at funksjonaliteten i applikasjonen kan testes.

Applikasjonsdistribusjon

Vi anbefaler at Learning Manager-administratoren eller en integrasjonsadministrator for produksjonskontoen tar eierskap til å gjøre applikasjonen tilgjengelig for brukere i organisasjonen. Når applikasjonen er testet og vurdert klar til distribusjon, må administratoren for produksjonskontoen få beskjed. Ideellt sett vil administratorene generere en ny klient-id og klienthemmelighet for applikasjonen i produksjonskontoen, og utføre nødvendige steg for å inkorporere dem i applikasjonen på en sikker måte. Den faktiske prosedyren for å distribuere applikasjonen varierer fra virksomhet til virksomhet, og Learning Manager-administratoren i organisasjonen din må finne støtte hos IT/IS-avdelingen i organisasjonen for å gjennomføre distribusjonen.

Godkjenning av eksterne applikasjoner

Du kan legge til eksterne applikasjoner ved å klikke på Godkjenn i øverste høyre hjørne av Applikasjoner-siden. Oppgi den eksterne applikasjons-id-en og klikk på Lagre.

Vanlige spørsmål

1. Har Learning Manager e-handelsintegrasjon?

Adobe Learning Manager har ikke e-handelsintegrasjon. Vi tilbyr imidlertid API-er, slik at du kan lage ditt eget hodeløse LMS og implementere e-handelsfunksjoner.