Handbuch für Anwendungsentwickler

Übersicht overview

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 usagescenario

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 apidescription

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.

Die 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 apiauthentication

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 samplemodel

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 models

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.

Liste der Objektattribute und -beziehungen

Anwendungsentwicklungsprozess registration

Voraussetzungen prerequisites

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 createclientidandsecret

Anwendungsentwicklung und Tests applicationdevelopmentandtesting

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 applicationdeployment

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 externalapplicationapproval

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

Häufig gestellte Fragen