Beispiel-6: XQuery-Ausführung
In diesem Beispiel wird unter Windows mittels Power Shell ein XQuery-Dokument an einem XML-Dokument ausgeführt. Beide Dokumente befinden sich im Ordner examples Ihres Applikationsordners (RaptorXMLServer2024).
| Anmerkung: | Unter Umständen werden Anführungszeichen auf anderen Shells anders verwendet ('bash' funktioniert mit dem Beispiel, wenn man anstelle von 'curl.exe' 'curl' verwendet). |
Bereitstellen des POST-Requests zur Validierung von Inline XBRL mittels CURL
Unten finden Sie einen CURL-Beispielbefehl, mit dem ein Inline XBRL-Validierungs-Request gesendet wird.
\path\to\curl.exe -F 'msg={\"command\": "xquery", "args": ["additional-files:///CopyInput.xq"], "options": {"input": "additional-files:///simple.xml", "output": "MyQueryResult"}};type=application/json' -F "additional-files=@CopyInput.xq;type=text/plain" -F "additional-files=@simple.xml;type=application/xml" http://localhost:8087/v1/queue
Zur einfacheren Lesbarkeit:
(1) -F 'msg={
(2) "command": "xquery",
(3) "args": ["additional-files:///CopyInput.xq"],
(4) "options": {"input": "additional-files:///simple.xml", "output": "MyQueryResult"}
(5) };type=application/json'
(6) -F "additional-files=@CopyInput.xq;type=text/plain"
(7) -F "additional-files=@simple.xml;type=application/xml"
(7) http://localhost:8087/v1/queue
Input
Die verschiedenen Teile des CURL-Befehls werden unten anhand der oben angeführten Nummern erklärt.
(1) -F 'msg={...}' definiert ein Formularfeld mit dem Namen 'msg'
Aufgrund der Option -F (i) generiert CURL ein mehrteiliges Formular-POST mit dem Content-Type: multipart/form-data und (ii) fügt dieses form-Feld automatisch zum Request Header hinzu. Zur Beschreibung des von RaptorXML Server auszuführenden Befehls verwenden wir ein JSON-Objekt.
Content-Type: multipart/form-data; boundary=--------------------
CURL übersetzt diese Option im HTTP-Request folgendermaßen:
Content-Disposition: form-data; name="msg"
Content-Type: application/json
{"command": "xquery", "args": ["additional-files:///CopyInput.xq"], "options": {"input": "additional-files:///simple.xml", "output": "MyQueryResult"}}
(2) Der auf dem Server auszuführende RaptorXML Server-Befehl. Informationen zu Befehlen, die hier verwendet werden können, finden Sie unter Befehlszeilenschnittstelle (CLI). Der Befehl für die XQuery-Ausführung lautet in unserem Beispiel XQuery.
(3) Die Argumente des Befehls (die von der RaptorXML Server-Befehlszeile akzeptiert werden) sind als JSON-Array kodiert. RaptorXML Server verwendet ein explizites Schema additional-files://, um zusätzliche Ressourcen in einem separaten additional-files-Formularfeld zu referenzieren. In unserem Beispiel referenzieren wir das XQuery-Dokument CopyInput.xq.
| Anmerkung: | Alle Ressourcen im args-Array müssen auf dem Server verfügbar sein oder mit einem Request ähnlich denen in Punkt (6) und (7) bereitgestellt werden. |
(4) Die Optionen des Befehls (die von der RaptorXML Server-Befehlszeile akzeptiert werden) sind als JSON-Objekt kodiert. Wenn die Standardwerte von Optionen für Ihre Bedürfnisse geeignet sind (siehe Abschnitt CLI), kann dieser Teil weggelassen werden. In unserem Beispiel definieren wir (i) die XML-Datei, an der die XQuery ausgeführt werden soll und (ii) die Datei, in der die Ausgabe der XQuer-Ausführung gespeichert werden soll.
(5) Der Content-Type des msg-Formularfelds wird nach der Definition des Formularfelds angegeben und durch ein Semikolon vom Wert des Formularfelds getrennt. In unserem Beispiel wird der Content Type von msg durch type=application/json angegeben.
(6) Dateien, die zusätzliche Ressourcen für den Befehl enthalten, können mit Hilfe des additional-files-Formularfelds definiert werden. In unserem Beispiel definieren wir zwei zusätzliche Ressourcen: (i) @CopyInput.xq, gefolgt von einem Semikolon als Trennzeichen und anschließend seinem Content-Type, den wir als type=text/plain angeben; (i) simple.xml, gefolgt von einem Semikolon als Trennzeichen und anschließend seinem Content-Type, den wir als type=application/xml angeben.
| Anmerkung: | Stellen Sie dem Dateinamen das Zeichen @ voran, damit CURL (i) den Dateinamen als Wert der Eigenschaft filename und (ii) den Inhalt der Datei als Wert des Formulars verwendet. Das additional-files-Formularfeld kann mehrmals bereitgestellt werden, einmal für jede zusätzliche für den Befehl erforderliche Ressource. CURL übersetzt diese Option in den folgenden HTTP-Request: |
Content-Disposition: form-data; name="additional-files"; filenam
Content-Type: text/plain
<<content of CopyInput.xq>>
Content-Disposition: form-data; name="additional-files"; filename="simple.xml"
Content-Type: application/xml
<<content of simple.xml>>
| Anmerkung: | Dateien aus anderen Ordnern können durch Voranstellen des relativen Pfads vor den Dateinamen angegeben werden: -F "additional-files=@Examples/CopyInput.xq;type=text/plain". Wenn jedoch eine zusätzliche Datei aus einem anderen Ordner auf diese Art angegeben wird, muss sie durch Angabe des Dateinamens allein referenziert werden. Beispiel: |
\path\to\curl.exe -F 'msg={\"command\": "xquery", "args": ["additional-files:///CopyInput.xq"], "options": {"output": "MyQueryResult"}};type=application/json' -F "additional-files=@Examples/CopyInput.xq;type=text/plain" http://localhost:8087/v1/queue
Wenn Sie eine Ordnerstruktur beibehalten möchten, speichern Sie die Dateien in einem ZIP-Ordner und referenzieren Sie die Dateien auf die übliche Art für ZIP-Ordner.
Ausgabe
Von RaptorXML Server wird ein JSON-Objekt ausgegeben:
{"jobid": "42B8A75E-0180-4E05-B28F-7B46C6A0C686", "result": "/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686"}
Das JSON-Objekt enthält einen jobid-Schlüssel und einen result-Schlüssel. Der Wert des result-Schlüssels ist der Pfad zum Ergebnis. Dieser Pfad muss an den Teil <scheme>://<host>:<port>, der zum Bereitstellen des Request verwendet wird, angehängt werden. In unserem Beispiel würde die vollständige Ergebnis-URL folgendermaßen lauten: http://localhost:8087/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686. Die Ergebnis-URL wird auch verwendet, um das Ergebnis der Befehlsausführung anzufordern. Siehe Abrufen des Ergebnisdokuments.
Abrufen des Fehlers/der Nachricht/der Ausgabe des POST-Request
Der Input-Befehl zum Abrufen des Fehlers/der Nachricht/der Ausgabe des POST-Request (siehe Abrufen von Fehler-/Meldungs-/Ausgabedokumenten) würde in etwa folgendermaßen lauten:
curl.exe http://localhost:8087/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686
In our example, this command returns the following JSON object:
{"jobid":"42B8A75E-0180-4E05-B28F-7B46C6A0C686","state":"OK","error":{},"jobs":[{"file":"additional-files:///simple.xml","jobid":"768656F9-F4A1-4492-9676-C6226E30D998","output":{"result.trace_file":["/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/trace.log"],"xquery.main_output_files":["/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1"],"xquery.additional_output_files":[]},"state":"OK","output-mapping":{"/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1":"file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2016/Output/768656F9-F4A1-4492-9676-C6226E30D998/MyQueryResult"},"error":{}}]}
Zur besseren Lesbarkeit wurde dies unten in separaten Zeilen formatiert und mit nummerierten Beschreibungen versehen:
%1 :
(2) "jobid":"42B8A75E-0180-4E05-B28F-7B46C6A0C686",
(3) "state":"OK",
(4) "error":{},
(5) "jobs":[{
(6) "file":["additional-files:///simple.xml"],
(7) "jobid":"768656F9-F4A1-4492-9676-C6226E30D998",
(8) "output":{
(9) "result.trace_file":["/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/trace.log"],
(10) "xquery.main_output_files":["/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1"],
(11) "xquery.additional_output_files":[]},
(12) "state":"OK",
(13) "output-mapping":{
(14) "/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1":
(15) "file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2016/Output/768656F9-F4A1-4492-9676-C6226E30D998/MyQueryResult"
(16) },
(17) "error":{}
(18) }]
(19) }
Im Folgenden finden Sie eine Erklärung dieser Liste:
(1) Das Ergebnis wird als JSON-Objekt zurückgegeben.
(2) Die Auftrags-ID auf der ersten Ebene ist der Auftragshaupt-Identifier.
(3) Der Status für diesen Auftrag ist OK. Mögliche Zustände sind: none; Dispatched (abgesendet); Running (wird ausgeführt); Canceled (abgebrochen); Crashed (abgestürzt); OK; Failed (fehlgeschlagen).
(4) Das JSON-Fehlerobjekt in unserem Beispiel ist leer. Es kann die von RaptorXML Server ausgegebene JSON-Serialisierung des Fehlers enthalten.
(5) Der Hauptauftrag (auf der ersten Ebene) generiert Unteraufträge (z.B. einen pro Argument).
(6) Das Argument für diesen Auftrag ist die XML-Instanzdatei: additional-files:///simple.xml.
(7) Unteraufträge haben ebenfalls eine Auftrags-ID, anhand welcher der Status abgefragt oder die Ergebnisse abgerufen werden können. Die Auftragsausführung ist asynchron. Aufgrund dessen können kurze Aufträge, die nach längeren Aufträgen gesendet wurden, eventuell früher fertig sein.
(8) bis (16) Das JSON output-Objekt enthält Schlüssel für die Server-generierten Ausgabedateien, die über HTTP abgerufen werden können. Einige Schlüssel (wie z.B. xquery.main_output_files) definieren URLs zu den auf dem Server gespeicherten generierten Dateien. Diese lokalen Pfade auf dem Server können auf Namen gemappt werden, die in HTTP-URLs als JSON output-mapping-Objekte verwendet werden können. Solche URLs dienen zum Abrufen von Ausgabedateien über HTTP und setzen sich folgendermaßen zusammen:
<scheme>://<host>:<port>/<output-mapping-value>
Unser Beispiel zum Abrufen der XQuery-Hauptausgabedatei würde daher folgendermaßen aussehen:
curl.exe http://localhost:8087/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1
Beachten Sie, dass der erste Wert (14) im output-mapping-Objekt (13), der Mapping-Wert ist, den wir mit dem Schlüssel an die XQuery-Ausgabe gebunden haben file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2016/Output/768656F9-F4A1-4492-9676-C6226E30D998/MyQueryResult Wir können die Datei dadurch über den Mapping-Wert referenzieren.