Créer des artefacts pour la validation de l'extraction

Créez des artefacts de validation d'extraction dans Document Understanding à l'aide des API d'artefacts, puis laissez votre application créer une tâche d'application pour la validation humaine.

Remarque :

Cette fonctionnalité est en aperçu.

Utilisez les API d’artefacts pour préparer les artefacts de validation d’extraction stockés dans les compartiments de stockage Orchestrator. Les artefacts sont ensuite utilisés par votre application pour créer une tâche d'application pour la validation humaine - dissociant la création d'artefacts de la gestion des tâches et vous donnant le contrôle sur le moment, l'emplacement et l'interface utilisateur de la tâche.

Important :

Cette fonctionnalité n’est pas disponible dans Automation Cloud pour le secteur public, car la création d’applications n’y est pas prise en charge.

Vue d’ensemble du workflow

1. Numérisez le document.
2. Extrayez les données du document.
3. Récupérez la taxonomie du projet.
4. Démarrez la création de l’artefact.
5. Interrogez jusqu’à ce que les données de validation de contenu soient prêtes.
6. Créez une tâche d’application dans Action Center à l’aide des données de validation de contenu.
7. Terminez la validation dans la station de validation.
8. Récupérer le résultat validé de l'extraction.

Prérequis

• Un projet Document Understanding avec un modèle d’extraction configuré.
• Les documentId et extractionResult d’un appel d’extraction précédent. Pour les obtenir, suivez le guide Utiliser les API de numérisation pour numériser le document et obtenir une documentId, puis suivez le guide Utiliser le service d'extraction pour exécuter l'extraction et obtenir la extractionResult.
• Un compartiment de stockage et un chemin d'accès au répertoire accessibles depuis votre locataire.
• Une application pour héberger la tâche de validation. Vous pouvez déployer l'application par programmation en utilisant le point de terminaison deployUnifiedPackage de l'API Apps.

Étendues OAuth requises

Votre application externe doit inclure les étendues suivantes. Pour obtenir des instructions sur la configuration d’une application externe, consultez la section Authentification et autorisation.

API call	Étendue requise
Récupérer la taxonomie du projet	Du.Digitization.Api, Du.Extraction.Api, Du.Classification.Api, ou Du.Validation.Api
Points de terminaison de validation (création d’artefacts, interrogation, résultat)	Du.Validation.Api

Récupérer la taxonomie du projet

Récupérez la taxonomie de votre projet Document Understanding. Transmettez cette taxonomie lorsque vous démarrez la création des artefacts de validation d’extraction.

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/projects/<Project_ID>/taxonomy?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Réponse :

{
  "documentTaxonomy": {
    "dataContractVersion": "1.2",
    "documentTypes": [
      {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "group": "",
        "category": "",
        "name": "invoices",
        "optionalUniqueIdentifier": "",
        "typeField": {
          "fieldId": "invoices.DocumentType",
          "fieldName": "Document Type"
        },
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "isMultiValue": false,
            "type": "Text",
            "components": [],
            "setValues": [],
            "metadata": [],
            "ruleSet": null,
            "defaultValue": null,
            "dataSource": null
          }
        ]
      }
    ],
    "groups": [],
    "supportedLanguages": ["en"],
    "reportAsExceptionSettings": null
  }
}

Chemins alternatifs pour récupérer la taxonomie

Vous pouvez également récupérer la taxonomie à l'aide de points de terminaison de découverte existants:

• GET /projects/{projectId}/extractors/{extractorId} — renvoie la taxonomie pour un extracteur spécifique.
• GET /projects/{projectId}/tags/{tag}/document-types/{documentTypeId} — renvoie la taxonomie pour un type de document spécifique par balise. Le filtrage basé sur des balises n’est pas pris en charge pour les projets Document Understanding classiques.

Remarque :

Si vous transmettez une taxonomie étendue à un extracteur ou à un type de document spécifique, la fonctionnalité Modifier le type de document n’est pas disponible pour l’opérateur pendant la validation dans la Station de validation.

Le point de terminaison de la taxonomie principal prend également en charge les paramètres de requête projectVersion et tag. Tenez compte des éléments suivants lorsque vous l'utilisez:

• Projets modernes: sans filtrage par tag , un même documentTypeId peut apparaître plusieurs fois si plusieurs extracteurs de déploiements différents sont basés sur le même type de document. Utilisez le paramètre tag pour limiter les résultats à un déploiement spécifique et éviter les doublons.
• Projets classiques: le filtrage par balises n'est pas pris en charge. S'il existe plusieurs extracteurs pour le même type de document, utilisez plutôt le point de terminaison spécifique à l'extracteur (/projects/{projectId}/extractors/{extractorId}) pour éviter toute ambiguïté.

Démarrer la création d'artefacts de validation d'extraction

Envoyez une requête POST pour démarrer la création d’artefacts de validation d’extraction. Transmettez l'objet documentTaxonomy complet récupéré dans l'appel précédent.

documentTaxonomy est nécessaire. storageBucketName et folderName sont facultatifs. Si vous ne spécifiez pas folderName, la valeur par défaut sera le dossier Shared.

Important :

Les dossiers de compartiment de stockage dans votre espace de travail personnel ne sont pas pris en charge.

curl -X 'POST' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/start?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
  "extractionResult": {
    "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
    "resultsVersion": 0,
    "resultsDocument": {
      "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
      "documentTypeName": "invoices",
      "fields": [
        {
          "fieldId": "invoices.invoice-no",
          "fieldName": "Invoice Number",
          "type": "Text",
          "isMissing": false,
          "dataSource": "Automatic",
          "values": [
            {
              "value": "181038",
              "confidence": 0.98,
              "operatorConfirmed": false
            }
          ]
        }
      ]
    }
  },
  "documentTaxonomy": {
    "dataContractVersion": "1.2",
    "documentTypes": [
      {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "name": "invoices",
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "type": "Text"
          }
        ]
      }
    ],
    "groups": [],
    "supportedLanguages": ["en"],
    "reportAsExceptionSettings": null
  },
  "storageBucketName": "du_storage_bucket",
  "storageBucketDirectoryPath": "du_storage_bucket"
}'

Réponse: fournit les operationId et les URL des deux appels suivants:

{
  "operationId": "7c320dfc-a1b2-4c3d-8e9f-000d3a4964af",
  "artifactsUrl": "https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/content-validation-data/7c320dfc-a1b2-4c3d-8e9f-000d3a4964af?api-version=2",
  "resultUrl": "https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/validation-result/7c320dfc-a1b2-4c3d-8e9f-000d3a4964af?api-version=2"
}

Interroger la préparation aux artefacts

Envoyez des requêtes GET au artifactsUrl renvoyé lorsque vous avez commencé la création de l'artefact, jusqu'à ce que le statut soit Succeeded ou Failed.

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/content-validation-data/<operationId>?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

La réponse renvoie l'un des quatre statuts:

État (Status)	Signification
NotStarted	La tâche est en file d’attente, mais pas encore en cours de traitement.
Running	La préparation de l’artefact est en cours.
Succeeded	Les artefacts sont prêts. Continuez avec la création de la tâche d'application (étape 6).
Failed	Échec de la préparation de l’artefact. Consultez error.code pour en savoir plus.

Réponse lorsque les artefacts sont prêts:

{
  "contentValidationData": {
    "bucketName": "du_storage_bucket",
    "bucketId": 261151,
    "folderId": 810789,
    "folderKey": "4c6ff0e2-0a05-4ce1-9508-7102b977bd58",
    "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
    "encodedDocumentPath": "du_storage_bucket/7c320dfc-.../encoded.zip",
    "textPath": "du_storage_bucket/7c320dfc-.../text.zip",
    "documentObjectModelPath": "du_storage_bucket/7c320dfc-.../dom.zip",
    "taxonomyPath": "du_storage_bucket/7c320dfc-.../taxonomy.zip",
    "automaticExtractionResultsPath": "du_storage_bucket/7c320dfc-.../input_results.zip",
    "validatedExtractionResultsPath": "du_storage_bucket/7c320dfc-.../output_results.zip",
    "customizationInfoPath": "du_storage_bucket/7c320dfc-.../customization_info.zip"
  },
  "status": "Succeeded",
  "createdAt": "2026-04-28T10:00:00Z",
  "lastUpdatedAt": "2026-04-28T10:00:05Z"
}

Remarque :

L'objet contentValidationData contient les chemins du compartiment de stockage Orchestrator nécessaires pour ouvrir le document dans la station de validation. La Station de validation utilise le mode compact pour les flux de tâches d'application; le mode classique n’est pas disponible pour ce flux.

Réponse lors du traitement:

{
  "status": "Running",
  "createdAt": "2026-04-28T10:00:00Z",
  "lastUpdatedAt": "2026-04-28T10:00:02Z"
}

Récupérer le résultat de l’extraction validé

Appelez ce point de terminaison une fois que l'opérateur humain a terminé la validation dans la station de validation (étapes 6 à 7). Envoyez une requête GET au fichier resultUrl renvoyé lorsque vous avez démarré la création de l’artefact.

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/validation-result/<operationId>?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Remarque :

Si la tâche Action Center n’est pas encore terminée (les étapes 6 à 7 ne sont pas encore terminées), le point de terminaison renvoie 200 avec un résultat vide:

{
  "result": {}
}

Réponse lorsque la validation est terminée:

{
  "result": {
    "validatedExtractionResults": {
      "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
      "resultsVersion": 1,
      "resultsDocument": {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "documentTypeName": "invoices",
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "type": "Text",
            "isMissing": false,
            "dataSource": "Automatic",
            "values": [
              {
                "value": "181038",
                "confidence": 1,
                "operatorConfirmed": true
              }
            ],
            "operatorConfirmed": true
          }
        ]
      }
    }
  }
}

Résultat

Une réponse 200 contenant validatedExtractionResults confirme que la validation de l'extraction est terminée. L'indicateur operatorConfirmed: true sur chaque champ indique que le résultat a été validé.