Iniciar trabajos con POST
Temas de este apartado:
•Sintaxis JSON para solicitudes POST
•Cargar archivos con la solicitud POST
Enviar la solicitud
Los trabajos de RaptorXML+XBRL Server se inician con el método HTTP POST.
Método HTTP | URI | Campo de encabezado Content-Type | Cuerpo |
POST | http://localhost:8087/v1/queue/ | application/json | JSON |
Observe que:
•El URI de la tabla tiene una dirección de servidor que utiliza las opciones de la configuración inicial.
•El URI tiene una ruta de acceso /v1/queue/, que debe estar presente en el URI. Puede entenderse como una carpeta abstracta en memoria y en ella se coloca el trabajo.
•El número de versión /vN es el que devuelve el servidor (no necesariamente el que aparece en esta documentación). El número que devuelve el servidor es el número de versión de la interfaz HTTP actual. Los números de versión anteriores indican versiones antiguas de la interfaz HTTP y se admiten para garantizar la compatibilidad con versiones anteriores.
•El encabezado debe incluir el campo: Content-Type: application/json. Sin embargo, si quiere cargar archivos dentro del cuerpo de la solicitud POST, el encabezado del mensaje debe tener el tipo de contenido multipart/form-data (es decir, Content-Type: multipart/form-data). Para más información consulte el apartado Cargar archivos con la solicitud POST.
•El cuerpo de la solicitud debe estar en formato JSON.
•Los archivos que desea procesar deben estar en el servidor. Por tanto, debe copiar los archivos al servidor antes de realizar la solicitud o cargarlos junto con la solicitud POST. En este último caso, el encabezado del mensaje debe tener el tipo de contenido multipart/form-data. Para más información consulte el apartado Cargar archivos con la solicitud POST.
Esta sería la solicitud en formato JSON para comprobar si un archivo XML tiene un formato correcto:
{
"command": "wfxml", "args": [ "file:///c:/Test/Report.xml" ]
}
Los comandos, sus argumentos y sus opciones se documentan en la sección Interfaz de la línea de comandos.
Sintaxis JSON para solicitudes HTTP POST
{ "command": "Nombre-Comando", "options": {"opción1": "opción1-valor", "opción2": "opción2-valor"}, "args" : ["file:///c:/nombreArchivo1", "file:///c:/nombreArchivo2"] }
•El texto de color negro es obligatorio y debe incluirse. Esto incluye todas las llaves, comillas, dos puntos, comas y corchetes. Los espacios en blanco se pueden normalizar. •El texto de color azul en cursiva son marcadores de posición para nombres de comandos, opciones, valores de opciones y valores de argumentos. Para más información consulte la sección Interfaz de la línea de comandos.
•Las claves command y args son obligatorias. La opción options es opcional. Algunas claves options tienen valores predeterminados. Por tanto, de todas estas opciones, solamente debe especificar aquellas cuyos valores predeterminados desee cambiar.
•Todas las cadenas de texto deben ir entre comillas dobles. Los valores booleanos y los números no necesitan ir entre comillas. El uso correcto sería {"error-limit": "unlimited"} y {"error-limit": 1}.
•Es recomendable usar los URI de archivo y no sus rutas de acceso. Recuerde que los URI usan barras diagonales, mientras que las rutas de acceso usan barras diagonales inversas. Además, en Windows es necesario añadir caracteres de escape a las barras diagonales inversas de las rutas de acceso (es decir, "c:\\dir\\nombreArchivo"). Por último, recuerde que los URI y las rutas de acceso son cadenas y, por tanto, deben ir entre comillas. |
A continuación puede ver un ejemplo con opciones. Observe que algunas opciones (como input o xslt-version) toman un valor directo, mientras que otros (como param) toman un par clave-valor y, por tanto, necesitan otra sintaxis.
{
"command": "xslt",
"args": [
"file:///C:/Work/Prueba.xslt"
],
"options": {
"input": "file:///C:/Work/Prueba.xml",
"xslt-version": 1,
"param": {
"key": "miPruebaParam",
"value": "ValorDeParám"
},
"output": "file:///C:/temp/salida2.xml"
}
}
El ejemplo que aparece a continuación muestra otro tipo de opción más: una matriz de valores (como en la opción xsd del ejemplo). En casos así, debe usar la sintaxis de una matrix JSON.
{
"command": "xsi",
"args": [
"file:///C:/Work/Prueba.xml"
],
"options": {
"xsd" : ["file:///C:/Work/File1.xsd", "file:///C:/Work/Archivo2.xsd"]
}
}
Cargar archivos con la solicitud POST
Puede cargar los archivos que deben procesarse dentro del cuerpo de la solicitud POST. En este caso, la solicitud POST debe crearse como se muestra a continuación.
Encabezado de la solicitud
En el encabezado de la solicitud, defina Content-Type: multipart/form-data y especifique una cadena de texto cualquiera como frontera. Por ejemplo:
Content-Type: multipart/form-data; boundary=---FronteraParcial
El objetivo de la frontera es delimitar las diferentes partes form-data del cuerpo de la solicitud (ver más abajo).
Cuerpo de la solicitud: parte del mensaje
El cuerpo de la solicitud está formado por varias partes form-data, separadas por la cadena de frontera especificada en el encabezado (ver más arriba):
•Partes form-data obligatorias: la parte msg, que especifica la acción de procesamiento solicitada, y la parte args, que contiene los archivos que deben cargarse como argumentos del comando especificado en la parte msg. (Ver ejemplo que aparece más abajo).
•Parte form-data opcional: la parte additional-files contiene los archivos a los que se hace referencia desde las partes form-data obligatorias msg y args. Además, las partes form-data con nombre de opción de comando también pueden incluir archivos para cargar.
Nota: todos los archivos cargados se crean en el mismo directorio virtual.
Consulte el Ejemplo nº1 (con llamadas): validar XML para ver un ejemplo de código y el Ejemplo nº2: usar un catálogo para buscar el esquema.
Pruebas con CURLPuede usar aplicaciones externas de transferencia de datos como CURL (http://curl.haxx.se/) para probar la solicitud POST. CURL ofrece una opción de seguimiento muy práctica que genera y enumera las fronteras parciales de las solicitudes. Esto evita tener que crear a mano las fronteras parciales. Para más información consulte el apartado Pruebas con CURL.
|
Cargar archivos ZIP
También puede cargar archivos ZIP y hacer referencia a los ficheros del archivo ZIP con el esquema additional-files. Por ejemplo:
additional-files:///migranarchivo.zip%7Czip/instanciagrande.xml
| Nota: | en la parte |zip/ el URI tiene que estar entre caracteres de escape (%7Czip/) para ajustarse al RFC del URI porque el símbolo | no está permitido. El uso de patrones glob (* y ?) también está permitido. Por tanto, para validar todos los archivos XML del archivo ZIP puede usar algo así: {"command": "xsi", "args": ["additional-files:///migranarchivo.zip%7Czip/*.xml"], "options": {...}} |
Para ver otro ejemplo de código consulte el Ejemplo nº3: usar archivos ZIP.