Leitfaden zu den Udemy Business-APIs

Dieser von Udemy erstellte Leitfaden möchte dich bei der Integrationsentwicklung mit Udemy Business-APIs unterstützen. Wenn du diese Tipps und Hinweise umsetzt, sorgst du für ein bestmögliches Lernerlebnis deiner Nutzer. 

Falls bei der Entwicklung Fragen aufkommen, steht dir unser Sales & Solutions Engineering-Team gern unterstützend zur Seite.  Kontaktiere dann einfach deinen Ansprechpartner bei Udemy Business, um einen Gesprächstermin zu vereinbaren. 

Hier geht's zur vollständigen API-Dokumentation von Udemy.

Letzte Aktualisierung dieses Dokuments: 25. Januar 2023.

Screen_Shot_2023-01-27_at_7.57.39_AM.png

Inhalt:

  1. Grundlegende Infos zu APIs
  1. Kurslisten-API
  1. Lernpfad-APIs
  1. Berichts-APIs
  1. Ausblick
  2. Feedback?

    1. Grundlegende Infos zu APIs

Authentifizierung & SSO

Hinweis: Die Authentifizierungs- und Nutzerverwaltung innerhalb von Udemy Business arbeitet unabhängig bzw. separat von deinem LMS/LXP-System (Lernmanagement-System/Learning-Experience-Plattformsystem).  Wenn Nutzer also über ein LMS/LXP-System auf Kurse von Udemy Business zugreifen wollen, können sie diese Kurse nur belegen, wenn sie über eine Udemy Business-Lizenz verfügen.  Udemy Business unterstützt die Nutzerverwaltung über verschiedene Mechanismen: Standard-Nutzername/-Passwort, E-Mail-Domain-Zugriff und SSO (Single Sign-On).

Fehlerbehandlung und Aufrufratenlimits

429-Fehler

  • Bei allen Udemy-APIs bestehen Aufrufratenlimits. Bei einer Überschreitung dieses Limits wird eine 429-Fehlermeldung mit einem Retry-After-Header zurückgegeben. Implementiere deshalb am besten eine Wiederholungsroutine, die dafür sorgt, dass weitere Aufrufe bzw. Anfragen erst nach Ablauf der im Header angegebenen Sekundenzahl gestellt werden. 
  • Hinweis: Die Aufrufratenlimits bei Udemy können sich jederzeit ändern. Die Logik der implementierten Wiederholungsroutine sollte deshalb nicht mit festen Zahlen arbeiten, sondern auf dem Wert in der zurückgegebenen 429-Fehlermeldung basieren.

50X-Fehler

  • Auch für 502/503-Fehler sollten Wiederholungsroutinen implementiert werden. Wenn beim Zugriff auf den Endpunkt der Kursliste 50X-Fehler zurückgegeben werden, kannst du dies ggf. für zukünftige Aufrufe verhindern, indem du den Wert des „page_size“-Parameters verringerst.
  • Außerdem empfehlen wir das Implementieren von nutzerbezogenen Mechanismen zur erneuten Synchronisierung des Kurskatalogs und zur Aktualisierung der Berichtsdaten.

     2. Kurslisten-API 

Funktionsweise

Mit der Kurslisten-API von Udemy Business kannst du alle Kurse und die zugehörigen Metadaten in dein System abrufen,  um dort bequem innerhalb der vorhandenen Drittanbieter-Plattformen (dein LMS-, LXP- oder anderes System) im Udemy Business-Kursangebot suchen und auf die Kurse zugreifen zu können.  Die Kursintegration enthält nicht nur grundlegende Daten wie Titel, Kursbeschreibung, Thumbnail usw., sondern auch einen Kurs-URL-Deep-Link, über den der Nutzer automatisch von deinem LMS/LXP-System zurück auf die Udemy Business-Instanz deines Unternehmens geleitet wird und den entsprechenden Kurs dann in Udemy Business belegen kann. 

Das Einbetten bzw. Nutzen des Udemy Business-Kurses innerhalb des Drittanbieter-Systems ist mit der Integration dagegen nicht möglich.  Dies vermeidet zum einen den Aufwand des zusätzlichen Hostings derselben Inhalte auf anderen Systemen und sorgt zum anderen für ein optimales Lernerlebnis, da die Kurse auf die Nutzung innerhalb der Udemy-Umgebung abgestimmt sind und nur dort der Zugriff auf zusätzliche Funktionen, wie Lern-Tools, Austausch mit den Dozenten u. ä. möglich ist.

Udemy Business unterstützt in der API-Konfiguration außerdem die optionale Einstellung zur automatischen Kurseinschreibung.  Wenn diese für Integrationen empfohlene Einstellung aktiviert ist, werden Nutzer automatisch in den Kurs eingeschrieben, wenn sie im LMS/LXP-System auf einen Kurs-Link klicken. 

Zugriff auf Kurse bei Udemy und bei Drittanbieter-Systemen

Bei einigen LMS/LXP-Systeme ist es möglich einzuschränken, welche Nutzer innerhalb des LMS/LXP-Systems auf welche Kurse zugreifen können.  Abgesehen von nicht öffentlichen unternehmensinternen Kursen und Lernpfaden können alle Udemy Business-Nutzer innerhalb von Udemy Business auf den gesamten öffentlichen Kurskatalog zugreifen und sich in diese Kurse einschreiben. Dies ist für unsere Kunden zwar kein Problem, wir möchten dich aber darauf hinweisen, dass bei diesen Funktionen leichte Unterschiede zwischen deinem LMS/LXP-System und Udemy Business bestehen können.

Häufigkeit von Katalogaktualisierungen

Da wir am Kurskatalog immer wieder Änderungen vornehmen, empfehlen wir, den Katalog täglich zu aktualisieren.  Dies sollte automatisch ablaufen und kein manuelles Eingreifen des Endnutzers erfordern.  Wir empfehlen, die Aktualisierung zu einem Zeitpunkt mit möglichst geringer Nutzung ausführen zu lassen (idealerweise 03:00 Uhr UTC).

Empfohlene Kursdaten

Über die API können große Mengen an Kurs-Metadaten bereitgestellt werden. Wir empfehlen, mindestens die hier angegebenen Datenpunkte zu nutzen, um für ein optimales Nutzererlebnis zu sorgen: 

API-Feld

Empfehlung

title

description

primary_category

primary_subcategory

Nutze diese Felder für den Abgleich mit dem vom Nutzer eingegebenen Suchbegriff.

images[]

Eine Bild-URL, die ein Bild des Kurses für den Nutzer ausgibt

url

mobile_native_deeplink

Deep-Links zum Kurs in der Umgebung des Kunden innerhalb der Web-App bzw. Mobile-App von Udemy

locale

Der Udemy Business-Katalog enthält Kurse in verschiedenen Sprachen, dein System muss diese auf jeden Fall erkennen und filtern können.

estimated_content_length

Wird in Minuten angegeben, optimal zur Anzeige für Nutzer geeignet und kann für Berichterstellung/Gamification für Nutzer verwendet werden

level

Kurslevel (Anfänger, Mittelstufe, Experte) 

 

Effiziente API-Aufrufe

Je nach der Sprachauswahl des Kunden kann der Udemy Business-Katalog 6.000 bis 18.000 Kurse umfassen.  Da eine Seite max. 100 Einträge enthält, werden für den Abruf aller Kurse 60 bis 180 API-Rückgaben benötigt.  Langfristig gesehen zahlt es sich aus, dein System so einzurichten, dass dieser Prozess reibungslos ablaufen kann.  Wenn du hierzu eine persönliche Beratung benötigst, wende dich an den für dich zuständigen Solutions-Techniker bei Udemy.

Seitenlänge

  • Das Limit für „page_size“ beträgt 100 Datensätze.
  • Falls es bei Aufrufen dieser Art zu Verzögerungen oder 502-Fehlern kommt, dann verringere den „page_size“-Wert um die Hälfte und versuche es noch mal.
  • Die Gesamtanzahl von Kursen ist in der Antwort angegeben („count“). 
  • Die Seitenanzahl kannst du aus „count“ und „page_size“ ermitteln, d. h., wenn z. B. „count“ = 1000 und die Seitenlänge „page_size“ = 100 ist, müssen 10 Aufrufe durchgeführt werden.
  • Du kannst die nächste auch Seite abrufen, indem du den nächsten, in der Antwort ausgegebenen Wert verwendest.

Synchrone API-Aufrufe

  • Für ein effizienteres Abrufen des Kurskatalogs empfehlen wir die Verwendung von synchronen Aufrufen.
  • Während des Abrufprozesses für die Kursseiten kann es aus unterschiedlichsten Gründen passieren, dass einzelne Seiten nicht korrekt abgerufen werden.  Dieser Fall sollte unbedingt abgefangen und ein Mechanismus implementiert werden, der für einen erneuten Abruf der fehlerhaften bzw. nicht abgerufenen Seite sorgt. 
  • Hierfür sind synchrone API-Aufrufe und Warteschlagen-Konzepte optimal geeignet, da diese eine geordnete Abfolge von planmäßigen und wiederholten Seitenaufrufen ermöglichen. Bei asynchronen API-Aufrufen kann es zum einen durch zu viele gleichzeitige Aufrufe zur Überlastung der API kommen, zum anderen erschweren sie den Überblick darüber, welche Seiten innerhalb der Abfolge ggf. nicht abgerufen wurden.  Wir empfehlen, den Ablauf so zu implementieren, dass erst nach dem erfolgreichen Abrufen einer Kursseite mit dem Abrufen der nächsten Seite begonnen wird.

Kurskategoriestruktur

Hier findest du die aktuelle Kurskategoriestruktur. Es handelt sich dabei um eine Liste der Kategorien und Unterkategorien, die über die API auf deinem System abgebildet werden können. Hinweis: Diese Struktur ist nicht für alle Sprachen identisch und kann auch im Laufe der Zeit immer wieder verändert werden.

Sprachcodes

Im Folgenden findest du eine Liste der in Udemy Business vorhandenen Sprachen und deren Codes.  In der heruntergeladenen Kursliste von Udemy gibt es für jeden Kurs ein Feld für die Sprache. Die beiden ersten Kleinbuchstaben geben die grundsätzliche Sprache des Kurses an, die beiden anderen Buchstaben geben die Sprachregion an, was beispielsweise für Untertitel o. ä. nützlich ist. Beispielsweise gibt es für Englisch u. a. den Code „en_GB“ für britisches Englisch und „en_US“ für US-amerikanisches Englisch.

Arabisch – ar

Indonesisch – id

Englisch – en

Französisch – fr

Deutsch – de

Hindi – hi

Italienisch – it

Japanisch* – ja

Koreanisch* – ko

Mandarin – zh

Polnisch – pl

Portugiesisch – pt

Russisch – ru

Spanisch – es

Türkisch – tr

Individuelle Kurskataloge 

Der Udemy Business-Kurskatalog wird individuell auf jeden Kunden zugeschnitten und ist dann ausschließlich für diesen Udemy Business-Kunden verfügbar.  Der Katalog jedes Kunden setzt sich aus unterschiedlichen Sprachpaketen, unternehmensinternen Kursen und von udemy.com importierten Kursen zusammen, die über die Kurslisten-API in ihrer Gesamtheit abgerufen werden. Aus diesem Grund muss für jedes Unternehmen, das gegenüber Udemy Business ein eigenständiger Kunde ist, ein separater, individueller Kurskatalog geführt werden.

Neue und zurückgezogene Kurse

  • Der Inhalt des Kurskatalogs kann sich jederzeit verändern, da immer wieder neue Kurse hinzugefügt und veraltete Kurse zurückgezogen werden. 
  • Wenn du den Kurskatalog nutzt, um alle Kurse abzurufen und sie in die interne Datenbank deines Unternehmens zu laden, ist es wichtig, zurückgezogene Kurse, die nicht mehr in der aktuellen Kurslistenausgabe enthalten sind, zu entfernen oder entsprechend zu kennzeichnen.
  • Ein einmal zurückgezogener Kurs ist nicht mehr in der von der Kurslisten-API ausgegebenen Liste enthalten und Nutzer können sich bei Udemy nicht mehr in den Kurs einschreiben.  Wenn ein Kurs aus dem Udemy Business-Kurskatalog zurückgezogen wird, dann behalten alle Nutzer, die zum Zeitpunkt der Zurückziehung in diesen Kurs eingeschrieben sind, ihren Zugriff. Wenn sich ein Nutzer allerdings von einem Kurs abmeldet, der zurückgezogen wurde, kann er ab dann nicht mehr auf diesen Kurs zugreifen. Außerdem können neue Nutzer nicht mehr auf den Kurs zugreifen bzw. sich einschreiben. 

Nicht von der Kurslisten-API abgedeckte Daten

Beachte bitte, dass die API für den Udemy Business-Kurskatalog nicht auf alle Kursdaten Zugriff bietet.  Folgendes ist derzeit nicht verfügbar bzw. möglich:

  • Einbetten bzw. Hosting von Kursen
    • Udemy Business-Content kann nicht außerhalb von Udemy Business eingebettet oder gehostet werden.  Du musst die Nutzer hierfür von deinem LMS/LXP-System zurück zu Udemy Business leiten.
  • Kursbewertungen (Sterne)
    • Diese sind im Kurs-API-Endpunkt nicht enthalten.  Hinweis: Viele LMS/LXP-Systeme bieten ein eigenes Kursbewertungskonzept, das von deinen Nutzern weiterhin unabhängig vom Udemy-Bewertungssystem genutzt werden kann.
  • Kursrezensionen (Kommentare)
  • Daten zu Einschreibungen
  • Such- und Entdeckungsfunktion
    • Udemy Business nutzt ein eigenes Konzept zur Anzeige von Suchergebnissen und Kursempfehlungen, das auf Beliebtheit, Bewertung usw. der Kurse beruht. Dieses Konzept wird nicht an Tools bzw. Systeme von Drittanbietern übertragen.  Udemy Business hat keinen Einfluss darauf, welche Suchergebnisse oder Kursempfehlungen diese Tools bzw. Systeme anbieten.
  • Lernpfade und Udemy Pro-Pfade
    • Diese sind separat und stehen nicht in unmittelbarem Zusammenhang mit den Kursen, weshalb sie auch nicht in die Kurskatalog-Synchronisierung einbezogen werden.  Wir verfügen jedoch über einen separaten Lernpfad-API-Endpunkt, den du für den Import der Udemy Business-Lernpfade und der Udemy Pro-Lernpfade nutzen kannst.
  • Daten auf Lektionsebene
    • Über die APIs von Udemy Business werden vollständige Kurse und Lernpfade übertragen.  Teile von Kursen, wie z. B. einzelne Kursabschnitte, Lektionen, Quizze u. ä., können nicht übertragen werden.
    • Wenn du einzelne Kurskomponenten für die Erstellung von benutzerdefinierten Lernpfaden oder Lernprogrammen benötigst, empfehlen wir, die entsprechenden Lernpfade in Udemy Business zu erstellen und diese anschließend mithilfe unseres Lernpfad-API-Endpunkts in dein LMS/LXP-System zu importieren. 
  • Labs, Wissenstests und Workspaces von Udemy Business Pro
    • Labs, Wissenstests und Workspaces lassen sich nicht in Drittanbieter-Systeme integrieren, sondern müssen direkt in Udemy Business gestartet werden. 
  • Der gleichzeitige Upload mehrerer Kurse auf Udemy per API ist nicht möglich,  da unsere API nur für den Abruf von auf Udemy vorhandenen Kursdaten konzipiert ist.

     3. Lernpfad-APIs

Übersicht

Ähnlich dem Kurslisten-API-Endpunkt für Udemy-Kurse bietet Udemy Business auch einen Lernpfad-API-Endpunkt, der das Suchen und Zugreifen auf deine Udemy Business-Lernpfade von Drittanbieter-Plattformen aus ermöglicht (z. B. bestehendes LMS/LXP- oder anderes System). 

Lernpfade sind eine Zusammenstellung von Kursen, einzelnen Lektionen, individuellen Inhalten und Links, die den Nutzer gezielt durch das Erlernen eines bestimmten Themas oder Fachgebiets leiten.

Die für Lernpfade zurückgegebenen Daten ähneln weitgehend den Daten, die über den Kurslisten-API-Endpunkt abgerufen werden können. Beachte dabei aber bitte, dass Lernpfade ein von Kursen vollständig separates Objekt sind, das auch als solches behandelt werden muss.

Für die wichtigsten Nutzungsszenarien bei der Integration von Udemy Business ist das Entwickeln eines Connectors zur Nutzung der Lernpfad-API zwar keine Grundvoraussetzung, kann aber auf lange Sicht dazu beitragen, den Leistungs- und Funktionsumfang der Integration bestmöglich auszunutzen.

     4. Berichts-APIs

Übersicht

Die Berichts-API von Udemy Business gibt dir eine Übersicht darüber, wie deine Nutzer den Content nutzen.  Du kannst beispielsweise nachvollziehen, wer welche Kurse wie häufig nutzt, welche Nutzer am intensivsten lernen, wer möglicherweise Unterstützung braucht und vieles mehr.  Im Hinblick auf die übergeordneten Weiterbildungs- und Entwicklungsziele können diese Daten und Übersichten eine wertvolle Orientierungshilfe sein.  Es kann hilfreich sein, aus Udemy Business exportierte Berichtsdaten im LMS/LXP-System anzuzeigen, auch können sie so mit anderen Daten oder Berichterstellungsfunktionen anderer externer Systeme kombiniert oder ergänzt werden.

Für das Abrufen von Berichtsdaten von Udemy gibt es zwei Möglichkeiten: xAPI und die REST-Berichts-API. Ausführliche Infos über die Unterschiede zwischen beiden Möglichkeiten findest du unter Vorteile der xAPI. 

Berichts-xAPI

  • Udemy sendet Fortschritts- und Abschlussereignisse nahezu in Echtzeit an den von dir angegebenen Endpunkt. Auf diese Weise ist keine wiederholte Abfrage der Udemy-API erforderlich.
  • Wir empfehlen xAPI, sofern deine Plattform dies unterstützt, da dieser Standard mittlerweile von immer mehr Lernsystemen übernommen wird.
  • Beachte dabei bitte, dass die Berichts-xAPI derzeit nicht so viele Datenelemente wie die RESTful-API umfasst.

Berichts-RESTful-API

Diese API muss regelmäßig aufgerufen werden, hierbei werden die Daten aus dem Endpunkt der Berichts-REST-API in das LMS/LXP-System abgerufen.  Dies läuft nicht in Echtzeit ab, außerdem sind regelmäßige Abrufe erforderlich, um die Datensätze aktuell zu halten.

Empfohlener Endpunkt

Für Fortschritts- und Abschlussdaten: „user-course-activity“. Mithilfe von„from_date“ und „to_date“ können die Ergebnisse auf einen bestimmten Zeitraum eingeschränkt werden.

Aktualisierungshäufigkeit der Berichts-API

  • Alle 4 Stunden
    • Hinweis: Unsere REST-API-Daten werden 3x pro Tag aktualisiert. 
    • Bei einem Intervall von 4 Stunden kann Udemy zukünftig ggf. auch häufigere Aktualisierungen durchführen, ohne dass hierfür Veränderungen an der Integration vorgenommen werden müssen.

Berichtsdaten

Datenelement

Details

course_id

Die eindeutige ID des Kurses 

user_email

Die eindeutige ID des Nutzers 

completion_ratio

Der prozentuale Anteil des Kurses, den ein Nutzer bereits abgeschlossen hat.

Beachte bitte, dass sich dieser Anteil aufgrund von Änderungen am Kurs ändern kann.
Wird z. B. zu einem zu 100 % abgeschlossenen Kurs eine neue Lektion hinzugefügt, sinkt der Anteil auf 80 %.

num_video_consumed_minutes

Optimal geeignet für interne LMS-Kennzahlen, zum Nachvolllziehen von Kursnutzung, insgesamt konsumierten Minuten / Fortbildungseinheiten (Credits).

course_first_completion_date

Gibt an, ob der Nutzer den Kurs bereits zu irgendeinem früheren Zeitpunkt abgeschlossen hatte

course_completion_date

Gibt an, wann der Nutzer den Kurs zuletzt abgeschlossen hat.
Der Wert kann auch NULL sein, wenn sich der Nutzer vom Kurs abgemeldet hat.

user_external_id

Wird als externe ID verwendet, die für den Nutzer eindeutig ist. (Nur, wenn die E-Mail-Adresse keine gültige eindeutige ID darstellt.)

lms_user_id

Wird als externe ID verwendet, die für das LMS eindeutig ist. (Nur, wenn die E-Mail-Adresse keine gültige eindeutige ID darstellt.)

 

Fortschritt und Abschluss

  • Deine Integration sollte sowohl Fortschritts- als auch Abschlussereignisse aufnehmen.
    • Dies sollte für alle genutzten Udemy Business-Kurse der Fall sein, einschließlich zurückgezogener Kurse und Kurse, die nicht von der Plattform deines Unternehmens aus gestartet wurden.

Nicht von der Berichts-API und xAPI abgedeckte Daten

  • Berichte zu Lernpfaden
    • Diese Berichte sind bislang nicht über APIs verfügbar, sondern nur über den direkten Download in der Udemy Web-App.

      5. Ausblick

Wir arbeiten kontinuierlich an der Verbesserung unserer APIs und eingesetzten Technologien. 

  • GraphQL: Es ist eine Aktualisierung der Kurskatalog-APIs geplant, die eine Nutzung der GraphQL-Architektur ermöglicht. Hier findest du Infos zum allgemeinen GraphQL-Konzept. Dies hat mehrere Vorteile, u. a. können Abfragen der Kurskatalog-APIs durchgeführt werden, die nur die bei diesem spezifischen Aufruf benötigten Daten zurückgeben.  Die Veröffentlichung der GraphQL-APIs ist für das 2. Quartal 2023 geplant.  Wenn du denkst, dass dir diese neuen APIs schon jetzt nützlich sein könnten, dann kannst du uns gern per E-Mail an partnerships@udemy.com kontaktieren.

Such-API: Anhand der vielen Suchen, die Nutzer in unserem über 200.000 Kurse umfassenden Katalog durchführen, und der ausgegebenen Kursempfehlungen haben wir umfassendes Wissen zu Such- und Empfehlungsroutinen gesammelt.  Unsere Suchfunktionen können dir hier sicher eine gute Unterstützung sein.  Der Start der Suchfunktionen ist für das 1. Quartal 2023 geplant.  Wenn dir diese Funktion schon jetzt nützlich sein könnte, dann kannst du uns gern per E-Mail an partnerships@udemy.com kontaktieren.

      6. Feedback?

Hast du Feedback zu diesem Dokument oder vermisst du bestimmte Informationen?  Dann würden wir uns freuen, von dir zu hören. Sende dein Feedback bzw. deine Vorschläge bitte an partnerships@udemy.com. Danke im Voraus!

Verwandte Beiträge

Support kontaktieren