Handbuch für Anwendungsentwickler
NOTEÜbersicht
Adobe Learning Manager ist eine in der Cloud gehostete, auf die Kursteilnehmer zugeschnittene Selfservice-Lösung für Learning Management. Kunden können über die Learning Manager-API programmatisch auf Learning Manager-Ressourcen zugreifen, um sie in andere Unternehmensanwendungen zu integrieren. Die API kann auch von Adobes Partnern verwendet werden, um den Wertbeitrag von Learning Manager zu steigern, entweder durch Erweitern von dessen Funktionsumfang oder durch Integration in gängige Anwendungen oder Dienste.
Anwendungsszenario
Mithilfe der Learning Manager-API können Entwickler eigenständige Anwendungen herstellen, die den Funktionsumfang von Learning Manager erweitern oder Learning Manager in Arbeitsabläufe in anderen Unternehmensanwendungen integrieren. Sie können eine Webanwendung, einen Desktop-Client oder eine mobile App mit einer beliebigen Technologie Ihrer Wahl entwickeln. Als Entwickler können Sie über Learning Manager auf Ihre Anwendungsdaten zugreifen. Die Bereitstellung der von Ihnen entwickelten Anwendung erfolgt außerhalb der Learning Manager-Plattform, und Sie haben die vollständige Kontrolle über den Lebenszyklus der Softwareentwicklung, während die Anwendung weiterentwickelt wird. Anwendungen werden üblicherweise im Unternehmen des Kunden zur Verwendung mit dessen Learning Manager-Konto entwickelt und diese Anwendungen sind „privat“, d. h. nur für dieses Kundenunternehmen verfügbar. Außerdem können Adobe-Partner mit der Learning Manager-API generische Anwendungen erstellen, die von einem breiten Spektrum von Learning Manager-Kunden verwendet werden können.
Learning Manager-API
Die Learning Manager-API basiert auf den Prinzipien von REST und stellt wichtige Elemente des Objektmodells von Learning Manager über HTTP für Anwendungsentwickler bereit. Entwickler können sich mit den verschiedenen Learning Manager-Objekten, ihren Attributen und Beziehungen vertraut machen, bevor sie die Details zu den API-Endpunkten und den HTTP-Methoden kennen. Nachdem ein zuverlässiges Verständnis der Modelle vorhanden ist, empfiehlt es sich, Grundkenntnisse der Struktur von API-Anfragen und -Antworten zu erwerben und einige häufig vorkommende Programmierungsbegriffe zu erlernen, die in der gesamten API unterstützt werden.
Details zu den verschiedenen API-Endpunkten und -Methoden finden Sie in der Dokumentation zur Learning Manager-API.
Teilnehmer-APIs
Adobe Learning Manager - Mit Teilnehmer-APIs können Sie ein benutzerdefiniertes Lernerlebnis für Ihre Benutzer erstellen. Die Verwendung dieser APIs erfordert ein gültiges Benutzertoken und darf nur für Arbeitsabläufe mit einem vollständig lizenzierten/registrierten Teilnehmer verwendet werden.
IMPORTANTDie nicht angemeldeten Nutzungsszenarien erfordern eine besondere Behandlung.
Wenden Sie sich an das Lösungsarchitekturteam, falls Sie Fragen zur geeigneten Verwendung dieser APIs haben, und vergewissern Sie sich, dass ein Lösungsarchitekt eine Lösung vor der Bereitstellung überprüft hat.
API-Authentifizierung
Wenn Sie eine Anwendung entwickeln, die API-Aufrufe an Learning Manager sendet, müssen Sie Ihre Anwendung mithilfe der Integrations-Admin-App registrieren.
Learning Manager-APIs verwenden das OAuth 2.0-Framework zum Authentifizieren und Autorisieren Ihrer Clientanwendungen.
Vorgehensweise
1. Anwendung einrichten
Sie können die Anwendung mit der Client-ID und dem Client-Secret einrichten, um die richtigen Endpunkte zu verwenden. Nachdem Sie die Anwendung registriert haben, können Sie clientId und clientSecret abrufen. Die GET-URL sollte im Browser verwendet werden, da sie zur Authentifizierung der Learning Manager-Benutzer mit ihren vorkonfigurierten Konten wie SSO, Adobe ID usw. genutzt wird.
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.
Nach erfolgreicher Authentifizierung leitet Ihr Browser Sie zu dem in der oben genannten URL angegebenen redirect_uri weiter. Ein Parametercode wird zusammen mit dem Umleitungs-URI angehängt.
2. Aktualisierungstoken aus dem Code abrufen
POST https://learningmanager.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded
Hauptteil der Post-Anforderung:
client_id:
<enter your clientid>
&
client_secret:
<enter your clientsecret>
&
code:
<code from step 1></code>
</enter>
</enter>
3. Abrufen eines Zugriffstokens aus dem Aktualisierungstoken
URL zum Abrufen des Zugriffstokens:
POST https://learningmanager.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded
Hauptteil der Post-Anforderung:
client_id:
<enter your clientid>
&
client_secret:
<enter your clientsecret>
&
refresh_token:
<refresh token>
</refresh>
</enter>
</enter>
URL zum Überprüfen der Details zum Zugriffstoken
GET https://learningmanager.adobe.com/oauth/token/check?access_token=<access_token>
Nutzungsbeschränkung
Ein Zugriffstoken ist sieben Tage lang gültig. Nach einem Tag müssen Sie mithilfe des Aktualisierungstokens ein neues Zugriffstoken erstellen. Wenn Sie ein neues Zugriffstoken aus dem Aktualisierungstoken generieren, während ein vorhandenes Zugriffstoken noch gültig ist, wird das vorhandene Token zurückgegeben.
Als Referenz werden weiter unten einige in der Learning Manager-API häufig verwendete Begriffe erklärt.
Includes
Entwickler können sowohl auf ein einzelnes API-Objektmodell als auch auf mehrere mit diesem Modell verknüpfte Modelle zugreifen. Um auf die nachfolgenden verknüpften Modelle zuzugreifen, müssen Sie die Beziehung jedes Modells zu anderen Modellen kennen. Mit dem Includes-Parameter können Entwickler auf die abhängigen Modelle zugreifen. Sie können mehrere Modelle durch Kommas trennen. Beispiele für die Verwendung und weitere Details zu Includes finden Sie im Abschnitt zum Beispiel-API-Modell auf dieser Seite.
API-Anforderung
Die API-Anfragen können über eine HTTP-Anfrage gestellt werden. Je nach Endpunkt und Methode stehen eventuell verschiedene HTTP-Verben wie GET, PUT, POST, DELETE, PATCH usw. zur Verfügung. Bei manchen Anforderungen können Abfrageparameter übergeben werden. Wenn der Benutzer eine Anforderung für ein bestimmtes Datenmodell sendet, kann er auch verknüpfte Modelle anfordern wie in den Spezifikationen für die JSON-API beschrieben. Die Struktur einer typischen API-Anforderung wird unter Nutzungsbeispiel für Modell beschrieben.
API-Antwort
Bei einer API-Anforderung durch einen Client wird ein JSON-Dokument gemäß der JSON-API-Spezifikation abgerufen. Die Antwort enthält außerdem den HTTP-Statuscode, den der Entwickler überprüfen kann, um die entsprechenden nächsten Schritte in seiner Anwendungslogik auszuführen. Die Struktur einer typischen API-Antwort wird in Beispielmodellverwendung beschrieben.
Fehler
Wenn eine API-Anforderung fehlschlägt, geht eine Fehlerantwort ein. Der in der Antwort zurückgegebene HTTP-Statuscode gibt die Art des Fehlers an. Fehlercodes werden für jedes Modell in der API-Referenz mit Zahlen dargestellt. 200, 204, 400 und 404 sind einige der häufigsten Fehler, die in APIs angezeigt werden und auf HTTP-Zugriffsprobleme hinweisen.
Fields
Die Attribute des API-Objekts und seine Beziehungen werden zusammenfassend als Felder bezeichnet. Weitere Informationen finden Sie unter JSON API. Sie können Felder als Parameter beim Durchführen von API-Aufrufen verwenden, um ein oder mehrere bestimmte Attribute aus dem Modell abzurufen. Wenn der Fields-Parameter fehlt, ruft der API-Aufruf alle verfügbaren Attribute aus dem Modell ab. Im folgenden API-Aufruf ruft fields[skill]=name beispielsweise nur das name-Attribut des Kenntnismodells ab.
https://learningmanager.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name
Paginierung
Manchmal wird in der Antwort auf eine API-Anforderung eine lange Liste von Objekten zurückgegeben. In solchen Fällen ermöglicht das Paginierungsattribut dem Entwickler, die Ergebnisse nacheinander in Form mehrerer Seiten abzurufen, wobei jede Seite einen Bereich von Datensätzen enthält. Sie können beispielsweise mit dem Paginierungsattribut in Learning Manager festlegen, wie viele Datensätze maximal auf einer Seite angezeigt werden können. Außerdem können Sie den Bereichswert von Datensätzen definieren, die auf der Seite angezeigt werden sollen.
Paginierung
Die Sortierung ist in API-Modellen zulässig. Wählen Sie basierend auf dem Modell die Art der Sortierung aus, die auf die Ergebnisse angewendet werden soll. Die Sortierung kann in aufsteigender oder absteigender Reihenfolge angewendet werden. Wenn Sie beispielsweise "code sort=name" angeben, wird aufsteigend nach Namen sortiert. Wenn Sie "code sort=-name" angeben, erfolgt die Sortierung nach dem Namen in absteigender Reihenfolge. Weitere Informationen finden Sie in der JSON-API-Spezifikation.
Abbildung: Verwendung der API
Lassen Sie uns ein Szenario in Betracht ziehen, in dem ein Entwickler den Namen der Kenntnisse, die für die Kenntnisstufe zugewiesenen Höchstpunkte und die vom Teilnehmer für diese Kenntnisse gesammelten Punkte abrufen möchte.
Ein userSkill-Modell in Learning Manager-APIs umfasst standardmäßig die Attribute id, type, dateAchieved, dateCreated und pointsEarned. Wenn ein Entwickler die GET-Methode verwendet, um Details des userSkill-Modells abzurufen, werden die aktuellen Daten für die Standardattribute in der Antwortausgabe angezeigt.
In diesem Szenario möchte der Entwickler jedoch den Kenntnisnamen und die Punkte des Teilnehmers für eine Kenntnisstufe abrufen. In der Learning Manager-API können Sie auf diese verknüpften Informationen über Beziehungsfelder und Include-Parameter zugreifen. Die verknüpften Modelle für userSkill werden im Beziehungs-Tag abgerufen. Sie können die Details aller verknüpften Modelle abrufen, indem Sie diese Modelle zusammen mit userSkill aufrufen. Verwenden Sie zum Abrufen dieser Informationen den code include-Parameter mit durch Punkte (Punkte) getrennten Werten für jedes der zugeordneten Modelle. Sie können Komma als Trennzeichen verwenden, um ein anderes Modell anzufordern, z. B. user include=skillLevel.skill,course
API-Aufruf
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
Beispiel: userId könnte den Wert 746783 annehmen, userSkills id: 746783_4426_1.
Antwort des API-Aufrufs
\{
"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}
}
]
}
Learning Manager-Modelle
Mit der Learning Manager-API können Entwickler auf Learning Manager-Objekte als RESTful-Ressourcen zugreifen. Jeder API-Endpunkt stellt eine Ressource dar, typischerweise eine Instanz eines Objekts, etwa ein Abzeichen, oder eine Gruppe solcher Objekte. Die Entwickler können dann mithilfe von HTTP-Verben wie PUT, GET, POST und DELETE die CRUD-Operationen für diese Objekte bzw. Gruppen durchführen.
Die folgende Grafik zeigt die verschiedenen Elemente des Learning Manager-Objektmodells in V1 API.
In der folgenden Tabelle werden verschiedene Elemente des Lern-Manager V1-Objektmodells beschrieben:
Im Folgenden sind die verschiedenen Elemente des Learning Manager-Klassendiagramms in der V2-API aufgeführt.
badgecataloguseran ``loResource eingekapselten Ressourcen sind in Bezug auf das Lernziel äquivalent, unterscheiden sich jedoch in Bezug auf den Bereitstellungstyp oder das Inhaltsgebietsschema.with für einen einzelnen Benutzer. Er enthält Details wie den Zeitpunkt, zu dem er erreicht wurde, assertionUrl usw.and Arbeitshilfe.module . Ein Kurs besteht aus of weiteren Modulen. In Learning Manager kann ein Modul auf verschiedene gleichwertige Arten bereitgestellt werden. Daher kapselt loResource im Wesentlichen alle diese äquivalenten Ressourcen.user in der Ressource verbrachte Dauer, den vom Benutzer erzielten Fortschritt in Prozent, den Status "Bestanden/Nicht bestanden" und die vom Benutzer in einem zugeordneten Quiz erhaltene Punktzahl.upcoming classroom oder virtuellen Klassenzimmerkursen, bei denen sich der Benutzer anmelden kann.Liste der Objektattribute und -beziehungen
Attribute
dateCreated
gamificationEnabled
-ID
Gebietsschema
loginUrl
logoUrl
name
Subdomain
themeData
timeZoneCode
Beziehungen
contentLocales(localizationMetadata)
gamificationLevels(gamificationLevel)
timeZones(timeZone)
uiLocales(localizationMetadata)
id
imageUrl
name
Status
dateCreated
dateUpdated
Beschreibung
-ID
isDefault
isInternallySearchable
isListable
name
Status
id
Namen
Farbe
name
Punkte
Attribute
authorNames
dateCreated
datePublished
dateUpdated
effectivenessIndex
enrollmentType
-ID
imageUrl
isExternal
isSubLoOrderEnforce
loType
Status
Tags
Beziehungen
authors(user)
enrollment(learningObjectInstanceEnrollment)
instances(learningObjectInstance)
prerequisiteLOs(learningObject)
skills(learningObjectSkill)
subLOs(learningObject)
additionalLOs(learningObject)
additionalResources(resource)
Attribute
completeDeadline
dateCreated
enrollmentCount
-ID
isDefault
seatLimit
Status
Gültigkeit
Beziehungen
badge(badge)
l1FeedbackInfo(feedbackInfo)
learningObject(learningObject)
loResources(learningObjectResource)
localizedMetadata(localizationMetadata)
subLoInstances(learningObjectInstance)
Attribute
dateCompleted
dateEnrolled
dateStarted
hasPassed
-ID
progressPercent
Ergebnis
Status
Beziehungen
learner(user)
learnerBadge(userBadge)
learningObject(learningObject)
loInstance(learningObjectInstance)
loResourceGrades(learningObjectResourceGrade)
Attribute
externalReporting
-ID
loResourceType
resourceType
Version
Beziehungen
learningObject(learningObject)
loInstance(learningObjectInstance)
localizedMetadata(localizationMetadata)
resources(resource)
Attribute
dateCompleted
dateStarted
dateSuccess
Dauer
hasPassed
-ID
progressPercent
Ergebnis
Beziehungen
loResource(learningObjectResource)
Abspann
-ID
Beziehungen
learningObject(learningObject)
skillLevel(skillLevel)
Attribute
id
Grund
Beziehungen
learningObject(learningObject)
authorWunschdauer
completeDeadline
contentStrukturinfoUrl
contentType
contentZipSize
contentZipUrl
dateCreated
dateStart
wantedDuration
downloadUrl
extraData
hasQuiz
hasToc
-ID
instructorNames
isDefault
Gebietsschema
Lage
name
onlyQuiz
reportingInfo
reportingType
seatLimit
Attribute
Beschreibung
-ID
name
Status
Beziehungen
levels(skillLevel)
id
waagerecht
maxCredits
name
Beziehungen
badge(badge)
skill(skill)
Attribute
avatarUrl
Biografie
contentLocale
E-Mail
Felder
-ID
name
pointsEarned
profile
Rollen
Status
timeZoneCode
uiLocale
Beziehungen
account(account)
manager(user)
Attribute
assertionUrl
dateAchieved
-ID
modelType
Beziehungen
badge(badge)
learner(user)
model(learningObject)
Attribute
Bahn
courseType
dateStart
eingeschrieben
-ID
Monat
Quartal
Beziehungen
containerLO(learningObject)
course(learningObject)
actionTaken
Rinne
dateCreated
-ID
Nachricht
modelIds
modelNames
modelTypes
vorlesen
Rolle
Attribute
dateAchieved
dateCreated
-ID
pointsEarned
Beziehungen
learnerBadge(userBadge)
learningObject(learningObject)
skillLevel(skillLevel)
user(user)
Anwendungsentwicklungsprozess
Voraussetzungen
Als Entwickler müssen Sie ein Testkonto bei Learning Manager erstellen, damit Sie vollen Zugriff auf alle Rollen in diesem Konto haben. Um eine Anwendung entwickeln zu können, muss ein Entwickler einige Benutzer und Kurse erstellen und das Konto in einen funktionsfähigen Zustand versetzen, damit Beispieldaten vorhanden sind, auf die die zu entwickelnde Anwendung zugreifen kann.
Client-ID und Secret erstellen
-
Klicken Sie in der Anmeldung Integrations-Admin auf Anwendungen im linken Bereich.
Anwendungen auf Integrations-Admin auswählen
-
Klicken Sie in der rechten oberen Ecke der Seite auf Registrieren, um Ihre Anwendungsdetails zu registrieren. Die Registrierungsseite wird angezeigt.
Anwendung registrieren
Alle Felder auf dieser Seite müssen ausgefüllt werden.
Anwendungsname: Geben Sie den Namen Ihrer Anwendung ein. Es ist nicht zwingend erforderlich, denselben Anwendungsnamen zu verwenden. Es kann sich um einen beliebigen gültigen Namen handeln.
URL: Wenn Sie die genaue URL kennen, auf der die Anwendung gehostet wird, können Sie sie angeben. Wenn Sie sie nicht kennen, können Sie Ihre Firmen-URL angeben. Ein gültiger URL-Name ist in diesem Feld obligatorisch.
Domänen umleiten: Geben Sie den Domänennamen der Anwendung ein, zu der die Learning Manager-Anwendung nach der OAuth-Authentifizierung umleiten soll. Sie können hier mehrere URLs erwähnen, müssen jedoch die gültigen URLs wie
http://google.com,http://yahoo.comusw. verwenden.Beschreibung: Geben Sie die Kurzbeschreibung für Ihre Anwendung ein.
Umfang: Wählen Sie eine der vier verfügbaren Optionen aus, um den Umfang Ihrer Anwendung zu definieren. Die hier von Ihnen gewählte Option bestimmt, wie Ihre Anwendung auf die Learning Manager-API-Endpunkte zugreifen kann. Wenn Sie beispielsweise Lesezugriff für Teilnehmerrolle gewählt haben, ist der Zugriff auf alle Lern-Manager-API-Endpunkte für Teilnehmer für Ihre Anwendung schreibgeschützt.
Nur für dieses Konto?
Ja - Wenn Sie "Ja" auswählen, ist die Anwendung für andere Kontoadministratoren nicht sichtbar.
Nein - Wenn Sie "Nein" auswählen, können auch andere Kontoadministratoren auf diese Anwendung zugreifen, sie müssen jedoch die Anwendungs-ID verwenden, um auf diese Anwendung zuzugreifen. Die Anwendungs-ID wird generiert und im Bearbeitungsmodus der Learning Manager-Anwendung angezeigt.Wenn Sie beim Registrieren der Anwendung den Lese- und Schreibzugriff für die Administratorrolle als Bereich wählen und beim Erstellen der APIs den Lesezugriff für die Administratorrolle wählen, können Sie weiterhin Schreibzugriff für die Anwendung haben, da der Bereich für die Anwendungsregistrierung den Autorisierungsarbeitsablauf ersetzt.
-
Klicken Sie oben rechts auf Registrieren, nachdem Sie die Details auf der Registrierungsseite ausgefüllt haben.
Anwendungsentwicklung und Tests
Mithilfe der Learning Manager-API können Entwickler beliebige Anwendungen erstellen. Entwickler müssen sicherstellen, dass ihre Konten aus einigen gültigen Benutzern und Kursen bestehen. Sie können einige Testbenutzer und -kurse erstellen und Aktivitäten im Testkonto simulieren, um die Funktionsfähigkeit der Anwendung zu prüfen.
Anwendungsbereitstellung
Wir empfehlen, dass der Learning Manager-Administrator oder ein Integrationsadministrator für das Produktionskonto die Verantwortung für die Bereitstellung der Anwendung für die Benutzer im Unternehmen übernimmt. Sobald die Anwendung getestet wurde und als produktionsbereit betrachtet wird, informieren Sie den Administrator bezüglich des Produktionskontos. Im Idealfall entscheiden die Administratoren, im Produktionskonto eine neue Client-ID und ein neues Client-Secret für die Anwendung zu generieren, und führen die nötigen Schritte aus, um sie auf sichere Weise in die Anwendung zu integrieren. In der Praxis ist das Verfahren zum Bereitstellen von Anwendungen in jedem Unternehmen unterschiedlich, und der Learning Manager-Administrator in Ihrem Unternehmen benötigt für die Bereitstellung Unterstützung durch die IT/IS-Abteilung.
Genehmigung externer Anwendungen
Sie können externe Anwendungen hinzufügen, indem Sie auf Genehmigen in der oberen rechten Ecke der Seite Anwendungen klicken. Geben Sie die ID der externen Anwendung an und klicken Sie auf Speichern.
Eine externe Anwendung hinzufügen und genehmigen