Wie Sie unsere API verwenden
1
.
Was ist eine API?
Der Begriff API steht für Application Programming Interface (oder Programmierschnittstelle). Es handelt sich um ein Kommunikationsprotokoll, das den Datenaustausch zwischen einem Client und einem Server vereinfachen soll. Die Kommunikation erfolgt in einem strikten Format oder löst eine bestimmte Aktion aus, so dass sie sich gegenseitig perfekt ergänzen.
Ein API-Schlüssel ist eine eindeutige Kennung, die zur Authentifizierung eines Benutzers oder eines Programms, das die API aufruft, verwendet wird.
2
.
Was bedeutet die API für die Nutzer unserer Plattform?
Das bedeutet, dass Sie die API nutzen können, um einfach daten an unsere Plattform zu senden oder von ihr abzurufen.
Senden Sie Ihre eigenen Daten, um sie mit den Daten zu kombinieren die sich bereits auf unserer Plattform befinden. Dies können Daten aus einem ERP- oder CRM-System oder von Sensoren und Messsystemen sein. Sie können auch Daten anfordern zur Verwendung in Ihrer eigenen Anwendungssoftware.
3
.
Wie benutzt man unsere API und den API-Schlüssel?
1. Erstellung eines API-Schlüssels
Da sich die API in einer öffentlichen Beta-Phase befindet, muss der API-Schlüssel per E-Mail unter help@calculus.group angefordert werden. Sie können uns eine E-Mail mit der Betreffzeile "Request API key for Calculus" senden. In der E-Mail teilen Sie uns bitte mit, für welches Unternehmen Sie den API-Schlüssel benötigen und wofür Sie ihn verwenden wollen.
Bitte beachten! Wenn der API-Schlüssel kompromittiert würde, senden Sie uns bitte eine E-Mail an die gleiche Adresse, um den schlüssel zu widerrufen.
2. Verwende die API, um Daten zu erhalten
Mit der API können Sie Daten von allen Assets abrufen, die mit dem Unternehmen verbunden sind und zu dem der API-Schlüssel gehört. Der API-Endpunkt zum Abrufen von Daten lautet "https://api.calculus.group/asset/{key}". Ersetze {key} durch den eindeutigen Bezeichner des Assets. Die Aufrufe werden mit der HTTP-Aktion "GET" durchgeführt.
Parameter
|
epochStart
|
Die beginn der Zeitreihe, für die Sie Daten benötigen. Das verwendete Datums-/Zeitformat ist "Epoch", der UNIX-Zeitcode. Unter https://www.epochconverter.com/ finden Sie Tools zur Konvertierung von und nach Epoch. Wenn Sie diesen Parameter verwenden, sollten Sie ihn immer zusammen mit dem Parameter "epochEnd" verwendet werden. Wenn nicht verwendet, werden standardmäßig die letzten 24 Stunden herangezogen. |
|
epochEnd
|
Das Ende der Zeitreihe, für die Sie Daten benötigen. Das verwendete Datums-/Zeitformat ist "Epoch", der UNIX-Zeitcode. Unter https://www.epochconverter.com/ finden Sie Tools zur Konvertierung von und nach Epoch. Wenn Sie diesen Parameter verwenden, sollten Sie ihn immer zusammen mit dem Parameter "epochEnd" verwendet werden. Wenn nicht verwendet, werden standardmäßig die letzten 24 Stunden herangezogen. |
Headers
In den Kopfzeilen senden Sie den API-Schlüssel an die Calculus-Plattform, um Ihr Gerät zu authentifizieren.
|
CalculusApiKey |
Verwende den API-Schlüssel, den Sie in Schritt 1 erhalten haben, um sich bei der API zu authentifizieren. |
JSON model
Der Kern der Anfrage ist immer im JSON-Format.
3. Verwende die API, um Daten zu veröffentlichen
Der API-Endpunkt für die Übermittlung von Daten an unsere Plattform lautet "https://api.calculus.group/General/PostData". Die Aufrufe erfolgen mit der HTTP-Aktion "POST".
Parameter
|
api-Version
|
Die version der API, die Sie aufrufen möchten. Version 1.0 ist veraltet, Version 2.0 ist derzeit der bevorzugte Weg. Verwenden Sie "api-version=2.0". |
Ein typischer Aufruf wäre ein POST : "https://api.calculus.group/General/PostData?api-version=2.0".
Headers
In den Kopfzeilen senden Sie den API-Schlüssel an die Calculus-Plattform, um Ihr Gerät zu authentifizieren.
|
CalculusApiKey |
Verwende den API-Schlüssel, den Sie in Schritt 1 erhalten haben, um sich bei der API zu authentifizieren. |
4
.
JSON-Modell
Der Kern der Anfrage ist immer im JSON-Format. Die Verwendung von "check-deltas" und "reset-deltas" wird verwendet, wenn Werte überlaufen und auf 0 zurückgesetzt werden können. Wenn Sie die korrekten kumulativen Werte wünschen, kann dies verwendet werden, um sie in unserem backend zu berechnen. Bitte kontaktieren Sie uns für weitere Informationen, wie Sie dies implementieren können unter help@calculus.group.
Die folgenden Werte können eingestellt werden:
|
device |
Name des Geräts des Gateways, dem Sie Daten hinzufügen möchten. Wenn er nicht vorhanden ist, wird das Gateway automatisch hinzugefügt. Verwenden Sie das Präfix zusammen mit dem API-Schlüssel für das von Ihnen gewählte Gerät, und zwar im folgenden Format: "prefix_gateway". |
||||||
|
timestamp |
Sekunden seit Jan. 1, 1970 (epoch). |
||||||
|
check-delta
|
Derzeit nur verfügbar, nachdem ein Messpfad als Delta markiert wurde. Bitte kontaktieren Sie uns für weitere Informationen unter help@calculus.group. |
||||||
|
reset deltas |
Derzeit nur verfügbar, nachdem ein Messpfad als Delta markiert wurde. Bitte kontaktieren Sie uns für weitere Informationen unter help@calculus.group. |
||||||
|
measurements (Messungen) |
Ein array von Messwerten, die Sie hinzufügen möchten. Dies kann einen Wert, einen string-Wert oder beides haben.
|
Beispiel JSON-Körper
{
"device": "prefix_TestDevice",
"check-deltas": true,
"reset-deltas": true,
"timestamp":1573206752,
"measurements:
[
{
"path": "measurement_1",
"value": 1
},
{
"path": "measurement-2",
"stringValue": "OFF"
},
{
"path": "temp|measurement.3",
"value": 9.4,
"stringValue": "BROKEN"
},
{
"path": "temp|measurement.4",
"value": 11.4,
"stringValue": "OVERLOAD"
}
]
}