Resource Access: Unterschied zwischen den Versionen

Aus ARTECO Wiki
Zur Navigation springen Zur Suche springen
 
(21 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Work_In_Progress}}
+
Diese Seite beschreibt den Zugriff auf [[:Category:WebserviceResources|Ressourcen]]. Das hier Beschriebene gilt im Allgemeinen für alle verfügbaren [[:Category:WebserviceResources|Ressourcen]].
  
Diese Seite beschreibt den Zugriff auf [[:Category:WebserviceResources|Resourcen]]. Das hier Beschriebene gilt im Allgemeinen für alle verfügbaren [[:Category:WebserviceResources|Resourcen]].
+
Um Zugriff auf [[:Category:WebserviceResources|Ressourcen]] zu erhalten benötigt man einen [[Users|Benutzeraccount]]. Hier gibt's Informationen zur [[Login|Authentifizierung]].
  
== Liste ==
+
== Liste von Ressourcen abfragen ==
Über die Listenfunktion erhält man eine Liste von den [[:Category:WebserviceResources|Resourcen]], die der aktuell angemeldete Benutzer berechtigt ist zu sehen.
 
 
 
Im Normalfall sind alle Resourcen einem [[Customers|Customer (Kunden)]] zugeordnet.
 
  
 
=== HTTP Befehl ===
 
=== HTTP Befehl ===
  GET /systems.xml
+
  GET /<resource name in plural>.xml
  
=== Mögliche Parameter in der URL ===
+
=== Beispiel ===
{| border="1"
+
Aufruf der Liste aller [[Systems|Systeme]]
| '''Parameter'''
+
  https://xml.arteco.de/systems.xml
| '''Bedeutung'''
 
|-
 
| only
 
| Komma getrennte Liste der gewünschten Felder
 
|}
 
 
 
=== Beispiele ===
 
Aufruf der Liste aller Systeme
 
  http://xml.arteco.de/systems.xml
 
 
 
Aufruf der Liste aller Systeme, jedoch nur die Felder "uuid" und "short_name"
 
http://xml.arteco.de/systems.xml?only=uuid,short_name
 
  
 
liefert eine Antwort wie diese
 
liefert eine Antwort wie diese
Zeile 37: Zeile 22:
 
  </systems>
 
  </systems>
  
== Ein System ==
+
== Eine einzelne Ressource abfragen ==
Diese Resource bietet Zugriff auf die Daten eines Systems.
+
Auf diese Art und Weise kann man die Daten einer einzelnen Ressource abfragen. Im allgemeinen wird eine Ressource über ihre [[UUIDs|UUID]] spezifiziert.
 
 
Das System wird entweder über die UUID oder über den 'short_name' spezifiziert.
 
Mit Hilfe der UUID können Systeme des eigenen Kunden und Systeme aller Unterkunden abgerufen werden.
 
Spezifiziert man das System über den 'short_name', so kann man nur Systeme des eigenen Kunden abrufen.
 
  
 
=== HTTP Befehle ===
 
=== HTTP Befehle ===
  GET /systems/UUID-DES-SYSTEMS.xml
+
  GET /<resource name in plural>/<uuid der ressource>.xml
GET /systems/SHORT-NAME-DES-SYSTEMS.xml
 
  
=== Mögliche Parameter in der URL ===
+
=== Beispiel ===
{| border="1"
 
| '''Parameter'''
 
| '''Bedeutung'''
 
|-
 
| only
 
| Komma getrennte Liste der gewünschten Felder
 
|}
 
 
 
=== Beispiele ===
 
 
Aufruf des Systems mit der UUID AC87BDDF-E44C-43CC-9134-A2285A18C30A
 
Aufruf des Systems mit der UUID AC87BDDF-E44C-43CC-9134-A2285A18C30A
  http://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml
+
  https://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml
 
 
Aufruf des Systems mit dem "short_name" "mein auto"
 
http://xml.arteco.de/systems/mein%20auto.xml
 
 
 
Aufruf des Systems mit der UUID AC87BDDF-E44C-43CC-9134-A2285A18C30A, jedoch nur die Felder "uuid" und "short_name"
 
http://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml?only=uuid,short_name
 
 
 
== Erstellen eines neuen Systems ==
 
So kann man ein neues System erstellen.
 
  
 +
== Eine neue Ressource erstellen ==
 
=== HTTP Befehl ===
 
=== HTTP Befehl ===
 
  POST /systems.xml
 
  POST /systems.xml
 
=== Mögliche Parameter in der URL ===
 
keine
 
  
 
=== Beispiel ===
 
=== Beispiel ===
 
Ein POST an
 
Ein POST an
  http://xml.arteco.de/systems.xml
+
  https://xml.arteco.de/systems.xml
  
 
mit folgendem Inhalt
 
mit folgendem Inhalt
 
  <system>  
 
  <system>  
 
   <name>Mein Auto</name>  
 
   <name>Mein Auto</name>  
  <provider-id>3</provider-id>
 
 
  </system>
 
  </system>
  
erstellt ein System mit dem Namen "Mein Auto" mit der Provider ID 3. Siehe auch [[HTTP Post per Telnet]].
+
erstellt ein System mit dem Namen "Mein Auto". Siehe auch [[HTTP Post per Telnet]].
  
Als Antwort liefert der Server das soeben erstelle System inclusive auf dem Server generierter Daten (wie z.B. der UUID) zurück.
+
Als Antwort liefert der Server das soeben erstelle System inclusive auf dem Server generierter Daten (wie z.B. der [[UUIDs|UUID]]) zurück.
 
  <system>  
 
  <system>  
  <connected type="boolean">false</connected>
 
  <created-at type="datetime">2009-06-19T10:34:06Z</created-at>
 
  <devicetype-id type="integer">0</devicetype-id>
 
  <fueltype-id type="integer">0</fueltype-id>
 
  <gmt-offset type="integer" nil="true"></gmt-offset>
 
  <gps-correction nil="true"></gps-correction>
 
  <license-plate></license-plate>
 
 
   <name>Mein Auto</name>  
 
   <name>Mein Auto</name>  
  <password></password>
 
  <provider-id type="integer">3</provider-id>
 
  <remarks></remarks>
 
  <serial></serial>
 
 
   <short-name></short-name>  
 
   <short-name></short-name>  
   <sms-number></sms-number>
+
   <created-at type="datetime">2009-06-19T10:34:06Z</created-at>  
  <status></status>  
 
 
   <updated-at type="datetime">2009-06-19T10:34:06Z</updated-at>  
 
   <updated-at type="datetime">2009-06-19T10:34:06Z</updated-at>  
  <use-dst type="boolean">false</use-dst>
 
 
   <uuid>AC87BDDF-E44C-43CC-9134-A2285A18C30A</uuid>  
 
   <uuid>AC87BDDF-E44C-43CC-9134-A2285A18C30A</uuid>  
 
   <customer-uuid>2BE6327F-6F47-487A-B3EE-28FC3BEC50CC</customer-uuid>  
 
   <customer-uuid>2BE6327F-6F47-487A-B3EE-28FC3BEC50CC</customer-uuid>  
   <last-world-x type="float"></last-world-x>
+
   ...
  <last-world-y type="float"></last-world-y>
 
  <last-map-text></last-map-text>
 
  <last-status type="integer"></last-status>
 
  <last-timestamp type="datetime"></last-timestamp>
 
 
  </system>
 
  </system>
  
== Ein System aktualisieren ==
+
== Eine vorhandene Ressource aktualisieren ==
So kann man ein vorhandenes System aktualisieren.
 
  
 
=== HTTP Befehl ===
 
=== HTTP Befehl ===
  PUT /systems/UUID-DES-SYSTEMS.xml  
+
  PUT /<resource name in plural>/<uuid der ressource>.xml
 
 
=== Mögliche Parameter in der URL ===
 
keine
 
  
 
=== Beispiel ===
 
=== Beispiel ===
 
Ein PUT an
 
Ein PUT an
  http://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml
+
  https://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml
  
 
mit folgendem Inhalt
 
mit folgendem Inhalt
Zeile 134: Zeile 72:
 
  </system>
 
  </system>
  
ändert den Namen des Systems mit der UUID AC87BDDF-E44C-43CC-9134-A2285A18C30A auf "Mein tolles Auto". Der Server liefert, wie auch beim Erstellen eines Systems, das XML Dokument zurück. Siehe auch [[HTTP Post per Telnet]].
+
ändert den Namen des [[Systems]] mit der [[UUIDs|UUID]] AC87BDDF-E44C-43CC-9134-A2285A18C30A auf "Mein tolles Auto". Der Server liefert, wie auch beim Erstellen eines [[Systems]], das XML Dokument zurück:
 +
 
 +
<system>
 +
  <name>Mein tolles Auto</name>
 +
  <short-name></short-name>
 +
  <created-at type="datetime">2009-06-19T10:34:06Z</created-at>
 +
  <updated-at type="datetime">2009-06-19T12:01:18Z</updated-at>
 +
  <uuid>AC87BDDF-E44C-43CC-9134-A2285A18C30A</uuid>
 +
  <customer-uuid>2BE6327F-6F47-487A-B3EE-28FC3BEC50CC</customer-uuid>
 +
  ...
 +
</system>
 +
 
 +
Siehe auch [[HTTP Post per Telnet]].
  
== Ein System löschen ==
+
== Eine vorhandene Ressource löschen ==
So kann man ein vorhandenes System löschen.
 
  
 
=== HTTP Befehl ===
 
=== HTTP Befehl ===
  DELETE /systems/UUID-DES-SYSTEMS.xml
+
  DELETE /<resource name in plural>/<uuid der ressource>.xml
 
 
=== Mögliche Parameter in der URL ===
 
keine
 
  
 
=== Beispiel ===
 
=== Beispiel ===
 
Ein DELETE an
 
Ein DELETE an
  http://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml
+
  https://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml
 +
 
 +
löscht das [[Systems|System]] mit der [[UUIDs|UUID]] AC87BDDF-E44C-43CC-9134-A2285A18C30A.
  
löscht das System mit der UUID AC87BDDF-E44C-43CC-9134-A2285A18C30A.
+
== Abfrage Parameter ==
 +
Beim Abfragen von Listen und einzelnen [[:Category:WebserviceResources|Ressourcen]] können [[:Category:UrlParameters|Parameter]] mit der URL übergeben werden. Auf den Seiten der [[:Category:WebserviceResources|Ressourcen]] ist dokumentiert, welche [[:Category:UrlParameters|Parameter]] unterstützt werden.

Aktuelle Version vom 8. Oktober 2012, 13:53 Uhr

Diese Seite beschreibt den Zugriff auf Ressourcen. Das hier Beschriebene gilt im Allgemeinen für alle verfügbaren Ressourcen.

Um Zugriff auf Ressourcen zu erhalten benötigt man einen Benutzeraccount. Hier gibt's Informationen zur Authentifizierung.

Liste von Ressourcen abfragen

HTTP Befehl

GET /<resource name in plural>.xml

Beispiel

Aufruf der Liste aller Systeme

https://xml.arteco.de/systems.xml

liefert eine Antwort wie diese

<systems>
 <system>
  ... 
 </system>
 <system>
  ... 
 </system>
</systems>

Eine einzelne Ressource abfragen

Auf diese Art und Weise kann man die Daten einer einzelnen Ressource abfragen. Im allgemeinen wird eine Ressource über ihre UUID spezifiziert.

HTTP Befehle

GET /<resource name in plural>/<uuid der ressource>.xml

Beispiel

Aufruf des Systems mit der UUID AC87BDDF-E44C-43CC-9134-A2285A18C30A

https://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml

Eine neue Ressource erstellen

HTTP Befehl

POST /systems.xml

Beispiel

Ein POST an

https://xml.arteco.de/systems.xml

mit folgendem Inhalt

<system> 
 <name>Mein Auto</name> 
</system>

erstellt ein System mit dem Namen "Mein Auto". Siehe auch HTTP Post per Telnet.

Als Antwort liefert der Server das soeben erstelle System inclusive auf dem Server generierter Daten (wie z.B. der UUID) zurück.

<system> 
 <name>Mein Auto</name> 
 <short-name></short-name> 
 <created-at type="datetime">2009-06-19T10:34:06Z</created-at> 
 <updated-at type="datetime">2009-06-19T10:34:06Z</updated-at> 
 <uuid>AC87BDDF-E44C-43CC-9134-A2285A18C30A</uuid> 
 <customer-uuid>2BE6327F-6F47-487A-B3EE-28FC3BEC50CC</customer-uuid> 
 ...
</system>

Eine vorhandene Ressource aktualisieren

HTTP Befehl

PUT /<resource name in plural>/<uuid der ressource>.xml

Beispiel

Ein PUT an

https://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml

mit folgendem Inhalt

<system> 
 <name>Mein tolles Auto</name> 
</system>

ändert den Namen des Systems mit der UUID AC87BDDF-E44C-43CC-9134-A2285A18C30A auf "Mein tolles Auto". Der Server liefert, wie auch beim Erstellen eines Systems, das XML Dokument zurück:

<system> 
 <name>Mein tolles Auto</name> 
 <short-name></short-name> 
 <created-at type="datetime">2009-06-19T10:34:06Z</created-at> 
 <updated-at type="datetime">2009-06-19T12:01:18Z</updated-at> 
 <uuid>AC87BDDF-E44C-43CC-9134-A2285A18C30A</uuid> 
 <customer-uuid>2BE6327F-6F47-487A-B3EE-28FC3BEC50CC</customer-uuid> 
 ...
</system>

Siehe auch HTTP Post per Telnet.

Eine vorhandene Ressource löschen

HTTP Befehl

DELETE /<resource name in plural>/<uuid der ressource>.xml

Beispiel

Ein DELETE an

https://xml.arteco.de/systems/AC87BDDF-E44C-43CC-9134-A2285A18C30A.xml

löscht das System mit der UUID AC87BDDF-E44C-43CC-9134-A2285A18C30A.

Abfrage Parameter

Beim Abfragen von Listen und einzelnen Ressourcen können Parameter mit der URL übergeben werden. Auf den Seiten der Ressourcen ist dokumentiert, welche Parameter unterstützt werden.