REST Report API
Die REST Report API ermöglicht den Zugriff auf etracker Analyse-Daten aus Drittsystemen – wie BI-Lösungen oder dynamischen Excel-Tabellen – heraus. Dabei kann auf alle Daten, die in den Reports in etracker analytics zu sehen sind, zugegriffen werden. Auch die Anbindung an das Looker Studio (ehemals Google Data Studio) basiert auf der REST Report API.
In diesem Tutorial stellen wir dir die Möglichkeiten und Funktionsweise der Webservice API vor, damit du schnell an die Abfragen kommst, die du für deine Weiterverarbeitung brauchst.
Am einfachsten gelangst du zur API-Abfrage, indem du den gewünschten Report auswählst, Kennzahlen, Sortierung usw. anpasst und anschließend oben rechts im Menü auf API-Abfrage klickst.
Die zum Report gehörende API-Abfrage wird angezeigt und lässt sich per Klick kopieren, um sie ins Drittsystem einzufügen.
Zugang
Die REST Report API steht dir in der etracker Analytics Enterprise Edition zu Verfügung. Zur Nutzung benötigst du einen Zugriffs-Token. Diesen kannst du als Administrator/(Haupt-)Benutzer im etracker Account unter Integration → Zugriffs-Token erstellen.
Zum Schutz der Privatsphäre sowie zur Vermeidung einer unberechtigten Nutzung der etracker Web Services API, sollte der Zugriffs-Token in jedem Fall geheim gehalten werden.
Nutzung von Ansichten
In der etracker Applikation ist es möglich, Ansichten auf bestimmten Reports interaktiv zu definieren und zu speichern. Die Daten zu diesen Ansichten können auch über die REST-API aufgerufen werden. In der folgenden Abfrage werden die Daten zur Ansicht mit Id ‚4‘ im Report ‚Geräte‘ aufgerufen
https://ws.etracker.com/api/v6/report/EADeviceType/data?viewid=4| Parameter | Viewid |
|---|---|
| Beschreibung | Es werden nur die Daten zurückgegeben, die zu der angegebenen voreingestellten Ansicht gehören |
| Zulässige Werte | Gültige Ansicht-Ids. Die Ansichten zu einem Report erscheinen in den Report-Informationen, die mit der Abfrage /info abgerufen werden können. |
| Beispiel | 4 oder 32 |
Der Parameter viewid kann auch mit allen anderen Parametern kombiniert werden, um die Rückgabe einzugrenzen.
Fehlermeldungen
Bei fehlerhaften Abfragen werden keine Daten, sondern detaillierte Fehlermeldungen zurückgegeben. Die Fehlermeldungen haben immer das folgende Format:
{
"errorCode":170,
"msg":"Webservice authentication failed [code:170]"
}Die Rückgabe ist ein JSON-Objekt mit zwei Eigenschaften:
- Eine Fehlernummer (
errorCode), die für eventuelle Rückfragen an etracker verwendet werden kann, und - eine Nachricht (
msg), die Hinweise auf die Fehlerursache beinhaltet.
In bestimmten Fällen werden aus technischen Gründen keine Fehlermeldungen, sondern lediglich ein leeres JSON-Array zurückgegeben. Das tritt meistens dann auf, wenn die übergebenen Parameterwerte problematisch sind. In diesen Fällen ist es hilfreich, zunächst die folgenden Fehlerquellen zu überprüfen:
- Sind alle Attribut- bzw. Kennzahl-Ids korrekt geschrieben?
- Ist die Kennzahl-Id für sortColumn korrekt geschrieben?
- Ist der Wert von sortOrder ‚1‘ oder ‚2‘?