UseCase: Aufenthalt an einer bestimmten Tour Station via Statusmeldungen berechnen
Um die an einer bestimmten Tour-Station verbrachte Zeit genau zu ermitteln und somit die Abrechnungskosten korrekt zu berechnen, können mithilfe des Job-Moduls Statusmeldungen eines Gerätes abgefragt und entsprechende Touren kreiert werden.
Der Anwendungsfall:
Dieses Beispiel demonstriert die Möglichkeit, über das Job-Modul der GPSoverIP-API eine Tour zu erstellen und anschließend die Statusmeldungen abzufragen, um die verbrachte Zeit an jeder Tour-Station zu berechnen. Dies kann insbesondere bei der Belieferung von Baustellen von großer Bedeutung sein, da hier die exakte Aufenthaltsdauer abgerechnet werden muss.
Eine Tour mittels API erstellen:
Zunächst wird mittels des Job-Moduls und unter Verwendung bestimmter Parameter eine Tour über die API erstellt. .
| Parameter | Möglicher Wert | Erforderlich | Encodierung | Beschreibung |
|---|---|---|---|---|
| module | tour | Ja | --- | --- |
| action | send | Ja | --- | --- |
| mode | manual | Nein | --- | manual = Tour wird im Navigator unter Tourenlisten gespeichert und muss manuell gestartet werden auto = Tour wird ohne Interaktion des Fahrers direkt nach dem Empfangen gestartet |
| user | 120125 | Ja | --- | GPS-Account Nummer |
| pwd | ******** | Ja | MD5 | Passwort MD-5 codiert |
| deviceid | 100201, 100202 | Ja | --- | Gerätenummer |
| uniqueid | A12345 | Nein | --- | Eindeutiger Kennzeichner der Tour (aus Ihrem System) |
| gpxpackage | Schema | Ja | UTF-8 | Packet nach dem definierten Schema - Genaueres in API-Dokumentation |
Wichtiger Hinweis zum GPX-Paket:
Bei der Definition einer einzelnen Tour-Station sollte im Info-Tag die Bezeichnung der Baustelle oder Kostenstelle zur Identifikation angegeben werden. Diese Information wird bei jeder Statusmeldung mit zurückgegeben und kann zur weiteren Auswertung genutzt werden. Alternativ kann die Bezeichnung auch im Label oder im Infotext eingetragen werden. Für das vorliegende Beispiel wird jedoch der Info-Tag verwendet.
Die Anfrage liefert die Job-ID der gerade erstellten Tour zurück. Es ist von Bedeutung, diese ID zu speichern, um später die Statusmeldungen abrufen zu können.
C# Anfrage - Beispiel
Ein Beispiel für eine solche Anfrage in C# könnte wie folgt aussehen. Für die Einfachheit wurde das Error-Handling in allen Beispielen weggelassen
Zum Vergleich: Tourenerstellung GPS-Explorer
Im Vergleich dazu sieht die Tourenerstellung im GPS-Explorer web so aus:
Statusmeldung mittels API abfragen
Zur Abfrage der Job Status wird „getstatus“ des Job-Moduls verwendet. Hierfür werden folgende Parameter benötigt:
| Parameter | Möglicher Wert | Erforderlich | Encodierung | Beschreibung |
|---|---|---|---|---|
| module | job | Ja | --- | --- |
| action | getstatus | Ja | --- | --- |
| mode | all | Nein | --- | all = alle Statusmeldungen zum Job new = nur bisher nicht gelesene debug = Nachrägliches Auslesen der bereits als gelesen markierten Stautsmeldungen |
| user | 120125 | Ja | --- | GPS-Account Nummer |
| pwd | ******** | Ja | MD5 | Passwort MD-5 codiert |
| jobid | 001421 | Ja | --- | Auftragsidentnummer (Der vorher erstellten Tour. Wird bei Tourerstellung als Antwort mit zurückgegeben) |
| format | json | Nein | --- | Gibt das Format an in welchem die Antwort zurückgegeben werden soll json -> Rückgabe in JSON Durch andere Angaben oder nicht erfolgter Eingabe wird die Antwort als GPX zurückgegeben |
Statusmeldung JSON - Beispiel
Die Abfrage liefert Statusmeldungen im JSON-Format zurück, die beispielsweise wie folgt aussehen könnten:
Zum Vergleich: Abgefahrene Tour im GPS-Explorer
Vergleichsweise würde ein solcher Verlauf der abgefahrenen Touren im GPS-Explorer web so aussehen.
C# Abfrage - Beispiel
Wie an der API-Antwort zu sehen ist, enthält das Info-Tag die bei der Erstellung angegebene Kostenstelle, die für die weitere Auswertung extrahiert werden kann. Es ist wichtig, die Statusmeldungen nach den Status „Erledigt“ und „Anfahrt“ zu filtern, da die Geräte auch Statusmeldungen senden können, die für diese Auswertung nicht relevant sind.
Eine korrekte Konfiguration Ihrer Geräte ist ebenfalls von Bedeutung. Wenn Sie beispielsweise möchten, dass die Statusmeldungen automatisch abgegeben werden, wird der Status bei Ankunft in einem konfigurierbaren Bereich als "Anfahrt" gesendet und bei Verlassen dieses Bereiches als "Erledigt".
Wenn Sie bei der Konfiguration Unterstützung benötigen, wenden Sie sich bitte an den GPSoverIP Customer Support.
Sollen Statusmeldungen manuell abgegeben werden, wird "Anfahrt" wahrscheinlich durch den Status "Angekommen" ersetzt.
Ein Beispiel für eine solche Abfrage in C# könnte wie folgt aussehen (siehe Bilder).
Zum parsen der Antwort wurde hier das Newtonsoft.Json Modul verwendet.
Auswertung
Mit den vorliegenden Daten ist die Auswertung nun sehr einfach. Die Statusmeldungen werden nach dem Zeitpunkt der Abgabe sortiert und es muss lediglich die Zeitdifferenz zwischen dem "Angekommen"- und "Erledigt"-Status berechnet werden.
Ein Beispiel für den entsprechenden C#-Code könnte wie folgt aussehen (siehe Bild).
Nach dem gezeigten Beispiel würde hier 00:00:05 als an der Kostenstelle verbrachte Zeit ausgegeben werden.
