Abrufen des Ergebnisdokuments
In diesem Abschnitt werden folgende Schritte beschrieben:
•Abrufen des Ergebnisdokuments
•Ergebnisdokument, das URIs von Fehlerdokumenten enthält
•Ergebnisdokument, das URIs von Ausgabedokumenten enthält
•Ergebnisdokument, das keine URI enthält
•Aufruf von im Ergebnisdokument aufgelisteten Fehler- und Ausgabedokumenten
Die Ergebnisdokument-URI
Bei jeder Erstellung eines Auftrags wird ein Ergebnisdokument erstellt, unabhängig davon, ob das Ergebnis eines Auftrags (z.B. einer Validierung) positiv (Dokument ist gültig) oder negativ (Dokument ungültig) ist. In beiden Fällen wird eine 201 Created Meldung zurückgegeben. Diese Meldung ist im JSON-Format und enthält eine relative URI des Ergebnisdokuments. Das JSON-Fragment sieht in etwa folgendermaßen aus:
{
"result": "/v1/results/E6C4262D-8ADB-49CB-8693-990DF79EABEB",
"jobid": "E6C4262D-8ADB-49CB-8693-990DF79EABEB"
}
Das Objekt result enthält die relative URI des Ergebnisdokuments. Die URI ist relativ zur Serveradresse. Wenn die Serveradresse z.B. http://localhost:8087/ (die Adresse in der Anfangskonfiguration) ist, so lautet die erweiterte URI des im Codefragment oben angegebenen Ergebnisdokuments:
http://localhost:8087/v1/results/E6C4262D-8ADB-49CB-8693-990DF79EABEB
| Anmerkung: | 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 jedoch weiterhin aus Gründen der Rückwärtskompatibilität unterstützt werden. |
Abrufen des Ergebnisdokuments
Um das Ergebnisdokument abzurufen, senden Sie die erweiterte URI des Dokuments (siehe oben) in einem HTTP GET Request. Daraufhin wird das Ergebnisdokument zurückgegeben. Es könnte eine der unten beschriebenen allgemeinen Arten sein.
| Anmerkung: | Wenn ein Auftrag erfolgreich in die Server-Warteschlange gestellt wurde, wird die URI des Ergebnisdokuments zurückgegeben. Wenn der Client das Ergebnis anfordert, bevor der Auftrag gestartet wurde (weil er sich noch in der Warteschlange befindet) wird die Meldung "status": "Dispatched" zurückgegeben. Wenn der Auftrag gestartet, aber noch nicht fertig gestellt wurde (weil es sich z.B. um einen großen Auftrag handelt), wird die Meldung "status": "Running" zurückgegeben. In beiden Fällen sollte der Client einige Zeit warten, bevor er das Ergebnisdokument erneut anfordert. |
| Anmerkung: | In den Beispieldokumenten unten wird immer davon ausgegangen, dass der Zugriff des Client eingeschränkt ist. Daher wird angenommen, dass Fehlerdokumente, Meldungsdokumente und Ausgabedokumente im entsprechenden Auftragsverzeichnis auf dem Server gespeichert werden. Die URIs für diese Dokumente im Ergebnisdokument sind daher alle relative URIs. Keine davon ist eine Datei-URI (wie dies bei unbeschränktem Client-Zugriff der Fall wäre). Nähere Informationen zu diesen URIs finden Sie im Abschnitt Abrufen von Fehler-/Ausgabedokumenten. |
Ergebnisdokument, das URIs von Fehlerdokumenten enthält
Wenn der angeforderte Auftrag mit dem Status Fehlgeschlagen beendet wurde, hat der Auftrag ein negatives Ergebnis zurückgegeben. So wurde z.B. bei einem Validierungsauftrag das Ergebnis: "Dokument ungültig" zurückgegeben. Die bei der Ausführung des Auftrags ausgegebenen Fehler werden in Fehlerprotokollen gespeichert, die in drei Formaten erstellt werden: (i) Text, (ii) long-XML (detailliertes Fehlerprotokoll) und (iii) short-XML (weniger ausführliches Fehlerprotokoll). Siehe JSON-Codefragment unten.
{
"jobid": "6B4EE31B-FAC9-4834-B50A-582FABF47B58",
"state": "Failed",
"error":
{
"text": "/v1/results/6B4EE31B-FAC9-4834-B50A-582FABF47B58/error/error.txt",
"longxml": "/v1/results/6B4EE31B-FAC9-4834-B50A-582FABF47B58/error/long.xml",
"shortxml": "/v1/results/6B4EE31B-FAC9-4834-B50A-582FABF47B58/error/short.xml"
},
"jobs":
[
{
"file": "file:///c:/Test/ExpReport.xml",
"jobid": "20008201-219F-4790-BB59-C091C276FED2",
"output":
{
},
"state": "Failed",
"error":
{
"text": "/v1/results/20008201-219F-4790-BB59-C091C276FED2/error/error.txt",
"longxml": "/v1/results/20008201-219F-4790-BB59-C091C276FED2/error/long.xml",
"shortxml": "/v1/results/20008201-219F-4790-BB59-C091C276FED2/error/short.xml"
}
}
]
}
Beachten Sie bitte die folgenden Punkte:
•Aufträge haben Unteraufträge.
•Fehler, die auf Unterauftragsebene entstehen, setzen sich bis zum Auftrag der obersten Ebene fort. Der Status des Auftrags der obersten Ebene ist nur dann OK, wenn alle seine Unteraufträge ebenfalls den Status OK haben.
•Jeder Auftrag oder Unterauftrag hat sein eigenes Fehlerprotokoll.
•Fehlerprotokolle enthalten Warnungsprotokolle, d.h. auch wenn ein Auftrag mit dem Status OK beendet wird, kann er URIs von Fehlerdateien enthalten.
•Die URIs von Fehlerdateien sind relativ zur Serveradresse (siehe oben).
Ergebnisdokument, das URIs von Ausgabedokumenten enthält
Wenn der angeforderte Auftrag mit dem Status OK beendet wurde, wurde vom Auftrag ein positives Ergebnis zurückgegeben. So wurde z.B. bei einem Validierungsauftrag das Ergebnis: "Dokument gültig" zurückgegeben. Wenn beim Auftrag ein Ausgabedokument - z.B. das Ergebnis einer XSLT-Transformation - zurückgegeben wurde, so wird die URI des Ausgabedokuments zurückgegeben. Siehe JSON-Codefragment unten.
{
"jobid": "5E47A3E9-D229-42F9-83B4-CC11F8366466",
"state": "OK",
"error":
{
},
"jobs":
[
{
"file": "file:///c:/Test/SimpleExample.xml",
"jobid": "D34B5684-C6FF-4A7A-BF35-EBB9A8A8C2C8",
"output":
{
"xslt-output-file":
[
"/v1/results/D34B5684-C6FF-4A7A-BF35-EBB9A8A8C2C8/output/1"
]
},
"state": "OK",
"output-mapping":
{
"/v1/results/D34B5684-C6FF-4A7A-BF35-EBB9A8A8C2C8/output/1": "file:///c:/temp/test.html"
},
"error":
{
}
}
]
}
Beachten Sie die folgenden Punkte:
•Die Ausgabedatei wird im Ordner output des Auftrags erstellt. Sie können zum Aufrufen der Datei die relative URI verwenden.
•Die URIs der Ausgabedateien sind relativ zur Serveradresse (siehe oben).
•Das Datenelement output-mapping mappt das Ausgabedokument im Auftragsverzeichnis auf dem Server auf den durch den Client in der Auftragsanforderung angegebenen Ordner. Beachten Sie, dass nur Ausgabedokumente, die vom Client in der Auftragsanforderung definiert sind, ein Mapping haben; Dateien im Zusammenhang mit dem Auftrag, die vom Server generiert werden (wie z.B. Fehlerdateien), haben kein Mapping.
•Alternativ dazu können alle generierten Ergebnisdokumente für einen bestimmten Auftrag über die URL "/v1/results/JOBID/output/zip" als ZIP-Archiv aufgerufen werden. Diese Funktion steht im uneingeschränkten Dateisystemmodus nicht zur Verfügung. Beachten Sie bitte, dass das ZIP-Archiv beschädigte Dateinamen enthält, die mit Hilfe des Objekts output-mapping wieder den tatsächlichen Namen zugeordnet werden müssen.
Ergebnisdokument, das keine URI enthält
Wenn der angeforderte Auftrag mit dem Status OK beendet wurde, hat der Auftrag ein positives Ergebnis zurückgegeben. So wurde z.B. bei einem Validierungsauftrag das Ergebnis: "Dokument gültig" zurückgegeben. Bei einigen Aufträgen - z.B. bei der Validierung oder der Wohlgeformtheitsprüfung - wird kein Ausgabedokument erzeugt. Wenn ein Auftrag dieser Art mit dem Status OK beendet wird, hat das Ergebnisdokument weder die URI eines Ausgabedokuments noch die URI eines Fehlerprotokolls. Siehe JSON-Codefragment unten.
{
"jobid": "3FC8B90E-A2E5-427B-B9E9-27CB7BB6B405",
"state": "OK",
"error":
{
},
"jobs":
[
{
"file": "file:///c:/Test/SimpleExample.xml",
"jobid": "532F14A9-F9F8-4FED-BCDA-16A17A848FEA",
"output":
{
},
"state": "OK",
"error":
{
}
}
]
}
Beachten Sie die folgenden Punkte:
•Sowohl das Ausgabedokument als auch das Fehlerprotokoll des Unterauftrags im Codefragment oben sind leer.
•Ein Auftrag, der mit dem Status OK beendet wurde, kann trotzdem Warnungen oder andere Meldungen enthalten, die in Fehlerdateien protokolliert sind. In diesem Fall enthält das Ergebnisdokument URIs von Fehlerdateien, obwohl der Auftrag mit dem Status OK beendet wurde.
Aufrufen von im Ergebnisdokument aufgelisteten Fehler- und Ausgabedokumenten
Fehler- und Ergebnisdokumente können mit HTTP GET Requests aufgerufen werden. Eine Beschreibung dazu finden Sie im nächsten Abschnitt Abrufen von Fehler-/Meldungs-/Ausgabedokumenten.