Obtener el documento de resultados
Temas de este apartado:
•El URI del documento de resultados
•Recuperar el documento de resultados
•Documento de resultados con los URI de los documentos de errores
•Documento de resultados con los URI de los documentos de salida
•Documento de resultados sin URI
•Acceder a los documentos de salida y de errores enumerados en el documento de resultados
El URI del documento de resultados
Cada vez que se crea un trabajo se genera un documento de resultados, independientemente de si el resultado del trabajo (p. ej. un trabajo de validación) es positivo (el documento es válido) o negativo (el documento no es válido). En ambos casos se devuelve un mensaje 201 Creado. Este mensaje está en formato JSON y contiene el URI relativo del documento de resultados. Por ejemplo:
{
"result": "/v1/results/E6C4262D-8ADB-49CB-8693-990DF79EABEB",
"jobid": "E6C4262D-8ADB-49CB-8693-990DF79EABEB"
}
El objeto result contiene el URI relativo del documento de resultados. El URI es relativo a la dirección del servidor. Por ejemplo, si la dirección del servidor es http://localhost:8087/ (la dirección según la configuración inicial), el URI ampliado del documento de resultados anterior sería:
http://localhost:8087/v1/results/E6C4262D-8ADB-49CB-8693-990DF79EABEB
| Nota: | el número de versión /vN es el que devuelve el servidor (no necesariamente el de 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 antiguos indican versiones previas de la interfaz HTTP, que se admiten para garantizar la compatibilidad con versiones previas. |
Recuperar el documento de resultados
Para obtener el documento de resultados puede enviar el URI ampliado del documento (ver más arriba) en una solicitud HTTP GET. Se devuelve el documento de resultados, que puede ser de tres tipos (ver más abajo).
| Nota: | si el trabajo se coloca en la cola del servidor, este devuelve el URI del documento de resultados. Si el cliente solicita el resultado antes de que comience el trabajo (si todavía está en la cola), se devuelve el mensaje "estado": "Distribuido". Si el trabajo se inició pero no terminó todavía (porque es un trabajo grande, por ejemplo), se devuelve el mensaje "estado": "En ejecución". En ambos casos el cliente debe esperar un poco para volver a solicitar el documento de resultados. |
| Nota: | en los ejemplos que aparecen a continuación se entiende que hay acceso de cliente restringido. Es decir, se entiende que los documentos de errores, mensajes y de salida se guardan en el directorio correspondiente del servidor. Los URI de estos documentos en el documento de resultados son, por tanto, URI relativos. Ninguno de ellos es un URI de archivo (como el que se generaría con acceso de cliente no restringido). Para más información consulte el siguiente apartado de esta sección. |
Documento de resultados con los URI de los documentos de errores
Si el trabajo solicitado termina con el estado Failed, el trabajo devuelve un resultado negativo. Por ejemplo, un trabajo de validación devuelve un resultado de documento no válido. Los errores detectados durante la ejecución del trabajo se almacenan en registros de errores, creados en tres formatos de archivo: (i) texto, (ii) XML largo (registro detallado) y (iii) XML corto (registro menos detallado).
{
"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"
}
}
]
}
Es importante destacar que:
•Los trabajos tienen trabajos subordinados.
•Los errores de los trabajos subordinados se propagan al trabajo de nivel superior. Es decir, el estado del trabajo solamente puede ser OK si el de los trabajos subordinados también lo es.
•Cada trabajo y trabajo subordinado tiene su registro de errores.
•Los registros de errores incluyen advertencias. Es decir, incluso si el trabajo tiene el estado OK, puede haber archivos de errores.
•Los URI de los archivos de errores son relativos a la dirección del servidor (ver más arriba).
Documento de resultados con los URI de los documentos de salida
Si el trabajo solicitado termina con el estado OK, el trabajo devuelve un resultado positivo. Por ejemplo, un trabajo de validación devuelve un resultado de documento válido. Si el trabajo generó un documento de salida (por ejemplo, como resultado de una transformación XSLT), se devuelve el URI del documento de salida.
{
"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":
{
}
}
]
}
Es importante destacar que:
•El archivo de salida se crea en la carpeta output del trabajo. Puede usar su URI relativo para acceder al archivo.
•Los URI de los archivos de salida son relativos a la dirección del servidor (ver más arriba).
•El elemento output-mapping asigna el documento de salida del directorio del trabajo del servidor a la ubicación de archivo especificada por el cliente en la solicitud. Recuerde que solo tienen una asignación los documentos de salida especificados por el cliente en la solicitud. Los archivos relacionados con el trabajo generados por el servidor (como los archivos de errores) no tienen ninguna asignación.
•Otra opción es recuperar todos los documentos de resultados generados para un trabajo específico en un archivo ZIP por medio de la URL "/v1/results/JOBID/output/zip". Esta característica no está disponible en el modo unrestricted filesystem. Recuerde que el archivo ZIP incluirá nombres de archivo alterados, que deberán asignarse a los nombres reales con ayuda del objeto output-mapping.
Documento de resultados sin URI
Si el trabajo solicitado terminó con el estado OK, significa que el trabajo devolvió un resultado positivo. Por ejemplo, un trabajo de validación devuelve un resultado de documento válido. Algunos trabajos, como los de validación o de comprobación de formato, no generan documentos de salida. Si un trabajo de este tipo termina con el estado OK, el documento de resultados generado no tendrá ni el URI de documento de salida ni el URI del registro de errores.
{
"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":
{
}
}
]
}
Observe que:
•Tanto los componentes de salida y de error del trabajo subordinado están vacíos en el ejemplo anterior.
•Un trabajo puede terminar con un estado OK, pero con advertencias y otro tipo de mensajes, que se registran en los archivos de errores. En este caso, el documento de resultados incluirá el URI de los archivos de errores, aunque el trabajo terminara con el estado OK.
Acceder a los documentos de errores y de salida enumerados en el documento de resultados
Puede acceder a los documentos de errores y de salida con solicitudes HTTP GET. Para más información consulte el siguiente apartado de esta sección.