REST API

Labvanced bietet eine REST API, mit der Benutzer Daten vom Labvanced-Server abrufen können, nachdem die Teilnehmer die Studie abgeschlossen haben.

Die REST API ist mit einem Token authentifiziert, das Ihnen ermöglicht, all Ihre Daten programmgesteuert herunterzuladen. Die REST API ist hervorragend für Organisationen und akademische Forschungseinrichtungen geeignet, die ihre Datenerfassung zentralisieren und ihre Daten gemäß ihrem Pipeline-Protokoll an dedizierten Orten speichern möchten. Anstatt Daten manuell auszuwählen und lokal zu speichern, ermöglicht dies Organisationen, auf die Daten auf ihren Servern zuzugreifen, was auch für das GDPR-Protokoll wichtig ist.

Die Dokumentation (Swagger UI) der REST-Endpunkte finden Sie hier: https://www.labvanced.com/openapi.html

Wir bieten auch eine OpenAPI-Spezifikation an, die verwendet werden kann, um Client-Code für verschiedene Programmiersprachen automatisch zu generieren (z. B. in Tools wie Postman): https://www.labvanced.com/labvanced-openapi.json

Erstellen des API-Tokens

Dies ist eine gesicherte API, was bedeutet, dass Sie den Zugriff mit einem in Labvanced generierten Token validieren müssen, um auf die Daten zuzugreifen.

Um das Token zu erstellen, melden Sie sich in der Labvanced-App an und gehen Sie zum Tab "Mein Konto", der sich auf der linken Seite des Menüs befindet.

Es gibt einen Abschnitt namens "API-Anmeldeinformationen", und um das Token zu erstellen, klicken Sie einfach auf "Generieren."

Wenn das Token angezeigt wird, doppelklicken Sie auf den Token-Schlüssel, um ihn vollständig hervorzuheben, und drücken dann Ctrl+C, um ihn zu kopieren.

Mit diesem Token können Sie auf die Daten Ihrer Studien und der relevanten Sitzungen zugreifen.

Hinweis: Das Token kann nur vom Studienbesitzer generiert werden, um Zugriff auf die Sitzungsdaten zu gewähren.

Testen Sie es mit unserer API-Dokumentation (Swagger UI)

Die einfachste Möglichkeit, unsere API auszuprobieren, besteht darin, die Funktion "Try it out" in unserer API-Dokumentation (Swagger UI) zu verwenden: https://www.labvanced.com/openapi.html

In der oberen rechten Ecke klicken Sie auf "Autorisieren".

Dies öffnet ein Dialogfeld, in dem Sie aufgefordert werden, das Token im Feld "Wert" einzugeben / einzufügen.

Nachdem Sie das Token eingefügt haben, klicken Sie auf "Autorisieren" und dann auf "Schließen", um das Dialogfeld zu schließen.

Hinweis: Wenn Sie mit der Datenanzeige fertig sind, können Sie sich von dieser Sitzung abmelden, indem Sie auf "Autorisieren" in der oberen rechten Ecke der Website klicken und dann im angezeigten Dialogfeld auf die Schaltfläche "Abmelden" in der unteren linken Ecke klicken.

Testen Sie den Zugriff auf Daten über unsere API-Dokumentation

Sobald Sie angemeldet sind, können Sie diese beiden Bereiche nutzen, um auf Ihre experimentellen Daten zuzugreifen:

• /api/{expId}/download/{recSessionId}: Dieser Abschnitt ermöglicht es Ihnen, die Daten eines einzelnen Teilnehmers abzurufen und herunterzuladen. Wenn die Daten heruntergeladen werden, erfolgt dies im .csv-Dateiformat gemäß der Konfiguration, die Sie in den exportSettings auf der „Dataview & Export“-Seite in der Labvanced-App angegeben haben.
• /api/{expId}/sessions: Ermöglicht es Ihnen, alle Sitzungen für ein bestimmtes Experiment abzurufen, indem Sie die „Experiment-ID“ eingeben.

Daten von ‘/api/{expId}/sessions’

Es ist am besten, mit dem zweiten Endpunkt zu beginnen, um zuerst herauszufinden, welche Aufzeichnungssitzungen (und deren entsprechende rec_session_id) in einem bestimmten Experiment existieren. Klicken Sie auf das zweite blaue Feld mit der Bezeichnung /api/{expId}/sessions und es wird in einer größeren Ansicht geöffnet, und klicken Sie auf die Schaltfläche "Try it out" auf der rechten Seite:

Durch Klicken auf "Try it out" können Sie Zahlen ins Feld "expid" eingeben, um die Experiment-ID anzugeben, für die Sie auf die Sitzungsdaten zugreifen möchten. Sie finden dies in Labvanced auf der Seite "Meine Studien" in der Spalte "ID". Sobald Sie dieses Feld ausgefüllt haben, klicken Sie auf "Ausführen".

Sobald Sie dies getan haben, können Sie nach unten scrollen und die Informationen zu allen Sitzungen in diesem spezifischen Experiment sehen:

Bitte notieren Sie sich eine der rec_session_id aus der Antwortnutzlast, um sie im nächsten Abschnitt zu verwenden, um alle aufgezeichneten Daten dieser Aufzeichnungssitzung herunterzuladen.

Hinweis: Um eine andere „Experiment-ID“ einzugeben, klicken Sie einfach auf die rote Schaltfläche "Abbrechen" auf der rechten Seite, um eine neue „Experiment-ID“ eingeben zu können.

Daten von ‘recSessionId’

Um auf die Daten eines Teilnehmers zuzugreifen und diese herunterzuladen, klicken Sie auf das erste blaue Feld mit der Bezeichnung /api/{expId}/download/{recSessionId} und es wird in einer größeren Ansicht geöffnet, und klicken Sie auf die Schaltfläche "Try it out" auf der rechten Seite:

Durch Klicken auf "Try it out" können Sie Zahlen in die beiden Felder eingeben, die erscheinen, indem Sie die „Experiment-ID“ und die „rec_session_id“ angeben, die Sie herunterladen möchten (siehe vorheriger Abschnitt).

Sobald Sie diese Werte eingegeben haben, klicken Sie einfach auf "Ausführen" und die API wird ausgeführt. Dann scrollen Sie nach unten und Sie sehen eine Option zum 'Herunterladen der Datei.'

Wenn Sie auf "Datei herunterladen" klicken, wird eine .zip heruntergeladen, die zwei .csv-Dateien enthält, nämlich:

• sessions.csv
• trials.csv

Diese Dateien enthalten alle relevanten Daten für die spezifische Sitzung und die zugehörigen Versuchsdatendaten.

Hinweis: Um eine andere Sitzung abzurufen, klicken Sie einfach auf die rote Schaltfläche "Abbrechen" auf der rechten Seite, um eine neue „Experiment-ID“ und eine neue „rec_session_id“ zum Herunterladen eingeben zu können.

Zusammenfassend ermöglichen Ihnen diese Schritte, Daten mit dem API-Token abzurufen, das Sie mit einem eindeutigen und gesicherten Token in Labvanced generiert haben, um experimentelle und Sitzungsdaten anzuzeigen.

Testen Sie es mithilfe von Postman

Dies ist eine zweite Option, um die API auszuprobieren, für diejenigen, die Postman (eine API-Plattform) bereits in ihren täglichen Aktivitäten verwenden. Das Labvanced API-Token funktioniert auch dort.

Geben Sie die URL im oberen Feld ein, basierend auf der Labvanced API-Website.

Wählen Sie dann den Schlüssel aus und fügen Sie das Token unter der Spalte "Wert" ein, wie unten gezeigt:

Auf diese Weise wird der Sitzungsdaten für ein Experiment über Postman zugänglich sein.

Ebenso können Sie denselben Prozess befolgen, um Dateien für einen bestimmten Teilnehmer herunterzuladen.

Wenn Sie dies tun, zeigt die Vorschau seltsame Zeichen an, aber das ist normal, da dieses Kommando zum Abrufen von Dateien dient. Wenn Sie auf "Antworten speichern" und "In eine Datei speichern" klicken, erscheinen die Daten für den jeweiligen Teilnehmer normal.