/app/output ; montez-y un volume, sinon ils disparaîtront avec le conteneur. Voir Configuration.
Fonctionnement d’une analyse
L’analyse est asynchrone : vous soumettez un document et recevez immédiatement un ID de tâche, vous interrogez la tâche jusqu’à ce qu’elle soit terminée, puis vous téléchargez le résultat. La reconnaissance s’effectue sur un seul worker au sein du conteneur, un document à la fois : la connexion HTTP n’est donc jamais maintenue ouverte pendant toute la durée d’une reconnaissance.1
Soumettre
POST /parse avec le document et un type de sortie. La réponse est 202 Accepted, accompagnée de l’ID de la tâche.2
Interroger
GET /jobs/{id} jusqu’à ce que status soit successful, failed ou cancelled.3
Télécharger
GET /jobs/{file}, où file est le chemin indiqué par la réponse de statut. Le résultat est renvoyé en flux sous forme de pièce jointe.Points de terminaison
Chaque réponse d’erreur est au format JSON et comporte un champerror décrivant le problème. Certaines contiennent également un champ code ou status, comme indiqué ci-dessous.
POST /parse
Soumettez un document. Envoyez-le enmultipart/form-data avec un champ file contenant le document et un champ outputType défini sur doclang, json ou txt. Voir Formats de sortie.
Une soumission réussie renvoie 202 Accepted, un en-tête Location pointant vers la tâche, ainsi qu’un corps contenant l’ID de la tâche et le nom de fichier enregistré par FineParser.
La vérification de la License a lieu avant toute lecture du téléversement : un conteneur sans License rejette donc la requête sans consommer de bande passante ni d’espace disque.
GET /jobs/
Renvoie l’état d’une tâche.file est le chemin du résultat, au format {jobId}/{name}. Faites-le précéder de /jobs/ pour obtenir l’URL de téléchargement. Le nom correspond au nom du fichier téléversé suivi du type de sortie : ainsi, document.pdf analysé en DocLang devient document.pdf.doclang. Le champ est absent tant que la tâche n’a pas abouti, et disparaît à nouveau si le résultat est supprimé du disque.
Une tâche peut échouer pour des motifs de licence après avoir été acceptée, car le nombre de pages n’est connu qu’une fois le document chargé. Dans ce cas, status vaut failed et error le précise. Une tâche ayant échoué n’est jamais facturée.
Renvoie 404 si aucune tâche ne correspond.
GET /jobs//
Téléchargez un résultat. Utilisez la valeurfile de la réponse de statut comme chemin.
Le résultat est renvoyé sous forme de flux, avec un Content-Type correspondant au format de sortie et un en-tête Content-Disposition de type attachment indiquant le nom du fichier, de sorte que curl -OJ l’enregistre sous le bon nom. Les requêtes par plage ne sont pas prises en charge.
DELETE /jobs/
Supprime une tâche et son résultat du disque.GET /healthz
Indique si le conteneur dispose d’une licence et s’il est prêt à accepter des documents. Utilisez-le comme sonde de disponibilité (readiness probe) dans Kubernetes ou dans votre orchestrateur. L’image de conteneur l’utilise également commeHEALTHCHECK Docker.
200. Un conteneur non prêt renvoie 503 avec ready: false, un code expliquant la raison et, généralement, un message detail. L’état de préparation dépend uniquement de la licence. La télémétrie est communiquée en parallèle et n’a jamais d’incidence sur cet état. Voir Vérification de la licence.
Résultats sur le disque
Chaque résultat est écrit dans/app/output sous la forme {jobId}/{name}, à côté d’une petite base de données des tâches. L’organisation des fichiers est stable : vous pouvez donc aussi récupérer les résultats directement depuis le volume monté plutôt que de les télécharger via HTTP.
Par défaut, un résultat est conservé jusqu’à ce que vous exécutiez DELETE sur la tâche ou que vous le supprimiez vous-même du volume. Rien n’expire avec le temps. Si vous préférez laisser FineParser faire le ménage, démarrez le conteneur avec DELETE_ON_DOWNLOAD=true : chaque résultat est alors supprimé, avec son enregistrement de tâche, dès qu’il a été téléchargé intégralement. Ensuite, le statut comme le téléchargement renvoient 404. Un téléchargement interrompu laisse le résultat en place pour permettre une nouvelle tentative.
Les fichiers téléversés sont conservés dans un répertoire temporaire distinct et supprimés dès la fin de la reconnaissance, quelle qu’en soit l’issue.
Redémarrages et arrêt
Les tâches sont enregistrées dans la base de données des tâches, située sur le volume de sortie : elles survivent donc à un redémarrage tant que le volume existe. Les tâches en attente sont reprises. Une tâche en cours au moment de l’arrêt du processus est marquéefailed, car le processus ne peut pas savoir quelle part du résultat a été écrite.
Lors d’un arrêt propre, FineParser cesse d’accepter les requêtes, laisse se terminer celles qui sont en cours, puis se ferme sans attendre le document en cours de reconnaissance. La reconnaissance ne peut pas être interrompue et l’attendre pourrait retarder l’arrêt de plusieurs minutes. La tâche concernée est marquée cancelled et son résultat partiel est supprimé. Soumettez-la de nouveau si vous en avez encore besoin.
Attribuez au conteneur un délai d’arrêt de 60 secondes, avec --stop-timeout 60 sous Docker ou terminationGracePeriodSeconds: 60 sous Kubernetes. La valeur par défaut de Docker, 10 secondes, écourte la phase de vidage et fait perdre les données de télémétrie d’utilisation accumulées depuis le dernier export.
Un seul conteneur à la fois peut utiliser un répertoire de sortie donné. La base de données des tâches est verrouillée tant qu’elle est ouverte : un second conteneur sur le même volume refusera donc de démarrer. Deux conteneurs nécessitent deux volumes.