Exemple-6 : Exécution XQuery
Cet exemple utilise PowerShell sur Windows pour exécuter un document XQuery sur un document XML. Les deux documents sont situés dans le dossier exemples de votre dossier d’application (RaptorXMLServer2025).
| Note : | l’utilisation des guillemets peut être différente sur d’autres shells ('bash' fonctionne avec l’exemple quand il utilise 'curl’ à la place de 'curl.exe'). |
Soumettre la requête POST de validation XBRL Inline utilisant CURL
Ci-dessous, vous trouverez un exemple de la commande CURL pour soumettre une requête de validation XBRL Inline.
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
Pour une meilleure lisibilité :
(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
Entrée
La différentes parties de la commande CURL sont expliquées ci-dessous, verrouillées aux callouts dans la liste ci-dessus.
(1) -F 'msg={...}' spécifie un champ de formulaire avec le nom 'msg'
L’option -F : (i) fait que CURL génère un « multipart form post » avec Content-Type: multipart/form-data et (ii) fait que ce champ de formulaire est automatiquement ajouté à l’en-tête de la requête. Nous utilisons un objet JSON pour décrire la commande que RaptorXML Server devrait exécuter.
Content-Type: multipart/form-data; boundary=--------------------...
CURL traduit cette option en une requête HTTP 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) la commande RaptorXML Server à exécuter sur le serveur. Voir la section Command Line Interface (CLI) pour des informations sur les commandes qui peuvent être acceptées ici. Dans notre exemple, la commande pour l’exécution XQuery est XQuery.
(3) Les arguments de la commande (tels qu’acceptés par la ligne de commande RaptorXML Server) sont encodés comme array JSON. L’RaptorXML Server utilise un schéma explicite additional-files:// pour référencer des ressources supplémentaires à l’intérieur du champ de formulaire additional-files séparé. Dans notre exemple, nous référençons le document XQuery CopyInput.xq.
| Note : | toutes les ressources dans l’array args doivent être disponibles sur le serveur ou soumises avec la requête similaire à (6 and 7). |
(4) les options de la commande (tel qu’accepté par la ligne de commande RaptorXML Server) sont encodées comme objet JSON. Si les valeurs par défaut des options sont comme vous les voulez ( voir la section CLI), alors cette partie peut être omise. Dans notre exemple, nous spécifions (i) le fichier XML sur lequel XQuery doit être exécuté et (ii) le fichier sur lequel la sortie de l’exécution sera stockée.
(5) Le Content-Type du champ de formulaire msg est spécifié après la définition du champ de formulaire et est séparé de celui-ci par un point-virgule. Dans notre exemple, le Content-Type de msg est donné par : type=application/json.
(6, 7) Les fichiers qui contiennent des ressources supplémentaires pour la commande peuvent être spécifiés utilisant le champ de formulaire additional-files. Dans notre exemple, nous spécifions deux ressources supplémentaires : (i) @CopyInput.xq, suivi d’un séparateur de point-virgule et puis son Content-Type, que nous indiquons comme type=text/plain; (i) simple.xml, suivi d’un séparateur de point-virgule et puis son Content-Type, que nous indiquons comme type=application/xml.
| Note : | donnez un préfixe au nom de fichier avec @ pour instruire CURL pour (i) utiliser le nom de fichier comme la valeur de la propriété filename et (ii) le contenu du fichier comme la valeur du formulaire. Le champ de formulaire des fichiers supplémentaires peut être fourni de multiples fois, une fois pour chaque ressource supplémentaire requise par la commande. CURL traduit cette option dans la requête HTTP suivante : |
Content-Disposition: form-data; name="additional-files"; filename="CopyInput.xq"
Content-Type: text/plain
<<content of CopyInput.xq>>
Content-Disposition: form-data; name="additional-files"; filename="CopyInput.xq"
Content-Type: application/ xml
<<content of simple.xml>>
| Note : | les fichiers dans d’autres dossiers peuent être fournis en mettant le chemin relatif devant le nom de fichier comme ceci : -F "additional-files=@Examples/CopyInput.xq;type=text/plain". Toutefois, quand un fichier additionnel depuis un autre dossier est spécifié de cette manière, il doit être référencé en utilisant le nom du fichier uniquement Par exemple : |
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
Si vous souhaitez préserver une structure de dossier, mettez les fichiers dans un dossier ZIP et référencez les fichiers de manière usuelle aux dossiers ZIP.
Sortie
La sortie RaptorXML Server est un objet JSON :
{"jobid": "42B8A75E-0180-4E05-B28F-7B46C6A0C686", "result": "/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686"}
L’objet JSON contient une clé jobid et une clé result. La valeur de la clé result est le chemin au résultat. Ce chemin doit être ajouté à la partie <scheme>://<host>:<port> utilisée pour soumettre la requête. Dans notre exemple, le résultat entier de l’URL serait : http://localhost:8087/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686. Le résultat de l’URL de résultat est aussi utilisé pour demander le résultat de l’exécution de la commande. Voir Obtenir le résultat du document.
Obtenir l’erreur/le message/la sortie de la requête POST
La commande d’entrée qui est envoyée pour recevoir l’erreur/le message/la sortie de la requête POST (voir Obtenir Documents d’erreur/de message/de sortie) serait comme suit :
curl.exe http://localhost:8087/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686
Dans notre exemple, cette commande retourne l’objet JSON suivant :
{"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":{}}]}
Ceci est transcrit sur des lignes séparées dessous pour une lisibilité plus facile et avec des callouts pour un référencement plus facile :
(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) }
Ci-dessous, vous trouverez une explication de cette liste :
(1) Le résultat est retourné en tant qu'un objet JSON.
(2) Le jobid au premier niveau est l’identifiant principal de la tâche.
(3) L’état pour cette tâche est OK. Les états possibles sont : none ; Dispatched ; Running ; Canceled ; Crashed ; OK ; Failed.
(4) L’objet d’erreur JSON dans notre exemple est vide. Il peut contenir une sérialisation JSON de l’erreur comme rapporté par RaptorXML Server.
(5) La tâche principale (au premier niveau) génère les sous-tâches (par exemple, un par argument).
(6) L’argument pour cette tâche est le fichier d’instance XML : additional-files:///simple.xml.
(7) Les sous-tâches ont également un identifiant de tâche qui peut être utilisé pour interroger l’état de ou chercher les résultats. L’exécution de la tâche est asynchrone. En guise de résultat, des tâches courtes soumises après de longues tâches peuvent être terminées plus tôt.
(8) à (16) L’objet de la sortie JSON contient des clés pour les fichiers de sortie générés par le serveur qui peuvent être demandées via HTTP. Quelques clés (telles que xquery.main_output_files) spécifient les URL vers les fichiers générés stockés sur le serveur. Ces chemins server-local peuvent être mappés vers les noms, qui peuvent être utilisés comme objets JSON output-mapping dans les URL HTTP. De tels URL sont utilisés pour récupérer des fichiers de sortie via HTTP et sont constitués comme suit :
<scheme>://<host>:<port>/<output-mapping-value>
Notre exemple pour récupérer le fichier de sortie principal XQuery aurait donc l’air de ceci :
curl.exe http://localhost:8087/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1
Notez que dans l’objet output-mapping (13), la première valeur (14) est la valeur de mappage que nous avons saisi dans la sortie XQuery (15), file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2016/Output/768656F9-F4A1-4492-9676-C6226E30D998/MyQueryResult. Ceci nous permet d’utiliser la valeur de mappage pour référencer le fichier.