Benutzer-Werkzeuge

Webseiten-Werkzeuge


development:api:reference

Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen RevisionVorhergehende Überarbeitung
Nächste Überarbeitung
Vorhergehende Überarbeitung
development:api:reference [2015/11/12 13:06] – [Daten-Kontext] jaudevelopment:api:reference [2019/04/13 09:06] (aktuell) – URLs aktualisiert justinotherguy
Zeile 12: Zeile 12:
 Die URL besteht im Allgemeinen aus mehreren Komponenten: Die URL besteht im Allgemeinen aus mehreren Komponenten:
  
-<code>http://<server:port><einstiegspfad>/middleware.php/<kontext>[/<uuid>].<format>[?<parameter>]</code>+<code>http://<server:port><einstiegspfad>/middleware/<kontext>[/<uuid>].<format>[?<parameter>]</code>
  
 ^Platzhalter^Beispiele^Mögliche Werte^Beschreibung^optional^ ^Platzhalter^Beispiele^Mögliche Werte^Beschreibung^optional^
Zeile 18: Zeile 18:
 |<einstiegspfad>|/demo\\ /|vollständiger Pfad zu den volkszaehler.org Skripten\\ Wird benötigt, wenn kein eigener Virtual-Host zur Verfügung steht||ja| |<einstiegspfad>|/demo\\ /|vollständiger Pfad zu den volkszaehler.org Skripten\\ Wird benötigt, wenn kein eigener Virtual-Host zur Verfügung steht||ja|
 |<kontext>|channel|channel, group, capabilities, data|[[#Kontexte|Kontext]] der Anfrage|nein| |<kontext>|channel|channel, group, capabilities, data|[[#Kontexte|Kontext]] der Anfrage|nein|
-|<identifier>|550e8400-e29b-11d4-a716-446655441352\\ 41352|[string] oder [uuid]|Referenziert eindeutig eine Gruppe von Kanälen oder einen einzigen Kanal|ja|+|<identifier>|57acbef0-88a9-11e4-934f-6b0f9ecd95a8|[string] oder [uuid]|Referenziert eindeutig eine Gruppe von Kanälen oder einen einzigen Kanal|ja|
 |<format>|json|siehe [[#Antwort]]|das Format der [[#Antwort]]|nein| |<format>|json|siehe [[#Antwort]]|das Format der [[#Antwort]]|nein|
-|<parameter>|from=01-01-2010&to=01-02-2010\\ from=1234567890000&groupBy=500| | |ja|+|<parameter>|from=01-01-2010&to=01-02-2010\\ from=1234567890000&group=500| | |ja|
  
 Beispiel um die Auflösung eines Stromzählers in volkszähler-Datenbank nachträglich zu ändern: Beispiel um die Auflösung eines Stromzählers in volkszähler-Datenbank nachträglich zu ändern:
-<code>http://demo.volkszaehler.org/middleware.php/channel/[<uuid>].json?operation=edit&resolution=800</code>+<code>https://demo.volkszaehler.org/middleware/channel/[<uuid>].json?operation=edit&resolution=800</code> 
 + 
 +Beispiel um mehrer Kanäle abzufragen: 
 +<code>http://raspberrypi/middleware/data.json?uuid[]=f2e145a0-84d5-11e4-86e3-3587832d7a7e&uuid[]=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code>
  
 ===== Typen ===== ===== Typen =====
Zeile 30: Zeile 33:
 |[integer]|eine Ganzzahl mit optionalem Vorzeichen|/[+-]?\d+/| |[integer]|eine Ganzzahl mit optionalem Vorzeichen|/[+-]?\d+/|
 |[float]|eine Gleitkommazahl;\\ Dezimalpunkt ist "."| | |[float]|eine Gleitkommazahl;\\ Dezimalpunkt ist "."| |
-|[timestamp]|hier sind alle Formate gemäß "[[http://de3.php.net/manual/en/datetime.formats.php|PHP Date and Time Formats]]" erlaubt;\\ es können aber auch einfach nur die Anzahl der ms nach 1970 angegeben werden;\\ alle Zeitangaben beziehen sich auf die [[http://de.wikipedia.org/wiki/Koordinierte_Weltzeit|Koordinierte Weltzeit (UTC)]]\\ Der timestamp ist in Millisekunden anzugeben!| |+|[timestamp]|hier sind alle Formate gemäß "[[http://php.net/manual/en/datetime.formats.php|PHP Date and Time Formats]]" erlaubt;\\ es können aber auch einfach nur die Anzahl der ms nach 1970 angegeben werden;\\ alle Zeitangaben beziehen sich auf die [[http://de.wikipedia.org/wiki/Koordinierte_Weltzeit|Koordinierte Weltzeit (UTC)]]\\ Der timestamp ist in Millisekunden anzugeben!| |
 |[uuid]|jede nach [[http://www.ietf.org/rfc/rfc4122.txt|RFC4122]] valide UUID|/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/| |[uuid]|jede nach [[http://www.ietf.org/rfc/rfc4122.txt|RFC4122]] valide UUID|/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/|
 |[numeric]|ist [float] oder [integer]| | |[numeric]|ist [float] oder [integer]| |
Zeile 47: Zeile 50:
  
 <note tip>Möchte man einfach nur schnell mal einen Operation im Browser testen kann auch ein normaler GET-Request in Kombination mit einem zusätzlichen Parameter genutzt werden. Bsp: <note tip>Möchte man einfach nur schnell mal einen Operation im Browser testen kann auch ein normaler GET-Request in Kombination mit einem zusätzlichen Parameter genutzt werden. Bsp:
-<code>http://demo.volkszaehler.org/middleware.php/channel.json?operation=add&title=Test Zähler</code>+<code>https://demo.volkszaehler.org/middleware/channel.json?operation=add&title=Test Zähler</code>
 Bei der Angabe des "operation"-Parameters wird die Bestimmung der Operation durch die HTTP-Methode aufgehoben.</note> Bei der Angabe des "operation"-Parameters wird die Bestimmung der Operation durch die HTTP-Methode aufgehoben.</note>
  
Zeile 77: Zeile 80:
  
 === Messwerte abfragen === === Messwerte abfragen ===
-**Beispiel** +**Beispiele** 
-<code>GET http://demo.volkszaehler.org/middleware.php/data/550e8400-e29b-11d4-a716-446655441352.json?from=01-01-2010&to=01-02-2010</code>+<code>GET https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=01-01-2010&to=01-02-2010</code> 
 +<code>GET https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=7+days+ago&tuples=14</code>
  
 ^Parameter^Beschreibung^Standardwert^optional^ ^Parameter^Beschreibung^Standardwert^optional^
-|&tuples=[integer]|Anzahl der gewünschten Messwerte\\ Sind mehr Werte vorhanden, werden sie verdichtet\\ für //&tuples=0// werden nur Max, Min & Durchschnitts-Werte berechnet|alle Werte werden zurückgegen|ja|+|&tuples=[integer]|Anzahl der gewünschten Messwerte\\ Sind mehr Werte vorhanden, werden sie verdichtet|alle Werte werden zurückgegen|ja|
 |%%&group=(year|month|week*|day|hour|minute|second)%%|Gruppierung der Messwerte in konstante Zeitintervalle\\ (Überschreibt ggf. den //&tuples// Parameter)| |ja| |%%&group=(year|month|week*|day|hour|minute|second)%%|Gruppierung der Messwerte in konstante Zeitintervalle\\ (Überschreibt ggf. den //&tuples// Parameter)| |ja|
 |&from=[timestamp]|Startzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //jetzt//.\\ Ist //&to// nicht angegeben bezieht er sich auf //jetzt - 24h//|(jetzt - 24h)|ja| |&from=[timestamp]|Startzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //jetzt//.\\ Ist //&to// nicht angegeben bezieht er sich auf //jetzt - 24h//|(jetzt - 24h)|ja|
 |&to=[timestamp]|Endzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //&from//.\\ Ist //&from// nicht angegeben bezieht er sich auf //jetzt//|//jetzt//|ja| |&to=[timestamp]|Endzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //&from//.\\ Ist //&from// nicht angegeben bezieht er sich auf //jetzt//|//jetzt//|ja|
  
-* "week" ist derzeit nicht implementiert: https://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Volkszaehler/Util/Aggregation.php#L56+* "week" ist derzeit nicht implementiert: https://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Util/Aggregation.php#L68
  
 <note>Die Antwort wird in Form eines JSON-Arrays zurück geliefert. z.B.: <note>Die Antwort wird in Form eines JSON-Arrays zurück geliefert. z.B.:
Zeile 102: Zeile 106:
 Mit dieser Operation ist es möglich Pulse oder Messwerte für einen Kanal zu loggen. Mit dieser Operation ist es möglich Pulse oder Messwerte für einen Kanal zu loggen.
  
-**Beispiel** +**Beispiele** 
-<code>POST http://demo.volkszaehler.org/middleware.php/data/550e8400-e29b-11d4-a716-446655441352.json?ts=1284677961150&value=12</code>+<code>POST https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?ts=1284677961150&value=12</code> 
 +<code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=add&ts=1284677961150&value=12"</code>
  
 ^Parameter^Beschreibung^Standardwert^optional^ ^Parameter^Beschreibung^Standardwert^optional^
 |&ts=[timestamp]|Zeitpunkt der Messung|Zeit des Middlewareservers|ja| |&ts=[timestamp]|Zeitpunkt der Messung|Zeit des Middlewareservers|ja|
 |&value=[numeric]|absoluter Messwert oder Anzahl der Pulse seit der letzen Messung|1|ja| |&value=[numeric]|absoluter Messwert oder Anzahl der Pulse seit der letzen Messung|1|ja|
 +
 +
 +=== Messwerte löschen ===
 +
 +Mit dieser Operation ist es möglich Pulse oder Messwerte in einem Kanal zu löschen.
 +
 +**Beispiele**
 +
 +<code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&ts=1284677961150"</code>
 +<code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&from=1284677961150&to=now"</code>
 +
 +^Parameter^Beschreibung^Standardwert^optional^
 +|&ts=[timestamp]|Zeitpunkt der Messung|Zeit des Middlewareservers|nein|
 +|&from=[timestamp]|Startzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //jetzt//.\\ Ist //&to// nicht angegeben bezieht er sich auf //jetzt - 24h//|(jetzt - 24h)|nein|
 +|&to=[timestamp]|Endzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //&from//.\\ Ist //&from// nicht angegeben bezieht er sich auf //jetzt//|//jetzt//|ja|
 +
  
 ==== Kanal-Kontext ==== ==== Kanal-Kontext ====
Zeile 116: Zeile 137:
  
 **Beispiel** **Beispiel**
-<code>GET http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.json</code>+<code>GET https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code>
  
 === Kanal erstellen === === Kanal erstellen ===
Zeile 123: Zeile 144:
  
 **Beispiel** **Beispiel**
-<code>POST http://demo.volkszaehler.org/middleware.php/channel.json?type=power&resolution=2000&title=Testzähler</code>+<code>POST https://demo.volkszaehler.org/middleware/channel.json?type=power&resolution=2000&title=Testzähler</code>
  
 ^Parameter^Beschreibung^Standardwert^optional^ ^Parameter^Beschreibung^Standardwert^optional^
Zeile 135: Zeile 156:
  
 **Beispiel** **Beispiel**
-<code>DELETE http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.json</code>+<code>DELETE https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code>
  
 === Eigenschaften eines Kanals bearbeiten/löschen === === Eigenschaften eines Kanals bearbeiten/löschen ===
Zeile 142: Zeile 163:
  
 **Beispiel** **Beispiel**
-<code>PULL http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.json?description=neue Beschreibung</code>+<code>PULL https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?description=neue Beschreibung</code>
  
 ^Parameter^Beschreibung^Standardwert^optional^ ^Parameter^Beschreibung^Standardwert^optional^
Zeile 155: Zeile 176:
  
 **Beispiel** **Beispiel**
-<code>GET http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json</code>+<code>GET https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code>
  
 === Gruppe erstellen === === Gruppe erstellen ===
Zeile 162: Zeile 183:
  
 **Beispiel** **Beispiel**
-<code>POST http://demo.volkszaehler.org/middleware.php/group.json?title=neue Gruppe</code>+<code>POST https://demo.volkszaehler.org/middleware/group.json?title=neue Gruppe</code>
  
 ^Parameter^Beschreibung^Standardwert^optional^ ^Parameter^Beschreibung^Standardwert^optional^
Zeile 173: Zeile 194:
  
 **Beispiel** **Beispiel**
-<code>DELETE http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json</code>+<code>DELETE https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code>
  
 === Eigenschaften einer Gruppe bearbeiten/löschen === === Eigenschaften einer Gruppe bearbeiten/löschen ===
Zeile 180: Zeile 201:
  
 **Beispiel** **Beispiel**
-<code>PULL http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json?title=neuer Titel</code>+<code>PULL https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?title=neuer Titel</code>
  
 ^Parameter^Beschreibung^Standardwert^optional^ ^Parameter^Beschreibung^Standardwert^optional^
Zeile 191: Zeile 212:
  
 **Beispiel** **Beispiel**
-<code>POST http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json?uuid=550e8400-e29b-11d4-a716-44665512562</code>+<code>POST https://demo.volkszaehler.org/middleware/group/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code>
  
 ^Parameter^Beschreibung^Standardwert^optional^ ^Parameter^Beschreibung^Standardwert^optional^
Zeile 203: Zeile 224:
  
 **Beispiel** **Beispiel**
-<code>DELETE http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json?uuid=550e8400-e29b-11d4-a716-44665512562</code>+<code>DELETE https://demo.volkszaehler.org/middleware/group/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code>
  
 ^Parameter^Beschreibung^Standardwert^optional^ ^Parameter^Beschreibung^Standardwert^optional^
Zeile 212: Zeile 233:
  
 ** Beispiel ** ** Beispiel **
-<code>GET http://demo.volkszaehler.org/middleware.php/capabilities/definitions/entities.json</code> +<code>GET https://demo.volkszaehler.org/middleware/capabilities/definitions/entities.json</code> 
-<code>GET http://demo.volkszaehler.org/middleware.php/capabilities/database.json</code>+<code>GET https://demo.volkszaehler.org/middleware/capabilities/database.json</code>
  
 Es werden keine Parameter ausgewertet. Folgende Pfade sind verfügbar: Es werden keine Parameter ausgewertet. Folgende Pfade sind verfügbar:
  
 ^ Pfad ^ Beschreibung ^ ^ Pfad ^ Beschreibung ^
-|/middleware.php/capabilities|Alle Informationen| +|/middleware/capabilities|Alle Informationen| 
-|/middleware.php/capabilities/statistics|Server Load, Uptime, Git-Hash| +|/middleware/capabilities/statistics|Server Load, Uptime, Git-Hash| 
-|/middleware.php/capabilities/configuration|Database Middleware, Debug Mode| +|/middleware/capabilities/configuration|Database Middleware, Debug Mode| 
-|/middleware.php/capabilities/definitions/%%(properties|entities)%%|Liefert Definitionen von Entities oder deren Eigenschaften|+|/middleware/capabilities/definitions/%%(properties|entities)%%|Liefert Definitionen von Entities oder deren Eigenschaften|
  
 ====== Antwort ====== ====== Antwort ======
Zeile 233: Zeile 254:
 ^Dateiendung für die [[#URL]]^ Beschreibung ^ Verfügbar ^ ^Dateiendung für die [[#URL]]^ Beschreibung ^ Verfügbar ^
 |json|[[http://json.org|JavaScript Object Notation]]|ja (default)| |json|[[http://json.org|JavaScript Object Notation]]|ja (default)|
-|xml|[[http://www.w3.org/TR/2008/REC-xml-20081126/|Extensible Markup Language]]|ja| +|txt|einfache Textausgabe|ja| 
-|csv|[[http://www.ietf.org/rfc/rfc4180.txt|Komma-seperierte Werte]]|ja| +|csv|[[http://www.ietf.org/rfc/rfc4180.txt|Komma-separierte Werte]]|ja| 
-|png|Plotting Ausgabe mit [[http://jpgraph.net|jpGraph]]\\ Die Graphen werden durch die Middleware gerendert\\ und als Rastergrafik ausgegeben|(noch nicht implementiert)|+|png|Plotting Ausgabe mit [[http://jpgraph.net|jpGraph]]\\ Die Graphen werden durch die Middleware gerendert\\ und als Rastergrafik ausgegeben|ja (falls jpGraph installiert)|
 |gif|:::|:::| |gif|:::|:::|
 |jpg|:::|:::| |jpg|:::|:::|
Zeile 243: Zeile 264:
 |debug|integer|Debug Level (sollte größer 0 sein)|0|ja| |debug|integer|Debug Level (sollte größer 0 sein)|0|ja|
 |tsfmt|string|Zeitformat:|ms|ja| |tsfmt|string|Zeitformat:|ms|ja|
-| | |//sql//: yyyy-mm-dd HH:MM:SS| | +| | |//sql//: yyyy-mm-dd HH:MM:SS| |:::
-| | |//ms// (oder //unix//): Millisekunden seit 1.1.1970, 00:00 GMT|*| |+| | |//ms// (oder //unix//): Millisekunden seit 1.1.1970, 00:00 GMT|*|:::|
 |options|string|Optionen|keine|ja| |options|string|Optionen|keine|ja|
-| | |//raw//: Daten ohne Verarbeitung ausgeben (z.B. Zählerstände)| | | +| | |//raw//: Daten ohne Verarbeitung ausgeben (z.B. Zählerstände)| |:::
-==== JSON ==== +| | |//consumption//: Verbrauch ausgeben (Summe der Werte), für //group//| |:::| 
-^Parameter^Beschreibung^ +| |//skipduplicates//: Fehler beim Hinzufügen von Daten ignorieren (insbesondere Duplikate)| |:::| 
-|&padding=//funcname//|[[http://en.wikipedia.org/wiki/JSON#JSONP|JSON with padding]]|+|group|string|Ausgabe nach Zeitinterval aufsummieren: //year// //month// //week// //day// //hour// //minute// //second// \\ I.Anur mit //options=consumption// sinnvoll. \\ Timestamp ist der jeweils letzte des Intervals.| - |ja|
  
 ==== Plotting ==== ==== Plotting ====
development/api/reference.1447329968.txt.gz · Zuletzt geändert: 2015/11/12 13:06 von jau