Datenextraktions-APIs
Einführung
Dieser Abschnitt erklärt, wie Daten aus der Gear Studio-Plattform mithilfe der HTTP-API extrahiert werden, wie zum Beispiel:
- Benachrichtigungen: Die API ermöglicht die Extraktion der Definition aller in der Plattform erstellten Benachrichtigungen und deren Filterung auf verschiedene Weise.
- Alarme: Die API ermöglicht die Extraktion aller in der Plattform aufgezeichneten Alarme, historisch, und deren Filterung auf verschiedene Weise.
- Endpunkt-Daten: Die API ermöglicht die Extraktion aller mit Endpunkten verbundenen Informationen, historisch, und deren Filterung auf verschiedene Weise.
- Geozonen: Die API ermöglicht die Extraktion der Liste der für jeden Kunden konfigurierten Geozonen, einschließlich der Liste der darin enthaltenen Fahrzeuge.
Erste Schritte
Erstellen eines Zugriffstokens
Wie bei jeder anderen HTTP-Integration ist es erforderlich, ein Zugriffstoken zu erstellen. Diese Seite enthält weitere Informationen zur Verwaltung von Zugriffstokens. Zugriffstokens ermöglichen die Kontrolle des Zugriffs und der Berechtigungen für jede Operation.
Authentifizierung mit einem Zugriffstoken
In allen APIs kann das Zugriffstoken als Teil des Headers gesendet werden, indem ein Authorization-Header verwendet wird, wie unten dargestellt:
Authorization: Bearer {accessToken}Alternativ kann das Zugriffstoken, wenn es nicht möglich ist, das Token über den Authorization-Header zu senden, als Teil der URL über den Parameter "accessToken" gesendet werden, wie im folgenden Beispiel:
https://gear.cloud.studio/api/v2/alarms?accessToken={accessToken}&clientID=4&maxCount=10API-Ausführung
Um die API auszuführen, lesen Sie bitte jeden der folgenden Abschnitte, die die zugehörigen Informationen enthalten:
- Extrahieren von Benachrichtigungen.
- Extrahieren von Alarmen.
- Extrahieren von Endpunkt-Daten.
- Extrahieren von Geozonen-Daten.
Fehler
Wenn ein Aufruf fehlschlägt, antwortet die API mit dem HTTP-Statuscode 500 und einem JSON-Body in diesem Format, unabhängig von der Fehlerursache (ungültiges Token, fehlende Berechtigung oder ungültiger Parameter):
{
"Exception": {
"ClassName": "ServiceException",
"FaultCode": "8001",
"FaultData": "",
"Message": "Beschreibung des Fehlers"
}
}- FaultCode: numerischer Fehlercode. Er bleibt über Versionen hinweg stabil und ist das Feld, anhand dessen eine Integration entscheiden sollte, wie sie reagiert.
- Message: Fehlerbeschreibung für Menschen. Der Wortlaut kann sich ändern und wird übersetzt zurückgegeben, daher sollte sich eine Integration nicht auf den Text verlassen.
- FaultData: zusätzliche Fehlerdaten. Meist leer.
Die häufigsten Codes sind:
| FaultCode | Bedeutung | Was zu tun ist |
|---|---|---|
| 8001 | Das Zugriffstoken fehlt, existiert nicht oder ist abgelaufen | Token prüfen oder ein neues erstellen |
| 8002 | Das Zugriffstoken ist gültig, aber sein Konto ist deaktiviert | Konto reaktivieren oder das Token eines anderen Kontos verwenden |
| 8000 | Das Token darf diese API nicht verwenden | Token mit einem Konto erstellen, das diese Berechtigung hat |
| 8004 | Das Token hat keine Berechtigung für die angeforderte Ressource (Kunde, Facility, Gerät oder Endpoint) | Nur Ressourcen anfordern, auf die das Konto Zugriff hat |
| 100000 | Ein Pflichtwert fehlt | Die Parameter des Aufrufs prüfen |
| 100004 | Ein Parameter hat einen ungültigen Wert oder überschreitet ein Limit | Den in Message genannten Wert prüfen |
| 100001 | Unerwarteter Serverfehler | Später erneut versuchen; wenn der Fehler bleibt, den Support kontaktieren |
Die Fehler 8000, 8001, 8002, 8004, 100000 und 100004 lassen sich nicht durch Wiederholen desselben Aufrufs beheben: Zuerst muss die Anfrage oder das Token korrigiert werden.
Zuletzt aktualisiert am
Anpassung des Berichtsexports
Diese Funktion ermöglicht die Anpassung des Betreffs und des Inhalts der E-Mail, die beim Planen eines Berichts gesendet wird. Zusätzlich können der Name des angehängten Dokuments, die Kopfzeile und die Fußzeile angepasst werden.
Benachrichtigungen
Einführung Dieser Abschnitt erklärt, wie die Definition von Benachrichtigungen, die in der Gear Studio-Plattform erstellt wurden, mithilfe der Datenextraktions-API extrahiert werden. Benachrichtigungen ermöglichen die Definition...