Was ist WebserviceTool?
Multi Sprache
Daten eingeben und organisieren
Verschlüsselung
Daten finden und ersetzen
Anfrage ausführen
Massenanfragen ausführen
TLS Client Authentifizierung
Multi-User Nutzung ab zentraler Installation
Automatisierung mit BeanShell Scripts
WebserviceTool starten mit Kommandozeilen-Optionen
Fehlersuche und -behebung
Dieses Programm (Nachfolger von taSoapClient) ist ein generischer Webservice Klient mit welchem Sie HTTP und HTTPS basierte Webservices konsumieren können.
Es basiert auf der Eve VM 1.50 ( http://www.ewesoft.com). Zur Verbesserung der Leistung verwendet das Programm die JavaVM, falls installiert. Wenn Sie langsames Tastatur- oder Grafikverhalten feststellen, dann setzen Sie die Umgebungsvariable J2D_D3D=false bevor Sie WebserviceTool starten.
Das Programm hat folgende Leistungsmerkmale:
Das Programm wird in deutsch und englisch ausgeliefert, ist aber so konzipiert, dass es eine beliebige Anzahl Sprachen unterstützt. Um das Programm in Ihre Sprache zu übersetzen oder um die bestehenden deutschen / englischen Texte abzuändern, folgen Sie bitte den Anweisungen im 'Custom Language Package' (WebserviceTool-Custom.zip).
Beim obersten Eintrag können Sie die http Proxy Einstellungen definieren:
Wenn Sie einen neuen Webservice hinzufügen, müssen Sie folgende Informationen definieren:
Feldname:WertWenn Sie eine neue Anfrage zu einem Webservice hinzufügen, müssen Sie folgende Informationen definieren:
Feldname:Wert. Um globale Header Felder zu löschen, lassen Sie die Wert leer.Am Anfang der Anfragedatei können Sie das XML Encoding definieren. Dieses Encoding wird verwendet beim Lesen und Aktualisieren der Anfragedatei und braucht nicht zwingend übereinzustimmen mit demjenigen Encoding, welches bei der Kommunikation mit dem Webservice verwendet wird. Für Windows Systeme (mit nativer VM oder Java VM) empfehlen wir folgende Definition: <?xml version="1.0" encoding="ISO-8859-1"?>. Für Linux Systeme empfehlen wir <?xml version="1.0" encoding="UTF-8"?>. Falls kein XML Encoding definiert ist, wird ISO-8859-1 (=Windows1252, "ANSI") verwendet.
Das Programm kann SOAP XML Anfrage Dateien automatisch aus WSDL Dateien erstellen, welche den document/literal style verwenden. Wählen Sie hierzu den Menüpunkt 'Anfrage hinzufügen/aktualisieren aus WSDL' im 'Bearbeiten' Menü. Dieser Menüpunkt ist nur aktiv in der PRO Version und wenn eine Java VM 1.5 oder höher verwendet wird. Beim ersten Verwenden dieser Funktion müssen Sie ein SOAP Binding auswählen (später kann das Binding nicht mehr geändert werden, weil Operationen aus unterschiedlichen Bindings nicht gemischt werden dürfen). Dann können Sie die Operationen auswählen, für welche Sie Anfragen erstellen möchten. Anfragen, deren Namen mit dem Namen der Operation übereinstimmen, werden aktualisiert. XML Anfragedateien, deren Dateinamen mit dem Operationsnamen übereinstimmen, werden überschrieben mit den Definitionen aus der WSDL Datei. Nicht-existierende Anfragen werden am Schluss der Liste angehängt und die zugehörigen XML Anfragedateien werden im definierten 'Anfrage Verzeichnis' des Webservices erstellt. Alle Blatt-Elemente der XML Anfragedatei werden als Eingabefelder markiert (für Anpassungen siehe unten).
Wenn die WSDL vom Programm nicht unterstützt ist, empfehlen wir, dass Sie ein SOAP Programm wie das freie soapUI verwenden, um die XML Anfrage Dateien zu erstellen.
Sie können in den Anfragedateien Variablen im Format ${API.globalVars.key} verwenden. Diese werden beim Laden der Anfrage durch den Inhalt der entsprechenden Variable ersetzt. Die API.globalVars Variablen müssen über ein Script gesetzt werden (siehe API Dokumentation).
Beispiel:
<accountId>${API.globalVars.accId}</accountId>
Wenn Sie in einem Script mit API.globalVars.put("accId","1234"); die Variable API.globalVars.accId setzen, dann würde obiges XML-Element wie folgt eingelesen:
<accountId>1234</accountId>
In den Anfragedateien können Sie bei XML Elementen spezielle Attribute definieren (diese Attribute werden beim Senden der Anfrage nicht mitgeschickt):
{'formType':'dirChooser','optStartDir':'C:/Downloads'} // sie können / oder \\ verwenden
{'formType':'fileOpenChooser','optStartDir':'C:/Downloads'}
{'formType':'fileSaveChooser','optStartDir':'C:/Downloads'}
{'formType':'singleItemChooser','values':'value1,value2,value3','optLabels':'label1,label2,label3'} // optSeparator ist auch unterstützt
{'formType':'multiItemChooser','values':'value1\tvalue2\tvalue3','optSeparator':'\t'} // optLabels ist auch unterstützt
{'formType':'dateChooser','format':'dd.MM.yyyy'}
{'formType':'dateTimeChooser','format':'yyyy-MM-dd\'T\'HH:mm:ss'}
{'formType':'numericInput','minValue':1900,'maxValue':2100}
Sind in der Anfrage keine wst_ Attribute vorhanden, wird die Anfrage unmodifiziert geschickt (siehe ApiRequest.baRequest)
REST Webservices können neben dem POST Befehl weitere HTTP Befehle verwenden. Sie verwenden normalerweise GET, um Daten abzurufen und PUT oder POST, um Daten zu senden. Daten können als URL Parameter oder als PUT/POST Daten gesendet werden. Die Anfragen werden gleich definiert wie bei SOAP Anfragen, aber mit folgenden Abweichungen:
Untenstehend ist ein Beispiel für das Pivotal Tracker API (http://www.pivotaltracker.com/help/api).
<PivotalTracker>
<relativeURL>
<part1>projects</part1>
<part2 wst_title="Project number">1234</part2>
<part3>stories</part3>
</relativeURL>
<parameters>
<token wst_title="Security token" wst_noUpdate="true">010203040506070809A0</token>
</parameters>
<POSTdata>
<story>
<story_type wst_title="Story type">feature</story_type>
<name wst_title="Story name">User Story 123</name>
<requested_by wst_title="Requestor">Tom Arn</name>
<description wst_title="Story description">This is the user story number 123</description>
</story>
</POSTdata>
</PivotalTracker>
Wenn Sie die (Basis) URL für diesen Webservice als https://www.pivotaltracker.com/services/v3 definieren, wird mit den obigen Anfragedaten ein dynamisches GUI erzeugt, wo Sie die relativen Teile der URL, die URL Parameter und die POST Daten eingeben können. Wenn die Anfrage an den Webservice geschickt wird, wird folgender HTTP Rohcode gesendet:
POST /services/v3/projects/1234/stories?token=010203040506070809A0 HTTP/1.1 Host: www.pivotaltracker.com Content-Type: text/xml; charset=utf-8 Content-Length: 181 <story> <story_type>feature</story_type> <name>User Story 123</name> <requested_by>Tom Arn</name> <description>This is the user story number 123</description> </story>
Datenverschlüsselung wird in folgenden Kontexten verwendet:
Sie können nach Webservices / Anfragen suchen, welche einen Suchbegriff enthalten. Die Suche unterscheidet nicht nach Gross- und Kleinschreibung und durchsucht alle Textfelder aller Einträge.
'Finden' sucht immer ausgehend vom obersten Eintrag im Baum. 'Finde nächsten' fährt mit der Suche fort beim Eintrag nach dem aktuell selektierten Eintrag.
Mit 'Finden und Ersetzen' kann ein Text definiert werden, welcher dann bei 'Ersetzen, finde nächsten' den Suchbegriff im aktuell selektierten Eintrag ersetzt.
Um eine Anfrage auszuführen, müssen Sie eine Anfrage selektieren und 'Anfrage ausführen' wählen. Das Programm erstellt nun dynamisch eine Eingabemaske, basierend auf der definierten Anfragedatei. Geben Sie alle Eingaben ein und drücken sie OK. Das Programm übernimmt nun Ihre Eingaben in die Anfrage, schickt diese an den Webservice und stellt die Antwort in einem neuen Reiter am Schirm dar. Bei SOAP Webservices wird auch die Anfrage in einem Reiter angezeigt.
Wenn Sie eine Anfrage mehrmals mit unterschiedlichen Daten machen wollen, können Sie dies mit der Funktion Massenanfrage automatisieren:
Diese Funktion hängt vom Typ der Lizenz ab, die Sie gekauft haben und ist daher möglicherweise für Sie nicht verfügbar.
Wenn Ihre Client Credentials in einer PKCS12 Datei (Extension .p12) gespeichert sind, dann müssen Sie mit dem openssl Programm den privaten Schlüssel und das Zertifikat extrahieren.
Um das Zertifikat zu extrahieren geben Sie folgenden Befehl ein:
openssl pkcs12 -clcerts -nokeys -in ihreDatei.p12 -out ihreDatei-clcert.pem
Dies erstellt die Datei ihreDatei-clcert.pem welche das Zertifikat in folgendem Block enthält:
-----BEGIN CERTIFICATE-----
MII...
-----END CERTIFICATE-----
Sie können diesen Block nun kopieren und in WebserviceTool einfügen.
Um den privaten Schlüssel zu extrahieren geben Sie folgende Befehle ein:
openssl pkcs12 -nocerts -in ihreDatei.p12 -out ihreDatei-private.pem
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in ihreDatei-private.pem -out ihreDatei-private_pkcs8.pem
Dies erstellt die Datei ihreDatei-private_pkcs8.pem welche den unverschlüsselten privaten Schlüssel in folgendem Block enthält:
-----BEGIN PRIVATE KEY-----
MII...
-----END PRIVATE KEY-----
Sie können diesen Block nun kopieren und in WebserviceTool einfügen.
Da die Datei ihreDatei-private_pkcs8.pem den privaten Schlüssel in unverschlüsseltem Format enthält, löschen Sie anschliessend diese Datei und wählen Sie ein sicheres Passwort für Ihre Webservice Datei (.ws5), damit Ihr privater Schlüssel gut geschützt bleibt.
Mehrere Benutzer können die Applikation ab einer zentralen Installation starten und die gemeinsamen Webservice Definitionsdateien benutzen. Hierzu unterstützt die Applikation folgende Funktionalitäten:
Mit BeanShell Scripts (www.beanshell.org) können ganze Abläufe automatisiert werden im GUI und von der Kommandozeile. Die Scripts müssen die Erweiterung .bsh haben, müssen im UTF-8 Zeichensatz geschrieben und anschliessend signiert werden. Wenn Sie zum Schreiben nicht den internen Editor verwenden wollen, müssen Sie die fertigen Scripts am Ende mit dem internen Editor öffnen und speichern, damit das Script dann korrekt signiert ist.
In den Einstellungen können Sie definieren, dass Sie Scripts mit fremder Signatur bestätigen wollen, bevor sie ausgeführt werden. Wenn Sie zudem angeben, dass Sie die bestätigten Script-Signaturen cachen wollen, werden Ihre Bestätigungen gespeichert (in %userprofile%\WebserviceTool\SignatureCache.properties), so dass Sie unveränderte Scripts nicht erneut bestätigen müssen.
In den Einstellungen können Sie auch Regex Ausdrücke definieren, mit denen Sie Fehlermeldungen in der Script Console matchen können. Mit dem Knopf "Gehe zu Fehler" in der Script Console können Sie dann das Script im Editor aufrufen und gleich zur fehlerhaften Zeile springen. Sie können mehrere Regex Ausdrücke definieren, 1 pro Zeile. Die Ausdrücke müssen eine Gruppe <filename> und optional eine Gruppe <linenumber> enthalten. In den Standard-Einstellungen finden Sie einige Beispiele dazu.
Sie können in den Scripts alle Klassen der Eve Class Library und der weiteren integrierten Java Libraries verwenden (siehe separate API Dokumentation).
Beispiel für ein GUI Script:
this.interpreter.setStrictJava(true);
import ch.tanapro.WebserviceTool.api.*;
import bsh.*;
import nanoxml.*;
ApiWebserviceFile awsf;
ApiRequest req;
ApiResponse resp;
String token;
boolean ok;
int rc;
// checks for error and cleans up in case of error
boolean fnCheckForError()
{
if (API.lastError == null) return false;
System.out.println(API.lastError);
return true;
}
// main script
System.out.println("Starting GUI script");
if (!API.isGuiAvailable())
{
System.out.println("This script can only run from the GUI");
return;
}
// get currently open webservice file
awsf = API.wsFile;
// get request
req = API.getRequestByID (1454686907404L); // the id can be found in File -> Infos
if (fnCheckForError()) return;
System.out.println("Token request loaded successfully");
// let the user enter the token data
rc = API.guiEditRequest(req);
if (rc==1) API.lastError="Cancelled by user";
if (fnCheckForError()) return;
// invoke token request
System.out.println("Sending token request...");
resp = API.invokeRequest (req, null);
if (fnCheckForError()) return;
System.out.println("Token request invoked successfully");
// show in GUI
rc = API.guiShowInGUI(req, resp, "");
if (fnCheckForError()) return;
// get token from response
System.out.println("Getting token");
XMLElement xml = API.getXMLElementByXpath(resp.xResponse, "/REST/XML/access_token");
if (xml==null) API.lastError="Token not found";
if (fnCheckForError()) return;
token = xml.getContent();
System.out.println("Token found successfully");
// get request selected in GUI
System.out.println("Invoking request #"+awsf.selectedRequest);
req = API.getRequestByID (awsf.selectedRequest);
if (fnCheckForError()) return;
System.out.println("Request loaded successfully");
// let the user enter the request data
rc = API.guiEditRequest(req);
if (rc==1) API.lastError="Cancelled by user";
if (fnCheckForError()) return;
// invoke request
System.out.println("Setting token...");
req.setHeaderField ("Authorization", "bearer "+token); // set access token
System.out.println("Sending request...");
resp = API.invokeRequest (req, null);
if (fnCheckForError()) return;
System.out.println("Request invoked successfully");
// show in GUI
rc = API.guiShowInGUI(req, resp, "b");
if (fnCheckForError()) return;
Um ein Script von der Kommandozeile zu starten, muss das Programm wie folgt gestartet werden:
java -cp eve.jar Eve WebserviceTool.eve -S scriptfile.bsh
oder
eve WebserviceTool.eve -S scriptfile.bsh
Eine komplette Liste der verfügbaren Programmparameter erhalten Sie mit dem Parameter -?
Beispiel für ein Kommandozeilen-Script:
this.interpreter.setStrictJava(true);
import ch.tanapro.WebserviceTool.api.*;
import java.util.Vector;
import bsh.*;
import nanoxml.*;
ApiWebserviceFile awsf=null;
ApiRequest req;
ApiResponse resp;
Vector vInput, vData;
boolean ok;
// checks for error and cleans up in case of error
boolean fnCheckForError()
{
if (API.lastError == null) return false;
System.out.println(API.lastError);
if (awsf!=null) API.closeWebserviceFile();
return true;
}
// main script
System.out.println("Starting commandline script");
awsf = API.loadWebserviceFile(API.webserviceFile, "N7YExq7qhDbFLkMyYPxN2h7zk83Nse/+JQvuQw00IZnZPJPQWJRELGcqPr2YBpwc1x/q3vN7I11RdAZWW062PaBOvOZYLJbfZa2V4IOSYAP+juy8XGiH/+qHYpGodqro");
if (fnCheckForError()) return;
// get the key with:
// System.out.println(API.getEncryptedKey("the password for the webservice file"));
req = API.getRequestByID (1454402306498L);
if (fnCheckForError()) return;
vInput = API.readInputFile(API.inputFile); // Vector of Vectors of String
if (fnCheckForError()) return;
vData = (Vector) vInput.get(0); // Vector of Strings
resp = API.invokeRequest (req, vData);
if (fnCheckForError()) return;
// You can get the response like this:
// String response = resp.xResponse.toString();
System.out.println("Saving logs...");
resp.saveLogs();
API.closeWebserviceFile();
Mehr Details zum API finden Sie in der separaten API Dokumentation.
EinschränkungenDiese Funktion hängt vom Typ der Lizenz ab, die Sie gekauft haben und ist daher möglicherweise für Sie nicht verfügbar.
Starten Sie WebserviceTool mit
java -cp eve.jar Eve WebserviceTool.eve [Optionen] oder: javaw -cp eve.jar Eve WebserviceTool.eve [Optionen] oder: evew WebserviceTool.eve [Optionen] oder: eve WebserviceTool.eve [Optionen] Verwenden Sie javaw.exe/evew.exe für den GUI Modus und java.exe/eve.exe für den Konsolenmodus. Verfügbare Optionen: [-?], zum Anzeigen der Kommandozeilen-Optionen [-d], zum Aktivieren des Debuggings [-F <Schriftgrösse>] (default = automatisch) [-W <webserviceFile.ws5>] [-S <scriptFile.bsh>] [-U <username>], nur zusammen mit -S [-P <password>], nur zusammen mit -S [-I <inputFile>], nur zusammen mit -S [-O <outputFile>], nur zusammen mit -S Folgende Exit Codes werden zurückgegeben: 0 = OK 1 = Warnung 2 = Fehler Der Exit Code kann in einem Skript gesetzt werden durch API.setScriptResultCode(int code)
Wenn Sie WebserviceTool unter Windows verwenden, dann sollten Sie es aus einer Batchdatei starten und vorher folgenden Befehl einfügen:
set J2D_D3D=false
Dies erhöht massiv die Grafikleistung auf vielen Systemen.
Generell läuft WebserviceTool mit der JavaVM 3 bis 4 schneller als mit der EveVM.
Wenn Sie beim Arbeiten mit dem Programm Probleme feststellen, können Sie den Debug Modus aktivieren. In diesem Modus sammelt das Programm bei gewissen Operationen zusätzliche Informationen, welche Sie sich danach anzeigen lassen können. Diese Informationen können Ihnen helfen, herauszufinden wo das Problem liegt.
Wenn das Programm startet, ist der Debug Modus immer inaktiv. Das Programm merkt sich den Zustand des Debug Modus nicht.