Dieses Tutorial zeigt auf, wie ein Webservice auf Basis von HTTP un JSON, vom Modulsystem abgefragt werden kann. Als Beispiel wird der Online-Wetterdienst von Openweathermap.org verwendet. Der Dienst für eine bestimmte Anzahl von Abfragen kostenlos genutzt werden. Um das Beispiel nachzubauen, benötigt man nur eine kostenfreie Registrierung.

Vor dem Beispiel, findet Ihr noch eine Erklärung der speziellen Komponenten zur Abfrage von HTTP-Diensten.

Komponenten für RestFull Webservices

CreateHttpUrlWithParams

Mit dieser Komponente kann, für eine folgende HTTP-Abfrage, die benötigte URL mit Parametern zusammengesetzt werden. Die Parameter müssen vorher in einer Variable vom Typ MAP gesammelt werden.

Eigenschaften der Komponente: requestUrl: URL des Webservices params: Variable vom Typ MAP mit Parametern Rückgabe der Komponente:  createdUrl: Rückgabe der kompletten URL als Text

HttpRequest

Mit dieser Komponente kann eine HTTP-Abfrage durchgeführt werden. Als HTTP-Methoden stehen GET, POST, PUT, PATCH und DELETE zur Auswahl. Die Abfrage wird synchron durchgeführt und kann individuelle Daten und Header enthalten. Zusätzlich lassen sich Zugangsdaten für eine HTTP-Authentifizierung mitsenden. 

Eigenschaften der Komponente: Method: HTTP-Methode URL: Ziel-URL Data to send: Daten die übermittelt werden sollen Username: Benutzername für HTTP-Authentifizierung Password: Passwort für HTTP-Authentifizierung httpHeaders: Variable vom Typ MAP mit Header-Daten Rückgabe der Komponente:  Response stream: Inhalt der HTTP-Antwort responseHeaders: Header der HTTP-Antwort HTTP status code: HTTP-Statuscode als Nummer

ReadFromStream

Mit dieser Komponente kann ein Daten-Stream in einen Text umgewandelt werden. Für die Umwandlung muss das Encoding (Zeichenkodierung) festgelegt werden.

Eigenschaften der Komponente: Read from: Stream der umgewandelt werden soll Encoding: Bestimmt mit welcher Encoding der Text gewandelt wird Rückgabe der Komponente:  Resulting text: Rückgabe des Textes

JsonToObject

Wandelt einen Text, der JSON 

Eigenschaften der Komponente: Read from: Stream der umgewandelt werden soll Rückgabe der Komponente:  Resulting text: Rückgabe des Textes

JSON

Die JavaScript Object Notation, kurz JSON, ist ein kompaktes Datenformat in einer einfach lesbaren Textform zum Zweck des Datenaustauschs zwischen Anwendungen (Quelle: Wikipedia). Viele moderne Webservices verwenden JSON zum Austausch von Informationen. Das STARFACE Modulsystem ermöglicht es, JSON-Objekte in List und Map-Objekte zu wandeln, welche mit weiteren Komponenten verarbeitet werden können.

Aufbau eines JSON-Objektes, am Beispiel eines Büro-Objektes

{
	"Raum 1": [{
			"Platz": "1"
			"name": "Niklas Held",
		}, {
			"Platz": "2"
			"name": "Miriam Laup",
		}
	],
	"Raum 2": [{
			"Platz": "1"
			"name": "Marcel Grachner",
		}, {
			"Platz": "2"
			"name": "Uschi Meier",
		}, {
			"Platz": "3"
			"name": "Franz Diertle",
		}
	],
	"Küche": ["Stuhl 1", "Stuhl 2"]
}

Ablaufdiagramm des Beispielmoduls

Anleitung zur Erstellung des Beispielmoduls

Zur Umsetzung unseres Beispieles verwenden zwei Audio-Dateien, die im Bereich Ressourcen in das Modul geladen werden müssen.

Hinweis: Einige der Komponenten findet ihr erst, wenn im Modul Designer der Expert mode im Bereich Components aktiviert ist. Die Beschreibung zu GetCaller und CallPhoneNumber findet ihr unter Anrufe mit dem Modulsystem verteilen (CallPhoneNumber). Die Beschreibung zu CurrentDateTime und MatchDateTimeInterval findet ihr unter Anrufe zeitgesteuert mit dem Modulsystem verteilen.

	Festlegen der Grundeinstellungen, wie Name und Hersteller. Konfiguration als Modul vom Typ Standard.
	Hochladen der Audiodateien für die Ansagen. Für das Beispiel verwenden wir die Ansage "Die Temperatur in XXX beträgt" und "Grad". Diese können unter dem Reiter Resources hochgeladen werden. Wichtig: Nach dem Hochladen, müssen diese in das Format Asterisk Soundfile konvertiert werden.
	Unter dem Bereich Development legen wir nun zwei neue Funktionen mit der Bezeichnung start und getTemperature an. Der Funktion getTemperature fügen wir zwei Ausgabe Variablen (Output Variables) hinzu. temperature als Number success als Boolean
	Im nächsten Schritt fügen wir die Komponente foreach (List) hinzu, welche die Zeitraumliste aus der GUI durcharbeitet.
	Unter der foreach-Schleife führen wir nun mit der Komponente MatchDateInterval die Überpüfung des einzelnen Wertes aus der Variable foreach_entry durch.
	Die Rückgabe der Komponente MatchDateInterval können wir nun mit einer bedingten Anweisung (if) abfragen und wenn eine Übereinstimmung gefunden wurde vermitteln wir das Telefonat mitCallPhoneNumber an die Zielrufnummer 1 weiter. Danach können wir das Modul an dieser Stelle mit exit beenden.
	Zuletzt fügen wir einen zweite Komponente CallPhoneNumber ein, welche im Fall keiner einzigen Übereinstimmung den Ruf an die Zielrufnummer 2 vermittelt. Zuletzt beenden wir das Modul auch an dieser Stelle.
Konfiguration des Modules
	In der Konfiguration des Modules finden wir in unserem Reiter Einstellungen die Zeiträume und Zielrufnummern als Eingabefelder.