Über REST Requests
Die Einstellungen für REST Requests werden im Dialogfeld "RESTful API Request" (Abbildung unten) definiert. Dieses Dialogfeld wird in zwei Situationen aufgerufen:
•Wenn Sie eine Seitenquelle definieren, in der die Verbindung zu einer Datenquelle mittels REST Request hergestellt wird
•über die Aktion REST Request ausführen; in diesem Fall kann die Antwort auf den Request in einer $MT_HTTPExecute_Result-Variablen gespeichert werden.
Sie können entweder (i) Ihre eigenen Einstellungen definieren, (ii) eine URL importieren oder (iii) eine WADL-Datei verwenden. Wenn Sie die Option zum Definieren eigener Einstellungen wählen, können Sie Ihre eigenen Definitionen für die einzelnen Einstellungen festlegen. Wenn Sie eine URL importieren oder eine WADL-Datei verwenden, so sind einige Einstellungen in der URL oder der WADL-Datei definiert und können von Ihnen nicht geändert werden.
Unten sind die verschiedenen Einstellungen beschrieben:
•Vorlagen und Parsen der Ergebnisse einschließlich $MT_HTTPExecute_Result
•URL
Vorlagen und Parsen der Ergebnisse
Mit Vorlagen sind die drei Rahmenvorgaben gemeint, innerhalb derer Einstellungen definiert werden können (Ihre eigenen Einstellungen, URL oder WADL; siehe Abbildung oben). Sie können jederzeit durch Auswahl des entsprechenden Optionsfelds zwischen diesen Vorlagen wechseln. Wenn die URL- oder WADL-Vorlagenoption bereits ausgewählt ist und Sie eine andere URL oder WADL-Datei auswählen möchten, klicken Sie auf Von URL importieren oder Aus WADL-Datei importieren. Wenn Sie die URL- oder WADL-Option auswählen (bzw. deren jeweilige Import-Schaltfläche), wird ein Dialogfeld geöffnet, in dem Sie die gewünschte URL oder WADL-Datei definieren können.
Eigene Einstellungen definieren
Wenn Sie Ihre eigenen Einstellungen definieren, können Sie einen Request an einen REST-Server als URL eingeben, das Datenformat der Zielressource definieren (XML, HTML oder JSON), anschließend Benutzerauthentifizierungsinformationen und, falls nötig, Abfrageparameter und HTTP-Inhalt und -Header eingeben. Nähere Informationen zu diesen Einstellungen finden Sie weiter unten.
URL verwenden
Bei einer langen oder komplexen URL ist es besser, die URL in der Vorlage URL verwenden zu importieren, anstatt sie in der Vorlage Eigene Einstellungen definieren einzugeben. So kann eine URL z.B. eine Reihe von Parametern enthalten, wie im Beispiel unten gezeigt (Dabei handelt es sich um eine Google-Abfrage, die fünf Parameter enthält):
https://www.google.at/search?q=REST+WADL&ie=utf-8&oe=utf-8&gws_rd=cr&ei=89cDVrDHMIP0Up_5vcAB
Wenn Sie diese URL importieren, wird sie in das Feld "URL" der Vorlage eingegeben und die Parameter werden automatisch in die Parametertabelle der Vorlage eingegeben. Sie können das Datenformat der Zielressource (XML, HTML oder JSON) und die Request-Methode (GET, PUT, POST oder DELETE) auswählen. Anschließend können Sie die Werte für die Parameter eingeben, einen Parameter aber nicht löschen oder seinen Typ ändern. Wenn Sie die URL ändern möchten, klicken Sie auf Von URL importieren. Eine Beschreibung der Parameter finden Sie weiter unten im Abschnitt Parameter.
WADL-Datei verwenden
Eine WADL-Datei ist ein XML-Dokument, in dem die von einem Webservice bereitgestellten Ressourcen und die Beziehungen zwischen diesen Ressourcen definiert sind. Die Ressourcen werden durch resource-Elemente definiert. Jede Ressource enthält: (i) param-Elemente zum Beschreiben der Inputs einer Ressource und (ii) method-Elemente zum Beschreiben des Request und der Response einer Ressource. Mit dem request-Element wird definiert, wie der Input repräsentiert wird, welche Typen erforderlich sind. Außerdem werden etwaige spezifische HTTP-Header, die benötigt werden, definiert. Mit dem response-Element werden die Response, d.h. die Antwort des Diensts, sowie Fehlerinformationen dazu beschrieben.
Wenn Sie die WADL-Option auswählen, werden Sie aufgefordert, die gewünschte WADL-Datei anzugeben. Nachdem Sie auf OK geklickt haben, wird das Dialogfeld "Methode auswählen" angezeigt (Abbildung unten). Hier werden die in der WADL-Datei definierten Methoden angezeigt.
Wählen Sie die gewünschte Methode aus und klicken Sie auf OK. Die URL der Ressource wird in das Feld "URL" der Vorlage eingegeben und die Parameter und der in der WADL-Datei für diese Ressource definierte HTTP-Inhalt und die HTTP-Header werden in die entsprechenden Tabellen der Vorlage eingegeben (siehe Abbildung unten). Sie können in der Vorlage die Werte der Parameter und HTTP-Inhalt und Header eingeben, Parameternamen können jedoch nicht bearbeitet und Parameter können nicht gelöscht werden.
Ergebnis parsen als
Das Ergebnis sind die Daten, die vom Webservice in Antwort auf den Request zurückgegeben werden. In den Vorlagen Eigene Einstellungen und URL müssen Sie angeben, wie dieses Ergebnis geparst werden soll (als XML, HTML oder JSON), damit MobileTogether das Ergebnis korrekt verarbeiten kann. In der WADL-Vorlage stammen die Informationen über das Ergebnisformat aus den Definitionen in der WADL-Datei, d.h. diese Informationen werden automatisch ausgewählt, daher sind diese Optionsfelder in dieser Vorlage deaktiviert.
$MT_HTTPExecute_Result
Sie können auswählen, ob das Ergebnis in der Variablen $MT_HTTPExecute_Result gespeichert werden soll oder nicht. Wenn es gespeichert wird, können Sie es über eine Variable an anderen Stellen im Design verwenden. Beachten Sie, dass diese Option im Dialogfeld "RESTful API Request" nicht angezeigt wird, wenn die Seitenquelle zum ersten Mal definiert wird. Sie wird angezeigt, wenn das Dialogfeld über die Aktion REST Request ausführen geöffnet wird.
Request-Methode
In den Vorlagen Eigene Einstellungen und URL müssen Sie die Request-Methode (GET, PUT, POST oder DELETE) oder ein anderes so genanntes benutzerdefiniertes Verb definieren. Ein benutzerdefiniertes Verb ist ein Verb, das vom Server, von dem die Datenquelle angefordert wird, verwendet wird und welches Sie für den Request verwenden möchten. Um ein benutzerdefiniertes Verb zu verwenden, wählen Sie diese Option aus und geben Sie in das angezeigte Textfeld das benutzerdefinierte Verb ein. Anstatt das benutzerdefinierte Verb direkt einzugeben, können Sie es mit Hilfe eines XPath-Ausdrucks generieren.
In der WADL-Vorlage wird die Request-Methode durch die Auswahl bestimmt, die Sie im Dialogfeld "Methode für eine Ressource auswählen" treffen (siehe Abbildung oben). Diese Methode wird in der Vorlage automatisch ausgewählt, daher sind diese Optionsfelder in dieser Vorlage deaktiviert.
Sie können die folgenden Timeout-Optionen konfigurieren:
•Ein Verbindungs-Timeout, d.h. die Zeit, bis eine TCP-Verbindung hergestellt ist.
•Ein Request-Timeout, d.h. die Zeit, in der der Request abgeschlossen sein muss.
Beide Werte können entweder direkt oder über einen XPath-Ausdruck eingegeben werden und müssen in Sekunden mit Kommastellen für Sekundenbruchteile angegeben werden. Die kleinste Einheit, die angegeben werden kann, ist eine Millisekunde.
URL
Das URL-Feld kann nur in der Vorlage Eigene Einstellungen definieren bearbeitet werden. In dieser Vorlage können Sie die URL direkt oder als XPath-Ausdruck eingeben. Über die Schaltfläche Zurücksetzen können Sie den Eintrag im Feld "URL" wieder löschen.
Nicht vertrauenswürdige SSL-Verbindungen zulassen
Ein mit einer URL verknüpftes Zertifikat gilt als nicht vertrauenswürdig, wenn es nicht durch ein vertrauenswürdiges Root-Zertifikat signiert ist oder wenn keine Verknüpfung zu einem vertrauenswürdigen Root-Zertifikat erstellt werden kann. Wenn das Zertifikat von einer bekannten Zertifizierungsstelle signiert wurde, bedeutet das lediglich, dass eine der Zertifikat-Chain-Dateien zwischen Ihrem Zertifikat und dem Root-Zertifikat auf dem Webserver nicht installiert ist. Wenn ein vertrauenswürdiges Zertifikat erwartet wird (z.B. weil das HTTPS-Protokoll definiert wurde), so werden bei Auswahl dieser Option auch Verbindungen mit URLs zugelassen, die ein nicht vertrauenswürdiges Zertifikat haben.
Authentifizierung
Falls vom Server benötigt, können Sie Authentifizierungsinformationen bereitstellen. Wenn keine Authentifizierung erforderlich ist, wählen Sie im Dialogfeld "RESTful API Request" die Option Keine aus (siehe Abbildung oben).
Authentifizierungsinformationen können auf die folgenden Arten bereitgestellt werden:
•Standardauthentifizierung: Es wird ein Benutzername und Passwort angegeben (siehe Abbildung unten)
•OAuth 1.0
•OAuth 2.0
Wenn Sie Authentifizierungsinformationen einrichten möchten, klicken Sie im Dialogfeld "RESTful API Request" auf Authentifizierung einrichten (siehe Abbildung oben). Daraufhin wird das Dialogfeld "Authentifizierungseinstellungen" angezeigt (Abbildung unten), in dem Sie die vom Server benötigte Art der Authentifizierung auswählen und die Authentifizierungsinformationen eingeben können.
OAuth-Authentifizierung
Im Prinzip authentifiziert OAuth MobileTogether Designer und autorisiert den Zugriff auf die Ressourcen des durch die URL identifizierten Webservice. Dies setzt voraus, dass der Webservice OAuth unterstützt. In der BitBucket-Dokumentation zu OAuth 1.0 finden Sie ein Beispiel für ein Webservice, das OAUTH unterstützt.
Das OAuth-System funktioniert in groben Zügen folgendermaßen:
1.Erstellen Sie im Webservice einen OAuth Schlüssel (key) oder eine ID und ein Secret. Gemeinsam werden diese als OAuth Consumer bezeichnet.
2.Notieren Sie sich die OAuth-Endpunkte des Webservice. Bei OAuth 1.0 gibt es drei Endpunkte (Initialer Endpunkt, Autorisierungsendpunkt und Token-Endpunkt), bei OAuth 2.0 gibt es zwei Endpunkte (Autorisierungsendpunkt und Token-Endpunkt). Die Endpunkte sind normalerweise für alle Consumer konstant.
3.Richten Sie die Applikation, die auf den Webservice zugreift, ein. Definieren Sie dazu diese fünf (OAuth 1.0) und vier (OAuth 2.0) Authentifzierungsbestandteile.
Nachdem Sie Ihren Schlüssel und Ihr Secret vom Webservice erhalten und sich die benötigten Endpunkte notiert haben, können Sie MobileTogether Designer für den Zugriff auf den Webservice einrichten. Gehen Sie dazu folgendermaßen vor:
1.Klicken Sie im Dialogfeld "Authentifizierungseinstellungen" (Abbildung oben) auf OAuth 1.0 einrichten oder OAuth 2.0 einrichten. Daraufhin wird das Dialogfeld "OAuth-Einstellungen" angezeigt (Abbildung unten).
2.Setzen Sie Callback-Adresse auf http://localhost:8083. Diese Adresse ist fix. Es handelt sich hierbei um die Adresse des Rechners, auf dem Sie arbeiten.
3.Neue Einstellungen erstellen: Geben Sie Ihren Einstellungen einen Namen. Auf diese Weise können Sie die Einstellungen (über die Auswahllistenoption Einstellungen wiederverwenden) für andere Lösungen, in denen dieselben Ressourcen verwendet werden, wiederverwenden.
4.Geben Sie die vom Webservice deklarierten Endpunkte ein. Diese sind normalerweise für den ganzen Webservice für alle Consumer des Webservice konstant.
5.Geben Sie Ihren Schlüssel (oder Ihre ID) und das Secret ein.
6.Klicken Sie zum Fertigstellen auf Autorisieren.
Parameter
In der Vorlage Eigene Einstellungen definieren können Parameter nach Belieben hinzugefügt, bearbeitet und gelöscht werden. In den Vorlagen URL verwenden und WADL-Datei verwenden können Sie hingegen nur die Werte von Parametern bearbeiten. Sie können Parameter nicht hinzufügen oder löschen oder ihre Namen bearbeiten.
Die folgenden Parameterarten (oder -stile) können hinzugefügt werden (siehe Spalte 'Stil' in der Abbildung unten):
•Template: In Vorlagenparametern werden Platzhalter verwendet, um einen Wert in einer URL zur Laufzeit zu ersetzen. In der Abbildung unten sehen Sie z.B. einen Vorlagenparameter mit dem Platzhalter {product}. Dieser Platzhalter wird in der URL verwendet (siehe Abbildung unten). Er steht zur Kennzeichnung als Platzhalter innerhalb von geschweiften Klammern. Bei Verwendung der URL zur Laufzeit wird der Wert des Platzhalters an der entsprechenden Stelle in der URL ersetzt. Der entsprechende Teil der URL würde daher aufgelöst werden zu: https://docs.altova.com/XMLSpy.../features.
•Matrix: Bei Matrix-Parametern wird der Platzhalter in der URL durch ein name=wert-Paar ersetzt. Im Beispiel in der Abbildung unten sehen Sie zwei Matrix-Parameter, die in der URL durch die Platzhalter {language} und {version} angegeben werden. Diese Platzhalter in der URL würden zu den folgenden blau markierten URL-Bestandteilen aufgelöst: https://docs.altova.com/XMLSpy;lang=en;ver=2016.../features. Vor jeden Parameter wird ein Semikolon-Trennzeichen ; als Teil der Ersetzungsgruppe gesetzt.
•Matrix Boolean: Wenn der Wert eines Booleschen Matrix-Parameters auf true gesetzt ist, so wird der Platzhalter des Parameters durch den Namen des Parameters ersetzt. Wenn der Wert auf false gesetzt wird, so wird der Platzhalter des Parameters durch den leeren String (d.h. durch nichts) ersetzt. Im Beispiel in der Abbildung unten würde der Boolesche Matrix-Parameter daher zum markierten Teil der URL aufgelöst werden: https://docs.altova.com/XMLSpy;lang=en;ver=2016;sort/features. Vor jeden Parameter wird ein Semikolon-Trennzeichen ; als Teil der Ersetzungsgruppe gesetzt.
•Query: In Query-, also Abfrageparametern, werden keine Platzhalter verwendet. Alle Abfrageparameter werden in einem Abfragestring gesammelt. Dieser String wird zur Laufzeit an den Pfadteil der URL angehängt. So würde die URL im Beispiel unten z.B. zur Laufzeit folgendermaßen aufgelöst: https://docs.altova.com/XMLSpy;lang=en;ver=2016;sort/features?type=PDF. Vor den Abfragestring wird ein Fragezeichen ? als Trennzeichen gesetzt. Vor weitere Abfragen wird als Trennzeichen ein kaufmännisches Und-Zeichen & gesetzt. Ein Abfragestring mit zwei Abfragen würde somit folgendermaßen aussehen: ?type=PDF&about=json.
Spalten der Parametertabelle
Die Parametertabelle hat vier Spalten. Die Verwendung der ersten drei Spalten wird weiter oben in der Beschreibung zu den Parameterarten erklärt. Beachten Sie, dass in Vorlagen-, Matrix- und Booleschen Matrix-Parametern Platzhalter verwendet werden. Während Vorlagenparameterplatzhalter durch Werte ersetzt werden, werden Matrix- und Boolesche Matrix-Parameterplatzhalter durch Name-Wert-Paare bzw. Namen ersetzt. Abfrageparameter haben keine Platzhalter; ihre Name-Wert-Paare werden an den Pfadteil der URL angehängt. Die Spalte Beschreibung enthält Beschreibungen der Parameter für Sie, den MobileTogether Designer-Benutzer.
Parametertabellensymbole und Tabellenbearbeitung
Rechts oberhalb der Parametertabelle befinden sich Symbole, über die Sie Einträge in der Tabelle verwalten können.
•Parameter anhängen und einfügen: Verwenden Sie Anhängen, um einen neuen Parameter als letzten Parameter in der Tabelle hinzuzufügen. Verwenden Sie Einfügen, um einen neuen Parameter direkt oberhalb des aktuell ausgewählten Parameters einzufügen. Die Reihenfolge, in der Parameter in die Tabelle eingegeben werden, spielt keine Rolle. Wichtig ist die Reihenfolge der Platzhalter in der URL. Alle Abfrageparameter werden in einem Abfragestring gesammelt, der zur Laufzeit an den Pfadteil der Url angehängt wird.
•Parameter löschen: Klicken Sie auf Löschen, um den ausgewählten Parameter zu löschen.
•XPath-Ausdrücke für Parameterwerte: Klicken Sie, während ein Parameter ausgewählt ist, auf XPath, um das Dialogfeld "XPath/XQuery-Ausdruck bearbeiten" zu öffnen und einen Ausdruck einzugeben, der zu einem String aufgelöst wird. Dieser String wird als der Wert des Parameters eingegeben. In diesen Fällen wird in der Spalte Wert des Parameters ein XPath-Symbol angezeigt. Wenn Sie auf dieses Symbol klicken, können Sie den XPath-Ausdruck bearbeiten.
•Parameterwerte zurücksetzen: Klicken Sie auf Parameter zurücksetzen, um den Wert des Parameters zu löschen.
•Parameternamen und -werte bearbeiten: Klicken Sie in das entsprechende Feld und bearbeiten Sie den Inhalt.
HTTP-Inhalt
Sie können Inhalt definieren, der mit HTTP PUT und POST Requests gesendet werden soll. Dabei können Sie den Inhalt als ein einziges Element im Body (Textkörper) des Request senden (Inhalt als Body senden) oder aber Sie senden mehrere Elemente in einem Multipart Request (mehrteiliger Request) (Inhalte als Multipart senden). Aktivieren Sie das entsprechende Optionsfeld bei diesen beiden Optionen.
Über die Symbole rechts oben können Sie Inhalt anhängen oder einfügen.
Inhalt als Body senden
Geben Sie den Wert des Inhalts und den MIME-Typ des Inhalts ein. Der Inhalt kann direkt eingegeben oder aus einem XML-Node ausgelesen werden.
Inhalte als Multipart senden
Geben Sie den Namen für den gesendeten Inhaltsteil, die Art des Zugriffs auf den Inhalt, den Inhalt selbst sowie den MIME-Typ des Inhalts ein. Beim Wert des Inhalts handelt es sich um den eigentlichen gesendeten Inhalt. In der Abbildung oben wird der Inhalt mit Hilfe von XPath-Ausdrücken aus Seitenquellen-Nodes abgerufen. Bilder werden im Base64-Format oder als Datei gesendet.
HTTP-Header-Felder
HTTP-Header-Felder sind durch einen Doppelpunkt getrennte Namen-Wert-Paare, z.B. Accept:text/plain. Fügen Sie durch Anhängen oder Einfügen einen Eintrag für jeden Header hinzu und geben Sie anschließend den Namen und Wert des Header ein (siehe Abbildung unten).
