/app/output, por lo que debe montar un volumen allí; de lo contrario, desaparecerán junto con el contenedor. Consulte Configuration.
Cómo funciona un análisis
El análisis es asíncrono: se envía un documento y se recibe de inmediato un ID de trabajo, se consulta el trabajo hasta que finalice y luego se descarga el resultado. El reconocimiento se realiza en un único worker dentro del contenedor, un documento a la vez, por lo que la conexión HTTP nunca permanece abierta mientras dura el reconocimiento.1
Enviar
POST /parse con el documento y un tipo de salida. La respuesta es 202 Accepted con el ID del trabajo.2
Consultar
GET /jobs/{id} hasta que status sea successful, failed o cancelled.3
Descargar
GET /jobs/{file}, donde file es la ruta indicada en la respuesta de estado. El resultado se devuelve como archivo adjunto.Endpoints
Toda respuesta de error es un JSON con un campoerror que describe el problema. Algunas incluyen además un campo code o status, como se indica a continuación.
POST /parse
Envíe un documento. Envíelo comomultipart/form-data con un campo file que contenga el documento y un campo outputType con el valor doclang, json o txt. Consulte Formatos de salida.
Un envío correcto devuelve 202 Accepted, un encabezado Location que apunta al trabajo y un cuerpo con el ID del trabajo y el nombre de archivo registrado por FineParser.
La comprobación de licencia se realiza antes de leer nada de la carga, de modo que un contenedor sin licencia rechaza la solicitud sin consumir ancho de banda ni disco.
GET /jobs/
Informa el estado de un trabajo.file es la ruta del resultado con el formato {jobId}/{name}. Anteponga /jobs/ para obtener la URL de descarga. El nombre corresponde al del archivo cargado con el tipo de salida añadido al final, de modo que document.pdf analizado a DocLang pasa a ser document.pdf.doclang. El campo no aparece hasta que el trabajo se completa correctamente, y vuelve a desaparecer si el resultado se elimina del disco.
Un trabajo puede fallar por motivos de licencia después de haber sido aceptado, ya que el número de páginas solo se conoce una vez cargado el documento. En ese caso, status es failed y error así lo indica. No se cobra nada por un trabajo fallido.
Devuelve 404 si no existe dicho trabajo.
GET /jobs//
Descarga un resultado. Use el valorfile de la respuesta de estado como ruta.
El resultado se devuelve como flujo con un Content-Type acorde al formato de salida y un encabezado Content-Disposition de tipo attachment que indica el nombre del archivo, de modo que curl -OJ lo guarda con el nombre correcto. No se admiten solicitudes por rangos.
DELETE /jobs/
Elimina un trabajo y su resultado del disco.GET /healthz
Indica si el contenedor tiene licencia y está listo para aceptar documentos. Úselo como sonda de disponibilidad (readiness probe) en Kubernetes o en su orquestador. La imagen del contenedor también lo ejecuta como su propioHEALTHCHECK de Docker.
200. Uno que no está listo devuelve 503 con ready: false, un code que explica el motivo y, por lo general, un mensaje detail. La disponibilidad refleja únicamente el estado de la License. La telemetría se informa junto con ella, pero nunca la afecta. Consulte Confirmar la License.
Resultados en disco
Cada resultado se escribe en/app/output como {jobId}/{name}, junto a una pequeña base de datos de trabajos. El layout es estable, por lo que también puede recopilar los resultados directamente desde el volumen montado en lugar de descargarlos por HTTP.
De forma predeterminada, un resultado permanece hasta que ejecute DELETE sobre el trabajo o lo elimine usted mismo del volumen. Nada caduca por antigüedad. Si prefiere que FineParser se encargue de la limpieza, inicie el contenedor con DELETE_ON_DOWNLOAD=true: cada resultado se eliminará, junto con su record de trabajo, en cuanto se haya descargado por completo. A partir de ese momento, tanto el estado como la descarga devuelven 404. Una descarga interrumpida deja el resultado disponible para un nuevo intento.
Los archivos cargados se conservan en un directorio temporal aparte y se eliminan en cuanto finaliza el reconocimiento, con independencia del resultado.
Reinicios y apagado
Los trabajos se registran en la base de datos de trabajos del volumen de salida, por lo que sobreviven a un reinicio mientras el volumen también lo haga. Los trabajos pendientes se retoman. Un trabajo que estaba en curso cuando el proceso se interrumpió se marca comofailed, porque el proceso no puede saber qué parte del resultado llegó a escribirse.
En una detención limpia, FineParser deja de aceptar solicitudes, permite que finalicen las que están en curso y finaliza sin esperar al documento que se está reconociendo. El reconocimiento no se puede interrumpir, y esperarlo podría prolongar el apagado durante varios minutos. Ese trabajo se marca como cancelled y su resultado parcial se elimina. Vuelva a enviarlo si todavía lo necesita.
Asigne al contenedor un tiempo de espera de detención de 60 segundos, mediante --stop-timeout 60 en Docker o terminationGracePeriodSeconds: 60 en Kubernetes. El valor predeterminado de Docker, de 10 segundos, corta el vaciado antes de tiempo y hace que se pierda la telemetría de uso de todo lo ocurrido desde la última exportación.
Solo un contenedor puede usar un mismo directorio de salida a la vez. La base de datos de trabajos permanece bloqueada mientras está abierta, por lo que un segundo contenedor en el mismo volumen no arrancará. Dos contenedores requieren dos volúmenes.