Ejemplo n°6: Ejecutar XQuery
En este ejemplo usamos PowerShell en Windows para ejecutar un documento XQuery en un documento XML. Ambos documentos se encuentran en la carpeta examples de su carpeta de la aplicación (RaptorXMLServer2024).
| Nota: | El uso de comillas puede ser diferente en otros shells ('bash' funciona con el ejemplo cuando se utiliza 'curl' en lugar de 'curl.exe'). |
Enviar una solicitud POST de validación de Inline XBRL usando CURL
A continuación puede ver un comando CURL de muestra para enviar una solicitud de validación de Inline XBRL.
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
Para facilitar la lectura:
(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
Entrada
A continuación se explican las distintas partes del comando CURL, en función de los complementos del listado anterior.
(1) -F 'msg={...}’ especifica un campo de formulario con el nombre 'msg'
La opción -F: (i) CURL genere una publicación de un formulario multiparte con Content-Type: multipart/form-data y (ii) este campo de formulario se añada automáticamente al encabezado de la solicitud. Usamos un objeto JSON para describir el comando que RaptorXML Server debería ejecutar.
Content-Type: multipart/form-data; boundary=--------------------...
Con el comando CURL esta opción en la solicitud HTTP se convierte 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) El comando de RaptorXML Server que se debe ejecutar en el servidor. Consulte la sección Interfaz de la línea de comandos (ILC) para obtener más información sobre los comandos que se admiten. En nuestro ejemplo, el comando utilizado para ejecutar XQuery es XQuery.
(3) Los argumentos del comando (tal y como se aceptan en la línea de comandos de RaptorXML Server) se codifican como matrices JSON. RaptorXML Server usa un esquema additional-files:// explícito para hacer referencia a recursos adicionales en el formulario dentro de un campo separado additional-files. En nuestro ejemplo hacemos referencia al documento XQuery CopyInput.xq.
| Nota: | Todos los recursos en la matriz args deben estar disponibles en el servidor o enviarse con la solicitud, similar a los puntos (6) y (7). |
(4) Las opciones del comando (tal y como se aceptan en la línea de comandos de RaptorXML Server) se codifican como matrices JSON. Si los valores predeterminados de estas opciones son como los desea (véase la sección ILC), puede omitir este paso. En nuestro ejemplo especificamos (i) el archivo XML en el que se debe ejecutar XQuery y (ii) el archivo en el que se almacenará la salida de la ejecución de XQuery.
(5) El Content-Type del campo de formulario msg se especifica después de la definición del campo de formulario y se separa de ella por un punto y coma. En nuestro ejemplo, el Content-Type de msg se indica en type=application/json.
(6 y 7) Puede especificar los archivos que contienen recursos adicionales para el comando usando el campo de formulario additional-files. En nuestro ejemplo especificamos dos recursos adicionales: (i) @CopyInput.xq seguido de un separador de punto y coma y, al final, su Content-Type, que indicamos como type=text/plain y (ii) simple.xml seguido de un separador de punto y coma y, al final, su Content-Type, que indicamos como type=application/xml.
| Nota: | Utilice @ como prefijo del nombre de archivo para indicar a CURL que use (i) el nombre de archivo como valor de la propiedad filename y (ii) el contenido del archivo como valor del formulario. Puede rellenar el campo de formulario ‘additional-files’ varias veces, una por cada recurso adicional requerido por el comando. Con el comando CURL esta opción en la solicitud HTTP se convierte en: |
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="simple.xml"
Content-Type: application/xml
<<content of simple.xml>>
| Nota: | Puede suministrar los archivos que se encuentran en otras carpetas indicando la ruta relativa delante del nombre del archivo, tal y como se indica a continuación: -F "additional-files=@Ejemplos/CopyInput.xq;type=text/plain". Sin embargo, si especifica de esta manera un archivo adicional que se encuentra en otra carpeta, tiene que hacer referencia a ese usando sólo el nombre de archivo. Por ejemplo: |
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 desea conservar una estructura de carpetas, coloque los archivos en una carpeta ZIP y haga referencia a los archivos de la forma habitual para las carpetas ZIP.
Salida
El resultado de RaptorXML Server es un objeto JSON:
{"jobid": "42B8A75E-0180-4E05-B28F-7B46C6A0C686", "result": "/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686"}
El objeto JSON contiene una clave jobid y una clave result. El valor de la clave result es la ruta de acceso del resultado. Esta ruta de acceso debe añadirse a la parte <scheme>://<host>:<port> utilizada para enviar la solicitud. En nuestro ejemplo, el resultado URL entero sería: http://localhost:8087/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686. La URL del resultado también se utiliza para solicitar el resultado de la ejecución del comando. Consulte el apartado Obtener el documento de resultados.
Obtener documentos de errores/mensajes/salida de la solicitud POST
El comando de entrada que se envía para obtener el error/mensaje/salida de la solicitud POST (véase Obtener los documentos de errores/mensajes/salida) tendría más o menos este aspecto:
curl.exe http://localhost:8087/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686
En nuestro ejemplo, este comando devuelve el siguiente objeto JSON:
{"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":{}}]}
A continuación se transcribe este objeto en líneas separadas para facilitar la lectura y con acentuación para facilitar las referencias:
(1) {
(2) "jobid":"42B8A75E-0180-4E05-B28F-7B46C6A0C686",
(3) "state":"OK",
(4) "error":{},
(5) "trabajos":[{
(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) }
A continuación explicamos el listado de arriba:
(1) El resultado se devuelve como objeto JSON.
(2) El elemento jobid en el primer nivel es el identificador de trabajo principal.
(3) El estado de este trabajo es ‘OK’. Los posibles estados de trabajo son: none (ninguno); Dispatched (distribuido); Running (en ejecución); Canceled (cancelado); Crashed (bloqueado); OK; Failed (error).
(4) En nuestro ejemplo, el objeto de error JSON está vacío. Podría que contenga la serialización JSON del error, tal y como aparece en el registro de RaptorXML Server.
(5) El trabajo principal (en el primer nivel) genera trabajos subordinados (p.ej. uno por cada argumento).
(6) Para este trabajo el argumento es el archivo XML de instancia: additional-files:///simple.xml.
(7) Los trabajos subordinados también tienen un identificador de trabajo que se puede utilizar para consultar el estado u obtener los resultados. La ejecución de trabajos es asincrónica. Por tanto, es posible que trabajos cortos enviados después de otros trabajos más largos terminen antes.
De (8) a (16) El objeto JSON de salida output contiene las claves para los archivos de salida generados por el servidor que se pueden solicitar a través de HTTP. Algunas claves (p.ej. xquery.main_output_files) especifican URLs a los archivos generados almacenados en el servidor. Estas rutas de acceso locales del servidor se pueden asignar a nombres que se pueden usar como objetos JSON output-mapping en las URLs HTTP. Estas URL sirven para obtener archivos de salida a través de HTTP y están constituidas de la siguiente manera:
<scheme>://<host>:<port>/<output-mapping-value>
Por lo tanto, en nuestro ejemplo la ruta de acceso para obtener el archivo de salida Xquery principal sería el siguiente:
curl.exe http://localhost:8087/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1
Tenga en cuenta que en el objeto output-mapping (13), el primer valor (14) es el valor de asignación que está relacionado con la salida XQuery (15) file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2016/Output/768656F9-F4A1-4492-9676-C6226E30D998/MyQueryResult. Esto nos permite usar el valor de la asignación para hacer referencia al archivo.