Iniciar trabajos con POST
Este apartado contiene las siguientes secciones:
•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 | Content-Type | Cuerpo |
POST | http://localhost:8087/v1/queue/ | application/json | JSON |
Debe tener en cuenta 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 API HTTP actual. Los números de versión anteriores indican versiones antiguas de la API 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 Línea de comandos.
Sintaxis JSON para solicitudes HTTP POST
{ "command": "Nombre-Comando", "options": {"opt1": "opt1-value", "opt2": "opt2-value"}, "args" : ["file:///c:/filename1", "file:///c:/filename2"] }
•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 Línea de comandos.
•Las claves command y args son obligatorias. La clave 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 deben llevar comillas. Como resultado: {"error-limit": "unlimited"} y {"error-limit": 1}.
•Tenga en cuenta que se recomienda utilizar los URI de archivo, en lugar de las rutas de archivo, y que estos utilizan barras inclinadas. 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/Test.xslt"
],
"options": {
"input": "file:///C:/Work/Test.xml",
"xslt-version": "1",
"param": {
"key": "myTestParam",
"value": "SomeParamValue"
},
"output": "file:///C:/temp/out2.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 matriz JSON.
{
"command": "xsi",
"args": [
"file:///C:/Work/Test.xml"
],
"options": {
"xsd" : ["file:///C:/Work/File1.xsd", "file:///C:/Work/File2.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 límite. Por ejemplo:
Content-Type: multipart/form-data; boundary=---PartBoundary
El límite se usa para 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 límite especificada en el encabezado (ver más arriba):
•Partes form-data obligatorias: msg, que especifica la acción de procesamiento solicitada, y args, que contiene los archivos que se van a cargar como argumentos del comando especificado en la parte form-data msg. Más abajo puede verse un ejemplo.
•Parte form-data opcional: Una parte form-data denominada additional-files, que contiene archivos a los que se hace referencia desde archivos en las partes form-data msg o 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 un único directorio virtual.
Consulte Ejemplo n.º 1 (con acentuación): validar XML para ver una explicación detallada del código y Ejemplo n.º 2: usar un catálogo para encontrar el esquema.
Pruebas con CURLPuede utilizar una aplicación de transferencia de datos de terceros, 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 los límites parciales de las solicitudes. Esto evita tener que crear a mano los límites 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:///mybigarchive.zip%7Czip/biginstance.xml
Nota: La parte |zip/ debe codificarse en URI como %7Czip/ para cumplir con la especificación RFC de URI, ya que el símbolo de barra vertical | no está permitido directamente. 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": {...}}
Consulte Ejemplo n.º 3: usar archivos ZIP para ver un ejemplo de código.