API-Berechtigungsnachweise – Support-Kundenportal

Erstellen eindeutiger API-Anmeldeinformationen
- API-Token-Name
- API-Token-Berechtigungen
Bearbeiten oder Widerrufen eines API-Tokens
Liste Ihrer API-Anmeldeinformationen
Testen Ihrer API-Anmeldeinformationen mit Postman
Ratenbegrenzung
Spark-API-Dokumentation
Ähnliche Artikel

Spark verfügt über eine umfassende Anwendungsprogrammierschnittstelle (API), die es Systemen von Drittanbietern ermöglicht, die Daten abzufragen und zu bearbeiten. Sicherheit und Vertraulichkeit sind bei der Arbeit mit Systemdaten von größter Bedeutung, und alle Anfragen an die Spark-API müssen authentifiziert werden.

Erstellen eindeutiger API-Anmeldeinformationen

Spark ermöglicht es Ihnen, Ihr eigenes eindeutiges Token zu generieren, das für die Autorisierung Ihres Zugangs zur API verwendet werden kann. Navigieren Sie zunächst zu der Option API-Anmeldeinformationen in den Einstellungen für das LMS.

Wenn dies das erste Mal ist, dass Sie API-Anmeldeinformationen einrichten, sollten Sie eine Schaltfläche mit dem Titel"Neue API-Anmeldeinformationen erstellen" sehen.

Hier können Sie Ihr neues API-Token erstellen und diesem Token die erforderlichen Berechtigungen zuweisen. z.B. Benötigen Sie Ihr Token, um vollen Zugang zu allen Organisationseinheiten im LMS zu erhalten, oder benötigen Sie nur Zugang zu bestimmten Einheiten?

API-Token-Name

Geben Sie Ihren API-Anmeldeinformationen im Feld Konto einen Namen. Dies kann der Name eines Kunden oder eines Projekts sein.

Hinweis: Es kann eine Reihe verschiedener API-Tokens mit eindeutig zugewiesenen Berechtigungen erstellt werden. Daher ist es wichtig, jedem Token einen Namen zu geben, der seine Verwendung klar und genau angibt.

API-Token-Berechtigungen

Sie können mit den folgenden Optionen entscheiden, welche Art von Berechtigungen Sie mit Ihrem API-Token verknüpfen möchten:

Zugriff auf - Sie können wählen, ob Sie Ihren Berechtigungsnachweisen Zugriff auf die LMS-Daten aller Organisationseinheiten oder nur auf die Daten bestimmter Einheiten innerhalb der Organisationsstruktur geben möchten.

Wenn Sie Ihre API-Zugangsdaten nur für eine bestimmte Organisationseinheit benötigen, wählen Sie Data belonging to specific organizational units... im Dropdown-Menü, um ein Pop-up-Fenster aufzurufen, in dem Sie durch die Organisationsstruktur bis zur Ebene Ihrer Wahl navigieren und mit Hilfe der Kontrollkästchen Ihre Auswahl treffen können. Markieren Sie das Kästchen der Einheit(en), auf die Sie Zugriff wünschen, und wählen Sie dann Fertig.

Außerdem gibt es vier weitere Arten von Berechtigungen, die aktiviert werden können, um den Zugriff auf Ihre Anmeldedaten anzupassen:

Verteilung - Ermöglicht Ihnen die Verteilung von Kursen an Spark-Benutzer.

Schulungselemente - Sie können wählen, ob Sie die Möglichkeit haben möchten, den Inhalt von Dokumenten und Modulen über die API zu pflegen, z. B. diese Elemente hinzuzufügen oder zu ändern.

Benutzer - Ermöglicht Ihnen den Zugang zur Verwaltung verschiedener Benutzerebenen über die API. Sie sollten diese Berechtigungen hinzufügen, wenn Sie beabsichtigen, Benutzer hinzuzufügen oder ihren Benutzertyp zu aktualisieren.

Erweitert - Fügen Sie diese Berechtigungen hinzu, wenn Sie Ihre Unternehmensstruktur oder die Definitionen von Arbeitsplatzrollen beibehalten wollen. Diese Berechtigungen sind unerlässlich, wenn Sie die Unternehmensstruktur anpassen oder Ihre Rollendefinitionsliste über die API hinzufügen/bearbeiten möchten.

Hinweis: Sicherheit ist von größter Bedeutung, wenn eine API zur Abfrage von Daten verwendet wird. Indem Sie sicherstellen, dass Ihre Token-Berechtigungen so spezifisch wie möglich auf Ihre Anforderungen zugeschnitten sind, stellen Sie sicher, dass der Zugang zur API nicht weiter als nötig geöffnet wird.

Bearbeiten oder Widerrufen eines API-Tokens

Wenn Sie einen Namen und die erforderlichen Berechtigungen zugewiesen haben, wählen Sie"API-Zugangsdaten erstellen" und Sie werden zu einer Seite weitergeleitet, auf der Ihr Token auf der Registerkarte " Sicherheits-Token" angezeigt wird. Auf der Registerkarte " Bearbeiten " können Sie den Namen und die ursprünglich zugewiesenen Berechtigungen anpassen.

Wenn Sie ein Token löschen möchten, das nicht mehr verwendet wird, wählen Sie die Schaltfläche"Token widerrufen...".

Hinweis: Dadurch wird der Zugriff auf das Token PERMANENT entzogen und kann nicht rückgängig gemacht werden.

Liste Ihrer API-Anmeldeinformationen

Wenn Sie im System eine Ebene zurückgehen, sollten Sie nun sehen, dass eine Liste mit API-Anmeldeinformationen erstellt wurde und dass Ihr neues Token vorhanden ist. Jeder Eintrag in dieser Liste zeigt Ihren Token-Namen, die teilweise verborgene Token-Kennung und den Zugriff der Organisationseinheit, die Ihrem Token derzeit zugewiesen ist.

Hinweis: Durch den Widerruf eines Tokens werden Ihre API-Anmeldedaten nicht vollständig aus dieser Liste entfernt. Es wird nur das Ihrem Berechtigungselement zugewiesene Token und alle mit diesem Token verbundenen API-Zugriffe entfernt.

Testen Ihrer API-Anmeldeinformationen mit Postman

An dieser Stelle wird empfohlen, dass Sie Ihre neu generierten Anmeldeinformationen testen, um sicherzustellen, dass Sie auf die Spark-API zugreifen können, indem Sie eine einfache Anfrage senden, um einige Daten mit einer GET-Anfrage zu erhalten.

Postman ist eine kostenlose Plattform für die API-Zusammenarbeit, die es Ihnen ermöglicht, Anfragen an einen Endpunkt Ihrer Wahl einzurichten und dabei Ihr API-Token zur Autorisierung zu verwenden.

Hinweis: Sie können die Postman-Desktop-Anwendung herunterladen und mehr darüber erfahren, indem Sie den Link im Abschnitt " Verwandte Artikel" am Ende dieser Seite aufrufen.

Erstellen einer neuen Sammlung und Anforderung

Wählen Sie in Ihrem Postman-Arbeitsbereich"Neue Sammlung" und geben Sie Ihrer Sammlung einen Titel, der sich auf Ihre Testaktivität bezieht, z. B. "Spark API". Klicken Sie mit der rechten Maustaste auf Ihre Sammlung in der Sammlungsliste und wählen Sie"Anfrage hinzufügen".

Sie können Ihrer Anfrage einen Namen geben, der widerspiegelt, was Sie abfragen wollen, und dann eine optionale Beschreibung hinzufügen.

Hinweis: Wenn die API über unterstützende Dokumentation verfügt, empfiehlt es sich, auf den Bereich in dieser Ressource zu verweisen, der sich auf den Endpunkt bezieht, auf den Sie zugreifen möchten. Verwenden Sie eckige Klammern, um zu kennzeichnen, wohin der Link führt, und Klammern, um die URL anzugeben.

Sie können diesen Antrag auch einer Sammlung oder einem Ordner innerhalb einer Sammlung zuordnen. Wählen Sie dann"Speichern in *Ihre Sammlung/Ordnername*".

Zuweisung Ihres API-Tokens

Postman ermöglicht es Ihnen, eine Autorisierungsmethode auf der Ebene einer Sammlung oder einer Anfrage hinzuzufügen. Wenn Sie also ein einzelnes API-Token haben, das Sie zur Autorisierung einer Reihe verschiedener Anfragen verwenden möchten, können Sie es einer Autorisierungsmethode auf Sammlungsebene zuweisen, und die Autorisierung wird kaskadenartig auf alle Anfragen innerhalb dieser Sammlung angewendet.

Klicken Sie mit der rechten Maustaste auf Ihre Sammlung in der Liste " Sammlungen " und wählen Sie"Bearbeiten". Klicken Sie im Einstellungseditor auf die Registerkarte"Autorisierung" und wählen Sie"API-Schlüssel" aus dem Dropdown-Menü TYP.

Geben Sie Ihrem Schlüssel einen Namen und fügen Sie das API-Token, das Ihnen auf Spark zugewiesen wurde, in das Feld Wert ein. Dieser Wert sollte wie folgt dargestellt werden:"token *********************************", wobei die mit einem Sternchen versehene Zeile durch das von Ihnen generierte Token ersetzt wird.

Abschließend fügen wir diese Autorisierungsdetails als neuen Parameter in die Kopfzeile der Anfrage ein und wählen"Aktualisieren", um Ihre Autorisierungsmethode zu speichern.

Hinweis: Es ist eine gute Praxis, Ihr API-Token immer so sicher wie möglich zu halten. Sie können Ihr API-Token einer Variablen auf der Registerkarte"Variablen" zuweisen und auf den Variablennamen verweisen, anstatt Ihre API-Anmeldedaten explizit anzuzeigen.

Abfrage des API-Endpunkts

Vergewissern Sie sich, dass die Anfragemethode in der Dropdown-Liste "Methode" auf GET eingestellt ist, und geben Sie die URL des Endpunkts, den Sie abfragen möchten, oben in Ihrem Arbeitsbereich ein.

Wählen Sie dann die Registerkarte"Autorisierung" unter dem Eingabefeld für die URL und stellen Sie sicher, dass TYPE auf"Autorisierung von übergeordneter Stelle erben" eingestellt ist. Dies bedeutet, dass Ihr API-Schlüssel dem Authentifizierungs-Header Ihrer Anfrage hinzugefügt wird.

Klicken Sie nun auf die Schaltfläche"Senden" rechts neben dem Eingabefeld für die URL und Postman wird Ihre Anfrage bearbeiten.

Wenn Ihre Anfrage erfolgreich war, sollten Sie einen 200 OK Status und einige Daten als Body-Inhalt am unteren Rand Ihres Postman-Arbeitsbereichs sehen. Dabei handelt es sich um die vom abgefragten API-Endpunkt angeforderten Daten, die im JSON-Format (JavaScript Object Notation) dargestellt werden.

Hinweis: Wenn Sie den Status 401 UNAUTHORIZED erhalten, bedeutet dies, dass Ihre Autorisierung nicht korrekt eingerichtet wurde. Sie können die folgenden Schritte zur Fehlerbehebung durchführen:

Vergewissern Sie sich, dass Sie Ihr API-Token aus dem Spark LMS korrekt eingegeben haben;
Vergewissern Sie sich, dass der Autorisierungstyp auf API-Schlüssel eingestellt ist und dass dieser Parameter in den Einstellungen für die Sammlungsautorisierung zu Ihrem Anfrage-Header hinzugefügt wird;
Vergewissern Sie sich, dass der Autorisierungskopf aus den Einstellungen Ihrer Sammlung übernommen wird.

Ratenbegrenzung

Die Spark-API drosselt eine große Anzahl von Anfragen innerhalb eines kurzen Zeitraums, um das System vor Überlastung oder Missbrauch zu schützen. Dies führt zu einer 429 TOO MANY REQUESTS Status-Antwort, die einen Retry-After-Header enthält, der angibt, wie lange in Sekunden, bevor eine neue Anfrage von der API akzeptiert wird.

Spark-API-Dokumentation

Die Spark-API wurde ausführlich dokumentiert. Sie können auf diese Ressource zugreifen, indem Sie oben auf der Seite mit den API-Anmeldeinformationen"API-Dokumentation" auswählen.

Diese Dokumentation enthält detaillierte Informationen zur Verwendung der API für Abfragen an Spark, einschließlich einer vollständigen Liste der verfügbaren Endpunkte, der Verwendung Ihres API-Tokens zur Zuweisung der richtigen Berechtigung für Ihre Anfragen, der von der API akzeptierten REST-Methoden und der unterstützten Datenformate.