- ID de transaction.
- ID de Skill et version.
- Chemin de traitement par étapes :
- Types d’étapes
- Noms
- Date et heure de début et de fin de l’étape
- Durée (en secondes)
- Nom et e-mail de l’opérateur de relecture manuelle.
- Paramètres d’enregistrement du document et de la transaction.
Le Warehouse ne stocke pas d’informations sur les événements de traitement des documents dans les activités qui ne sont jamais exécutées selon leur configuration. Par exemple, le paramètre « Assemble by files » correspond au comportement par défaut de Vantage ; par conséquent, le traitement des documents dans cette activité sera ignoré dans un workflow.
Comprendre les différences de comportement entre v1 et v2
Avant la migration, il est important de comprendre que v1 et v2 ne diffèrent pas uniquement par la structure de l’API : elles définissent différemment la période de déclaration, et ce, intentionnellement. Attendez-vous à des totaux différents lorsque vous comparez les deux versions, et pas seulement à un format de requête/réponse différent. v1 filtre par transaction, puis renvoie toutes les étapes de ces transactions. Si les étapes d’une transaction chevauchent, même partiellement, la fenêtre de filtragestartDate/endDate, toutes ses étapes sont renvoyées, y compris celles terminées plusieurs semaines avant startDate ou après endDate.
v2 filtre par étape. Seules les étapes dont l’horodatage CompletedUtc se situe dans la fenêtre startDate/endDate sont renvoyées ; les autres étapes de la transaction sont exclues, même si d’autres étapes de cette même transaction se situent dans la fenêtre.
Requêtes synchrones et asynchrones
La v1 consiste en un unique appel synchrone : vous envoyez une requête GET avec des paramètres de requête et recevez directement les données du rapport dans la réponse. La v2 utilise quant à elle un modèle asynchrone : vous soumettez une requête, interrogez son statut, puis téléchargez les résultats une fois le rapport prêt. Ce changement permet à la v2 de traiter des requêtes de données bien plus volumineuses sans expirer. La v1 est obsolète, mais les clients peuvent continuer à l’utiliser ; aucune date de retrait n’est actuellement prévue.Portée de la période de déclaration
Comme v2 filtre selon la valeurCompletedUtc de chaque étape, chaque étape appartient à une seule fenêtre temporelle, quelle que soit la façon dont vous découpez la plage : un ensemble de rapports quotidiens donnera le même total qu’un rapport couvrant la plage équivalente sur plusieurs jours. Il s’agit d’une amélioration importante par rapport à v1, où l’inclusion d’une étape dépend du fait que sa transaction était active pendant la fenêtre, et non de l’heure d’achèvement de l’étape elle-même. Les totaux de v1 ne sont donc pas nécessairement les mêmes selon le découpage de la plage.
Un point à garder à l’esprit avec v2 : les étapes d’une transaction qui s’étendent sur deux jours apparaîtront dans deux rapports quotidiens différents, un pour chaque jour, au lieu d’être toutes regroupées dans l’un ou l’autre.
Le filtrage par date repose sur completedUtc
Dans le point de terminaison v2, startDate et endDate filtrent tous deux selon l’horodatage CompletedUtc propre à chaque étape, et non selon une heure de début ou de fin au niveau de la transaction.
Chaque étape d’une transaction (par exemple, Input, Classification, Extraction, relecture manuelle, Output) ayant sa propre valeur CompletedUtc, les étapes d’une même transaction peuvent être réparties sur différentes dates. Chaque étape est évaluée, puis incluse ou exclue indépendamment, uniquement en fonction de sa propre heure de fin.
Si une étape de transaction est retraitée, corrigée, repasse par la relecture manuelle ou fait l’objet d’une nouvelle tentative, pour quelque raison que ce soit, son CompletedUtc est mis à jour avec la nouvelle heure de fin. Dans la v2, cela n’affecte les résultats que lorsque la valeur endDate de la requête se situe dans le futur, c’est-à-dire lorsque la fenêtre est encore ouverte. Une fois que la valeur endDate d’une requête est passée, ses résultats sont stables : le retraitement horodate une étape avec l’heure actuelle, qui, par définition, est postérieure à une fenêtre déjà fermée ; elle ne peut donc pas y entrer ou en sortir rétroactivement.
Seules les étapes terminées apparaissent dans les résultats v2
Un export v2 renvoie uniquement les étapes terminées. Une étape encore en cours, par exemple une étape au statutProcessing, n’a pas de valeur CompletedUtc : l’export l’ignore donc. Elle apparaîtra dans un export ultérieur dont la plage de dates inclut son heure de fin.
La v1 renvoie toutes les étapes d’une transaction active pendant la période : un rapport v1 peut donc inclure des étapes encore en cours. Dans un rapport v1, vérifiez le Status de chaque étape avant de la considérer comme terminée.
Approche recommandée pour un rapport quotidien
Un besoin courant consiste à générer un rapport sur les transactions de la veille. Utilisez v2 à cette fin, avecstartDate et endDate définis sur la plage UTC allant de 00:00:00 à 23:59:59 de la veille. Comme v2 filtre selon le CompletedUtc propre à chaque étape, il renvoie exactement les étapes terminées ce jour-là, ce qui permet d’obtenir des totaux cohérents d’un jour à l’autre.
Évitez d’utiliser v1 à cette fin. Comme v1 renvoie chaque étape de toute transaction active pendant la période, une transaction comportant des étapes terminées des semaines avant ou après le jour ciblé est tout de même renvoyée dans son intégralité, incluant ainsi des étapes sans rapport dans des chiffres qui devraient concerner une seule journée.
Un compromis à prendre en compte avec l’approche v2 : les étapes d’une transaction qui chevauche minuit seront réparties entre deux rapports quotidiens, un pour chaque jour, au lieu d’apparaître entièrement dans l’un ou l’autre. Ce comportement est attendu ; voir la portée de la période de déclaration ci-dessus.
Tant que endDate correspond à un jour déjà entièrement écoulé, le rapport est stable et reproductible : l’exécution ultérieure de la même requête renvoie les mêmes résultats. En revanche, si vous interrogez une plage incluant la journée en cours, les résultats peuvent changer d’une exécution à l’autre à mesure que d’autres étapes se terminent (voir Le filtrage par date est basé sur CompletedUtc ci-dessus).
Migration de v1 vers v2
Quoi de neuf ?
Dans la requête (/api/reporting/v2/exports/transaction-steps) :
- Les filtres ont été déplacés des paramètres de requête vers le corps de la requête (objet JSON
filters). startDate, spécifié dans l’objetfilters, est désormais obligatoire.- Nouveau champ :
sendEmailNotification(true/false) - envoie un e-mail à l’utilisateur ayant demandé le rapport lorsque celui-ci est prêt à être téléchargé.
/api/reporting/v2/exports/transaction-steps/{{requestId}}/result/{fileIndex}), deux colonnes ont été ajoutées :
DocumentsCount: le nombre de documents traités dans une transaction.PagesCount: le nombre de pages traitées dans une transaction.
Différences d’utilisation de l’API
v1 utilise une seule requête GET avec des paramètres de requête et renvoie directement le rapport. v2 déplace les filtres vers le corps d’une requête POST, puis divise le processus en trois appels : demander le rapport, interroger périodiquement son statut et télécharger les résultats une fois qu’il est prêt. Poursuivez votre lecture pour en savoir plus sur le fonctionnement du point de terminaison v2 ci-dessous.Téléchargement d’un rapport de données
Seuls les utilisateurs ayant les rôles Tenant Administrator et Processing Supervisor peuvent télécharger un rapport de données depuis le Warehouse. Pour plus d’informations, consultez Contrôle d’accès fondé sur les rôles (RBAC).
filters :
- skillId. L’ID du Skill dont les transactions doivent être téléchargées. Facultatif.
- transactionId. L’ID de la transaction à utiliser pour le filtrage. Facultatif.
- startDate. Le premier jour de la période (format d’exemple : 2022-01-07T13:03:38, l’heure doit être en UTC) pour laquelle les transactions doivent être téléchargées. Filtre selon l’horodatage
CompletedUtcde chaque étape. Obligatoire. - endDate. Le dernier jour de la période (format d’exemple : 2022-09-07T13:03:38, l’heure doit être en UTC) pour laquelle les transactions doivent être téléchargées. Filtre selon l’horodatage
CompletedUtcde chaque étape. Facultatif. - sendEmailNotification. Envoyer un e-mail à l’utilisateur qui a créé la demande de rapport pour l’informer que le rapport est prêt à être téléchargé. Facultatif.
requestId utilisé pour vérifier l’état de la requête.
Résultat :
requestId dans la requête GET :
Interrogez régulièrement ce point de terminaison jusqu’à ce que le status ait la valeur Succeeded, Failed ou Cancelled. Le status prend l’une des valeurs suivantes :
Vantage traite une seule requête d’export à la fois par tenant. Si vous soumettez plusieurs requêtes, chacune reste à l’état
New jusqu’à ce que les requêtes qui la précèdent soient terminées, ce qui peut retarder son passage à l’état Processing. Si vous avez besoin de plusieurs rapports, soumettez chaque requête une fois la précédente terminée.
Vantage annule toute requête qui reste dans le même état au-delà des délais suivants :
Si le
status a la valeur Failed ou Cancelled, soumettez une nouvelle requête ultérieurement. La réponse d’état inclut également un correlationId. Communiquez-le si vous contactez le support ABBYY au sujet d’une requête ayant échoué ou ayant été annulée.
Lorsque le status a la valeur Succeeded, totalFileCount indique le nombre de fichiers disponibles au téléchargement :
requestId et en ajoutant le fileIndex, c’est-à-dire l’indice du fichier (à partir de zéro). Par exemple, si "totalFileCount": 3, les indices de fichier disponibles sont 0, 1 et 2.
Voici un exemple de réponse CSV :
Structure de la réponse
Chaque ligne d’un fichier CSV correspond à une opération effectuée sur une transaction, par exemple l’importation de documents, la reconnaissance ou la relecture manuelle. Pour chaque opération dans le Warehouse, ses détails sont stockés dans des colonnes :
Vantage conserve les fichiers de résultat pendant 14 jours après l’exécution de la requête. Il supprime ensuite les fichiers ainsi que la requête, qui n’apparaît alors plus dans la liste des demandes de rapport. Les données obtenues au format CSV peuvent ensuite être analysées dans n’importe quel outil de Business Intelligence (BI).
Récupération de la liste des demandes de rapport
Pour récupérer la liste des demandes de rapport effectuées sur une période donnée, effectuez une requête GET vers le point de terminaison suivant, oùcreatedFrom et createdTo représentent la plage de dates et statusFilter est l’une des valeurs suivantes : New,Queued,Processing,Succeeded,Failed, ou Cancelled. Cette opération est utile si vous avez égaré des identifiants de demande.
La réponse contient un tableau de requêtes de reporting.