HTTP-Abfrage

Um dieses Beispiel zu versehen, werden zuerst alle Grundlagen zu HTTP erklärt. Dies ist wichtig, um die Funktionsweise der Schnittstelle zu verstehen.

Grundlagen

Die folgenden Punkte sollten unbedingt beachtet werden:

  • Bei einem Request über HTTP wird eine Verbindung vom Client aufgebaut, bis die Verbindung vom Server getrennt wird.
  • Die Abfrage erfolgt via TCP über Port 80 (HTTP unverschlüsselt) und über Port 443 (HTTPS verschlüsselt).
  • Wird Port 80 mit http:// oder Port 443 mit https:// verwendet, wird der Port ausgeblendet.
  • Die Verbindungsschicht ist ab HTTP/1.1 so, dass die Verbindung eine Zeit lang offengelassen wird, um das Handshake von TCP zu umgehen. Dies ist im Monitor von Antcas nicht zu sehen. Jedoch wird nach dem Timeout die Verbindung vom Client, also dem Antcas Server geschlossen. Das Timeout sollte daher entsprechen hoch sein.
  • Jede Abfrage ist voll rückwärts kompatibel. Ob ein Server HTTP/1.0, HTTP/1.1 oder HTTP/2 unterstützt ist dabei egal.
  • Der Header ist Case-Insensitive. Dies bedeutet, dass Gross- und Kleinschreibung keine Rolle spielen. Jedoch gibt es einige Hersteller, die nicht darauf achten dies so umzusetzen.
  • Die Zeichenkodierung in Antcas Control ist immer UTF-8. Werden andere verwendet, müssen diese ggf. konvertiert werden.
  • Die maximale Länge einer URL inkl. Query beträgt 2'083 Zeichen.

Der Aufbau einer URL sieht wie folgt aus:

http://server.tld/getdata?project=you%26i+project&id=25#anker
Komponente Bedeutung
http:// Definiert das Protokoll. Antcas Control unterstützt aktuell http und https.
server.tld Definiert die Domäne (DNS) oder IP-Adresse des Zielservers.
getdata Ist die URI des Servers. Diese entspricht der Zielseite, vergleichbar mit einem Pfad.
?[...] Das ? trennt die URL vom sogenannten GET-Request, dahinter folgen alle Formdaten auch Query genannt. Das Query wird immer enkodiert, um nicht unterstützte Zeichen zu ersetzen.
#[...] Das #-Zeichen definiert einen Anker auf einer Seite. So lässt sich an eine beliebige Stelle springen (scrollen). Diese Daten werden nicht an den Server übertragen. Ausserdem darf dieser Bereich inkl. # nicht in die Abfrage kopiert werden, da dies sonst eine andere Zielseite auf dem Server aufruft.

Die Konfiguration der Zielserver erfolgt im entsprechenden HTTP-Gateway.

Aufbau einer Abfrage

Der Aufbau einer Abfrage besteht aus einem Header und einem Body. Der Header zeigt in der ersten Zeile immer die verwendete Methode, die URI und das Protokoll an.

GET /getdata?project=you%26i+project&id=25 HTTP/1.1
Host: server.tld

Darauf folgt die Antwort des Servers. Diese beinhaltet den Statuscode der Abfrage. Der Body folgt dem Header mit einer leeren Zeile.

HTTP/1.1 200 OK
Server: Apache2
Content-Type: text/html

<html>Hallo Welt</html>

Statuscodes

Die Statuscodes sind in Gruppen eingeteilt. Die Gruppen werden durch die erste Ziffer definiert. Ausserdem kommt nach der Zahl die Bedeutung in Klartext. Hier einige Beispiele:

Status Beschreibung
200 OK Die Anfrage war erfolgreich.
301 Found Umleitung zur eigentlichen Seite. Da Antcas Control den Links folgt, wird diese Antwort meist ausgeblendet.
404 Not Found Die angegebene Seite wurde nicht gefunden.
500 Internal Server Error Ein Serverfehler ist aufgetreten.

Methoden

Die GET- und POST-Methoden werden am häufigsten verwendet.

Methode Beschreibung
GET Die GET-Abfrage ist die Standard-Abfrage. Diese unterstützt keinen Content.
POST Die POST-Abfrage sendet einen Content zum Server. Der Content darf auch leer sein. Der Vorteil ist hier, dass der Content keine Längenbeschränkung hat. Bei einer GET-Anfrage können nur eine bestimmte Anzahl an Daten übermittelt werden.
PUT PUT wird von Schnittstellen verwendet, um Informationen auszutauschen.
DELETE Zusammen mit PUT dient es dazu Daten zu löschen.
(andere) Antcas Control unterstützt alle weiteren Protokolle, dazu musst du dies entsprechend konfigurieren.

Authentifizierung

Die meisten Authentifizierungen finden im Header statt. Es gibt jedoch auch Anfragen, die im Query oder Content definiert werden.

Es kann sein, dass eine Session erzeugt werden muss, vor der eigentlichen Abfrage. Die Session wird dann als Header Set-Cookie gesetzt. Dieses Cookie muss dann wieder übergeben werden. Der Inhalt der Cookies ist Case-Sensitive, dies bedeutet der Inhalt muss eins zu eins übergeben werden. Hier ein vereinfachtes Beispiel:

POST /login HTTP/1.1
Host: server.tld

username=myname&password=1234

Antwort des Servers:

HTTP/1.1 200 OK
Server: Apache2
Content-Type: text/html
Set-Cookie: SESSION=vmvbquk7dq6dbbcq

Nun kann das Cookie in der nächsten Abfrage wieder verwendet werden:

GET /opendoor HTTP/1.1
Host: server.tld
Cookie: SESSION=vmvbquk7dq6dbbcq

Tipps

In der Entwicklerkonsole des Browsers kann unter Netzwerk die Anfrage ausgewertet und getestet werden. Ausserdem ist es manchmal ratsam den Header zu kopieren oder einzusehen.

Konfiguration

In Antcas Control wird eine HTTP-Schnittstelle mit einem Gateway angelegt. Das Gateway wird als HTTP-Client konfiguriert. Hier werden die Zieladresse und der Port (erforderlich) entsprechend eingetragen. Danach wird in der Struktur die Abfrage konfiguriert. Hierzu wird unter Kommunikation die URL als Variable eingetragen.

Einfache Abfrage

Um eine einfache Abfrage zu erstellen, wird ein beliebiger Datentyp gewählt. Dieser ist vorzugsweise eine Zeichenkette (string). Tritt am Ausgang eine Wertänderung ein, so wird bereits eine Abfrage ausgeführt. Der Wert wird dann direkt als Query verwendet.

Komplexe Abfrage

Eine komplexere Abfrage wird mittels Funktionsblock HTTP_REQUEST erstellt. Dazu muss der Datentyp der Kommunikation auf raw eingestellt sein. Die Antwort kann dann mittels Funktionsblock HTTP_RESPONSE ausgewertet werden. Die ID der Abfrage muss dazu unbedingt verknüpft werden, um die Antwort der Anfrage korrekt zuzuordnen.

Beispiel

In diesem Beispiel werden Daten mittels GET-Methode an einen Server gesendet und die Antwort ausgewertet. Die vollständige URL lautet wie folgt:

http://server.tld/getdata?project=you%26i+project&id=25

Damit Daten von von einem Server abgeholt oder gesendet werden können, wird folgendes Beispiel verwendet:

Hinweis: Das Beispiel zeigt nicht, wie der Request ausgelöst werden muss. Dieser wird mit einer positiven Flanke an dem Eingang SET ausgelöst. Um eine ungewollte Abfrage zu verhindert, sollte der Eingang DIS auf TRUE gesetzt werden.

Die Konfiguration der Schnittstelle wird wie folgt konfiguriert: