Initiieren von Aufträgen mittels POST
In diesem Abschnitt werden folgende Schritte beschrieben:
•JSON-Syntax für POST Requests
•Hochladen von Dateien mit dem POST Request
Senden des Request
Ein RaptorXML+XBRL Server-Auftrag wird mit der HTTP POST -Methode initiiert.
HTTP-Methode | URI | Content-Type | Body |
POST | http://localhost:8087/v1/queue/ | application/json | JSON |
Beachten Sie die folgenden Punkte:
•Die obige URI hat eine Server-Adresse, für die die Einstellungen der Anfangskonfiguration verwendet werden.
•Die URI hat einen /v1/queue/ Pfad, der in der URI vorhanden sein muss. Dabei handelt es sich um einen abstrakten Ordner im Arbeitsspeicher, in den der Auftrag platziert wird.
•Die richtige Versionsnummer /vN ist diejenige, die der Server zurückgibt (und nicht notwendigerweise die in der Dokumentation verwendete). Die Nummer, die der Server zurückgibt, ist die Versionsnummer der aktuellen HTTP-Schnittstelle. Frühere Versionsnummern stehen für ältere Versionen der HTTP-Schnittstelle, die weiterhin aus Gründen der Rückwärtskompatibilität unterstützt werden.
•Der Header muss das Feld: Content-Type: application/json enthalten. Wenn Sie Dateien allerdings im Body des POST Request hochladen möchten, muss der Content-Type des Headers auf multipart/form-data (d.h. Content-Type: multipart/form-data) gesetzt werden. Nähere Informationen dazu finden Sie im Abschnitt Hochladen von Dateien mit dem POST-Request.
•Der Body des Request muss im JSON-Format sein.
•Die zu verarbeitenden Dateien müssen sich auf dem Server befinden, d.h. die Dateien müssen entweder vor Absenden des Request auf den Server kopiert werden oder sie müssen zusammen mit dem POST Request hochgeladen werden. In diesem Fall muss der Content-Type des Message Headers auf multipart/form-data gesetzt werden. Nähere Informationen dazu finden Sie im Abschnitt Hochladen von Dateien mit dem POST-Request.
Der Request zur Überprüfung der Wohlgeformtheit einer XML-Datei würde im JSON-Format in etwa folgendermaßen aussehen:
{
"command": "wfxml", "args": [ "file:///c:/Test/Report.xml" ]
}
Gültige Befehle, ihre Argumente und Optionen sind im Abschnitt zur Befehlszeile dokumentiert.
JSON-Syntax für HTTP POST Requests
{ "command": "Command-Name", "options": {"opt1": "opt1-value", "opt2": "opt2-value"}, "args" : ["file:///c:/filename1", "file:///c:/filename2"] }
•Der gesamte schwarze Text ist festgelegt und muss inkludiert werden. Dazu gehören alle geschweiften und eckigen Klammern, doppelten Anführungszeichen, Doppelpunkte und Kommas. Whitespaces können normalisiert werden.
•Bei Einträgen in blauer kursiver Schrift handelt es sich um Platzhalter. Sie stehen für Befehlsnamen, Optionen, Optionswerte und Argumentwerte. Eine Beschreibung der einzelnen Befehle finden Sie im Abschnitt zur Befehlszeile.
•Die Schlüssel command und args sind obligatorisch. Der Schlüssel options ist optional. Einige options Schlüssel haben Standardwerte, d.h. es müssen nur die Optionen angegeben werden, deren Standardwerte geändert werden müssen.
•Alle Strings müssen in doppelte Anführungszeichen gesetzt werden. Boolesche Werte und Zahlen dürfen keine Anführungszeichen haben. D.h.: {"error-limit": "unlimited"} und {"error-limit": 1} ist korrekt.
•Beachten Sie, dass es sich empfiehlt, anstelle von Dateipfaden Datei-URIs zu verwenden. Dafür werden Schrägstriche verwendet. Bei Verwendung von Windows-Dateipfaden werden umgekehrte Schrägstriche verwendet. Diese Windows Dateipfade müssen in JSON mit Escape versehen werden. (Das Escape-Zeichen ist der umgekehrte Schrägstrich: "c:\\dir\\filename"). Beachten Sie, dass URIs und Dateipfade Strings sind, die in Anführungszeichen gesetzt werden müssen. |
Hier sehen Sie ein Beispiel mit Optionen. Beachten Sie, dass einige Optionen (wie input oder xslt-version) einen direkten Optionswert erhalten, während andere (wie param) ein Schlüsselwertpaar als Wert erhalten, wofür eine andere Syntax erforderlich ist.
{
"command": "xslt",
"args": [
"file:///C:/Work/Test.xslt"
],
"options": {
"input": "file:///C:/Work/Test.xml",
"xslt-version": "1",
"param": {
"key": "myTestParam",
"value": "SomeParamValue"
},
"output": "file:///C:/temp/out2.xml"
}
}
Im unten gezeigten Beispiel sehen Sie eine dritte Art von Option: die eines Werte-Array (wie bei der Option xsd unten). In diesem Fall muss als Syntax die eines JSON Array verwendet werden.
{
"command": "xsi",
"args": [
"file:///C:/Work/Test.xml"
],
"options": {
"xsd" : ["file:///C:/Work/File1.xsd", "file:///C:/Work/File2.xsd"]
}
}
Hochladen von Dateien mit dem POST Request
Zu verarbeitende Dateien können im Body des POST Request hochgeladen werden. In diesem Fall muss der POST Request folgendermaßen erstellt werden.
Request Header
Setzen Sie im Request Header Content-Type: multipart/form-data und definieren Sie einen beliebigen String als Begrenzung. Hier sehen Sie einen Beispiel-Header:
Content-Type: multipart/form-data; boundary=---PartBoundary
Mit der Begrenzung (MyBoundary) werden die verschiedenen Formulardatenteile im Request Body voneinander abgegrenzt. (siehe unten).
Request Body: Message-Teil
Der Body des Request hat die folgenden Formulardatenteile, die durch den im Request Header definierten Begrenzungsstring (siehe oben) begrenzt sind:
•Obligatorische Formulardatenteile: msg, welches die angeforderte Verarbeitungsaktion definiert, und args, welches die Dateien enthält, die als das/die Argument(e) des im msg Formulardatenteil definierten Befehls hochzuladen ist/sind. Siehe Codefragment unten.
•Optionaler Formulardatenteil: Ein Formulardatenteil namens additional-files, welcher Dateien enthält, die von Dateien in den Formulardatenteilen msg oder args referenziert werden. Zusätzlich dazu können Formulardatenteile, die nach einer Option des Befehls benannt sind, ebenfalls hochzuladende Dateien enthalten.
Anmerkung: Alle hochzuladenden Dateien werden in einem einzigen virtuellen Verzeichnis angelegt.
In Beispiel-1 (mit Anmerkungen): XML validieren sowie in Beispiel-2: Suchen des Schemas über einen Katalog finden Sie eine genaue Erklärung zum Code.
Testen mit CURLSie können den POST Request mit Hilfe einer Datenübertragungsapplikation wie CURL (http://curl.haxx.se/) testen. CURL bietet eine hilfreiche Trace-Option, die die Abgrenzungen der Requests generiert und auflistet, so dass Sie diese nicht mehr manuell erstellen müssen. Eine Anleitung zur Verwendung von CURL finden Sie im Abschnitt Testen mit CURL.
|
Hochladen von ZIP-Archiven
ZIP-Archive können auch hochgeladen werden und Dateien innerhalb eines ZIP-Archivs können über das additional-files-Schema referenziert werden. Zum Beispiel:
additional-files:///mybigarchive.zip%7Czip/biginstance.xml
| Anmerkung: | Der |zip/-Teil muss als %7Czip/ URI-maskiert werden, damit er der URI RFC entspricht, da das Pipe-Symbol | direkt nicht zulässig ist. Auch globale Muster wie (* und ?) können verwendet werden. Sie können daher alle XML-Dateien in einem ZIP-Archiv mit einen Befehl wie dem folgenden validieren: {"command": "xsi", "args": ["additional-files:///mybigarchive.zip%7Czip/*.xml"], "options": {...}} |
Eine Liste des Beispielcodes finden Sie unter Beispiel-3: Verwendung von ZIP-Archiven.