Beispiel-5: Validieren von Inline XBRL
In diesem Beispiel wird unter Windows mittels PowerShell anhand der US-GAAP-Dateien von https://www.sec.gov/Archives/edgar/data/815097/000081509723000012/0000815097-23-000012-xbrl.zip eine Inline XBRL-Validierung durchgeführt.
Voraussetzungen
•Laden Sie 0000815097-23-000012-xbrl.zip (vollständige URL siehe oben) herunter.
•Installieren Sie die US-GAAP-2023-Taxonomie auf dem Server.
| 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\": "ixbrl", "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"], "options": {"verbose": true}};type=application/json' -F "additional-files=@0000815097-23-000012-xbrl.zip;type=application/octet-stream" http://localhost:8087/v1/queue
Zur einfacheren Lesbarkeit:
(1) -F 'msg={
(2) "command": "ixbrl",
(3) "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],
(4) "options": {"verbose": true}
(5) };type=application/json'
(6) -F "additional-files=@0000815097-23-000012-xbrl.zip;type=application/octet-stream"
(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+XBRL 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": "ixbrl", "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"], "options": {"verbose": true}}
(2) Der auf dem Server auszuführende RaptorXML+XBRL Server-Befehl. Informationen zu Befehlen, die hier verwendet werden können, finden Sie unter Befehlszeilenschnittstelle (CLI). In unserem Beispiel lautet der Befehl für die Inline XBRL-Validierung valinlinexbrl (ixbrl). Es kann entweder die lange Form valinlinexbrl oder die Kurzform ixbrl verwendet werden.
(3) Die Argumente des Befehls (die von der RaptorXML+XBRL Server-Befehlszeile akzeptiert werden) sind als JSON-Array kodiert. RaptorXML+XBRL 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 Inline XBRL-Dokument ccl-20221130.htm in der ZIP-Datei 0000815097-23-000012-xbrl.zip.
| Anmerkung: | Das Zeichen | in |zip, welches in Altova-Produkten zum Referenzieren von Dateien in einem .zip-Archiv verwendet wird, muss in der URL als %7C kodiert werden. Die 0000815097-23-000012-xbrl.zip-Datei selbst wird in (6) als Inhalt eines anderen Formularfelds bereitgestellt. Alle Ressourcen im args-Array müssen auf dem Server verfügbar sein oder mit einem Request ähnlich dem in (6) bereitgestellt werden. |
(4) Die Optionen des Befehls (die von der RaptorXML+XBRL 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 möchten wir ein ausführliches Ausgabeprotokoll erhalten. Wir setzen dazu die Option verbose auf true (der Standardwert der Option ist false).
(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 die Datei @0000815097-23-000012-xbrl.zip als zusätzliche Ressource, gefolgt von einem Semikolon als Trennzeichen und anschließend dem Content-Type, den wir als type=application/octet-stream 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: application/octet-stream
<<content of 0000815097-23-000012-xbrl.zip>>
Ausgabe
Von RaptorXML+XBRL Server wird ein JSON-Objekt ausgegeben:
{"jobid": "4B7CFC80-13B3-4558-B8CC-D312EA00BA74", "result": "/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74"}
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/4B7CFC80-13B3-4558-B8CC-D312EA00BA74. 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/4B7CFC80-13B3-4558-B8CC-D312EA00BA74
In unserem Beispiel gibt dieser Befehl das folgende JSON-Objekt zurück:
{"jobid":"4B7CFC80-13B3-4558-B8CC-D312EA00BA74","state":"OK","error":{},"jobs":[{"file":["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],"jobid":"94968597-3234-4D0A-A3FF-BCDE50A0E4E6","output":{"verbose-log":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log"],"xbrl-output-file":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl"]},"state":"OK","output-mapping":{"file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log":"verbose.log","file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl":"output.xbrl"},"error":{}}]}
Zur besseren Lesbarkeit wurde dies unten in separaten Zeilen formatiert und mit nummerierten Beschreibungen versehen:
%1 :
(2) "jobid":"4B7CFC80-13B3-4558-B8CC-D312EA00BA74",
(3) "state":"OK",
(4) "error":{},
(5) "jobs":[{
(6) "file":["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],
(7) "jobid":"94968597-3234-4D0A-A3FF-BCDE50A0E4E6",
(8) "output":{
(9) "verbose-log":[file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log"],
(10) "xbrl-output-file":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl"]},
(11) "state":"OK",
(12) "output-mapping":{
(13) "file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log":"verbose.log",
(14) "file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl":"output.xbrl"
(15) },
(16) "error":{}
(17) }]
(18) }
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+XBRL 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 Inline XBRL-Instanz in der ZIP-Datei: additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm.
(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 (15) 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. verbose-log) definieren URLs zu 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>/v1/results/<jobid>/output/<output-mapping-value>
Unser Beispiel zum Abrufen des ausführlichen Protokolls würde daher folgendermaßen aussehen:
curl.exe http://localhost:8087/v1/results/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output/verbose.log
Beachten Sie, dass der erste Wert (13) im output-mapping-Objekt (12) das ausführliche Protokoll file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log ist und wir diesen auf den Wert verbose.log gemappt haben. Wir können die Datei dadurch über den Wert verbose.log referenzieren.