Consommation de modèles via l'API Document Understanding

Accédez aux modèles IXP créés dans les nœuds d'extraction de flux via l'API du framework Document Understanding à l'aide de points de terminaison d'extraction basés sur des balises ou des ExtractorId.

Les nœuds d'extraction IXP Extraction et traitement intelligents sont accessibles via la même API d'infrastructure Document Understanding. Les nœuds d'extraction apparaissent comme ProjectType: "IXP" dans la découverte et prennent en charge à la fois les points de terminaison basés sur les balises et les points de terminaison basés sur l'extracteur ID pour l'extraction.

Documentation associée :

• Vue d'ensemble de l'API Document Understanding
• Créer une application externe pour Document Understanding
• Gestion d'applications externes

Remarque :

Utilisez l’API v2 pour utiliser les modèles de nœuds d’extraction et utilisez la dernière version des API publiques Document Understanding. Les exemples de cette page utilisent l'API v2 (api-version=2).

Prérequis

Avant d'appeler une API Document Understanding ou Extraction et traitement intelligents (IXP), vous avez besoin d'une application externe enregistrée dans Automation Cloud. Cela fournit le AppID et AppSecret utilisés pour l'authentification OAuth.

Créer une application externe

1. Naviguez vers Orchestrator au niveau du locataire.

2. Sélectionnez Gérer l'accès, puis Gérer les comptes et les groupes.

3. Dans l'en-tête Administration UiPath, sélectionnez Applications externes.

4. Sélectionnez Ajouter une application.

5. Remplissez le Nom de l'application, par exemple, DU API Client.

6. Sélectionnez Application confidentielle, qui est requise pour obtenir un secret d'application.

7. Sous Ressources, sélectionnez Ajouter des étendues :

   • Sélectionnez Document Understanding dans le menu déroulant Ressources.
   • Basculez vers l'onglet Étendue(s) de l'application.
   • Vérifiez les étendues dont vous avez besoin :
     • Du.Digitization.Api - numériser les documents
     • Du.Classification.Api - classer les documents
     • Du.Extraction.Api : extraire des données
     • Du.Validation.Api : créer des tâches de validation
     • Du.DataDeletion.Api : supprimer les données du document
   • Sélectionnez Enregistrer.

8. Sélectionnez Ajouter pour créer l'enregistrement.

   Remarque :

   La fenêtre contextuelle Copier le secret de l'application immédiatement s'affiche une seule fois et ne peut pas être récupérée. Vous pouvez en générer un nouveau plus tard à partir de l'écran de modification.

L'ID d'application est visible sur la page Applications externes à tout moment.

Obtention d'un jeton d'accès

Utilisez l'ID d'application et le Secret de l'application pour demander un jeton OAuth via le flux d'identifiants du client :

curl -X POST 'https://cloud.uipath.com/identity_/connect/token' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<APP_ID>' \
  -d 'client_secret=<your-client-secret>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'

Réponse :

{
  "access_token": "<your-access-token>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}

Le jeton expire après 1 heure. Utilisez-le comme Authorization: Bearer <your-access-token> sur tous les appels d'API suivants.

Remarque :

Si vous perdez le secret de l'application, accédez à Admin, puis Applications externes, modifiez l'application et sélectionnez Générer nouveau sous Secret d'application. Mettez à jour toutes les intégrations avec le nouveau secret.

Principales différences

La table suivante affiche les principales différences entre les projets Document Understanding et Extraction et traitement intelligents (IXP) :

	Document Understanding (Classique ou Moderne)	IXP
Type de projet	Classic ou Modern	IXP
Classification	Oui (Yes)	Non (extraction uniquement)
Routage de l'extraction	Par tag + documentTypeId (recommandé) ou extractorId	Par tag + documentTypeId ou par extractorId (gpt_ixp_[version])
Modèle d’extraction	Spécialisé ou Génératif	Génératif uniquement (GPT-4o, Gemini)
Définition du schéma	Dans le projet ou via des invites	Défini dans l'IU d'Extraction et traitement intelligents (IXP) (taxonomie)

Le workflow Extraction et traitement intelligents (IXP)

1. Découvrez le projet et les balises.
2. Numérisez le document et lancez une interrogation jusqu’à ce que la numérisation soit terminée.
3. Extrayez et interrogez jusqu'à ce que l'extraction soit terminée.
4. Validez (facultatif).

Remarque :

Il n'y a pas d'étape de classification, car Extraction et traitement intelligents (IXP) gère uniquement les extractions.

Étape 1 : découvrir le projet Extraction et traitement intelligents (IXP)

# List all projects - filter for type "IXP"
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Dans la réponse, notez le id du projet IXP.

Obtenir des balises (versions publiées)

Les balises correspondent aux versions de modèle publiées marquées comme Pré-production ou Production dans l'interface utilisateur Extraction et traitement intelligents (IXP). Chaque balise inclut ses extracteurs et types de document associés. Pour obtenir des balises, exécutez les éléments suivants :

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/tags?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Obtenir des types de document

Pour obtenir des types de document, exécutez les éléments suivants :

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/document-types?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Remarque :

Une fois que vous connaissez l'ID du projet, la balise et l'ID du type de document, vous n'avez pas besoin d'exécuter les appels de découverte au moment de l'exécution à chaque fois. Réutilisez plutôt ces valeurs dans votre automatisation.

Étape 2 : numériser le document

Remarque :

La numérisation est une étape obligatoire. Vous ne pouvez pas extraire de données d’un document avant de le numériser.

Semblable à Document Understanding, chargez le fichier pour obtenir un documentId :

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf'

Renvoie { "documentId": "..." }.

Interrogation pour le résultat de la numérisation:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/result/<documentId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

Interrogez jusqu'à ce que status soit Succeeded, puis démarrez l'extraction. Pour connaître les statuts et les réponses possibles, consultez Réponses à l'interrogation.

Étape 3 : extraire

L'extraction d'Extraction et traitement intelligents (IXP) prend en charge les approches de routage suivantes :

• Basé sur des balises - Routage par tag et documentTypeId. Cela est recommandé pour les workflows de Production ou de Pré-production.
• Basé sur ExtractorId - Routez par extractorId en utilisant le format: gpt_ixp_[version]. Par exemple, gpt_ixp_67. C’est la même chose que pour les projets Document Understanding Classiques ou Modernes.

Extraction basée sur des balises

Utilise le chemin basé sur une balise avec le documentTypeId de Découverte.

Synchrone (jusqu'à 5 pages)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Asynchrone (multi-pages)

Démarrez :

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Renvoie { "operationId": "..." }. Interroger pour obtenir le résultat :

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/result/<operationId>?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Interroger jusqu'à ce que status soit Succeeded ou Failed. Pour connaître les statuts et les réponses possibles, consultez Réponses à l'interrogation.

Extraction basée sur ExtractorId

Utilise les mêmes points de terminaison basés sur un extracteur que Document Understanding classique ou moderne. L'ExtractorId pour Extraction et traitement intelligents (IXP) suit le format gpt_ixp_[version], qui est visible dans la réponse de découverte. Synchrone (jusqu'à 5 pages) :

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Asynchrone (multi-pages) :

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Renvoie { "operationId": "..." }. Interroger pour obtenir le résultat :

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/result/<operationId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

Interroger jusqu'à ce que status soit Succeeded ou Failed. Pour connaître les statuts et les réponses possibles, consultez Réponses à l'interrogation.

Étape 4 : Valider (facultatif)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/validation/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentId": "<documentId>",
    "actionTitle": "Review IXP extraction",
    "actionPriority": "Medium",
    "actionCatalog": "default_du_actions",
    "actionFolder": "Shared",
    "storageBucketName": "du_storage_bucket",
    "storageBucketDirectoryPath": "du_storage_bucket",
    "extractionResult": { }
  }'

Réponses au sondage

Les appels de numérisation asynchrones à l’étape 2 et les appels d’extraction asynchrones à l’étape 3 renvoient leurs résultats via une interrogation. Chaque réponse au sondage contient une status, qui est l'une des éléments suivants:

• NotStarted : la tâche a été créée et est en attente de traitement.
• Running : la tâche a été récupérée et est en cours de traitement.
• Succeeded - La tâche s'est terminée avec succès. La réponse contient le result.
• Failed - La tâche s'est terminée avec une erreur. La réponse contient le error.

Continuez l'interrogation tant que le statut est NotStarted ou Running.

Lors du traitement de la tâche, la réponse contient le statut et les horodatages de la tâche:

{
  "status": "Running",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>"
}

Lorsque la tâche réussit, la réponse contient également le result. Pour l'extraction, le résultat est dans result.extractionResult. Pour connaître sa structure, consultez Structure de la réponse d'extraction IXP.

{
  "status": "Succeeded",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>",
  "result": {
    "extractionResult": {
      "documentId": "<documentId>"
    }
  }
}

Lorsque la tâche échoue, la réponse contient un objet error avec les détails suivants:

• message - La description de l'erreur.
• severity - La gravité de l'échec, le plus souvent Error.
• code : le code qui identifie le type d'erreur.
• parameters - Informations supplémentaires sur l'erreur, le cas échéant.

Pour des détails, vérifiez les schémas de requêtes et de réponse dans le guide de l'API Document Understanding.

Structure de réponse d'extraction d'Extraction et traitement intelligents (IXP)

Dans l'API v2, tous les champs et valeurs signalés par IXP utilisent des types de champs corrects, y compris les groupes de champs et les champs enfants, en utilisant un mappage exact des définitions de groupes de champs IXP et de champs enfants.

{
  "extractionResult": {
    "ResultsDocument": {
      "Fields": [
        {
          "FieldId": "Default.Seller",
          "FieldName": "Seller",
          "FieldType": "FieldGroup",
          "IsMissing": false,
          "DataSource": "Automatic",
          "Values": [
            {
              "Components": [
                {
                  "FieldId": "Default.Seller.Name",
                  "FieldName": "Name",
                  "FieldType": "Text",
                  "Values": [
                    {
                      "Value": "John Doe",
                      "Confidence": 0.9999834
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Remarque :

Nous vous recommandons d'utiliser l'API v2 pour l'utilisation d'IXP en raison du mappage univoque entre les groupes de champs et les types de champ du projet IXP et des résultats rapportés.

Structure de réponse de découverte d'Extraction et traitement intelligents (IXP)

Les projets Extraction et traitement intelligents (IXP) exposent le contrôle de version via des balises et des projectVersions :

{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Invoices",
  "type": "IXP",
  "properties": ["SupportsTags", "SupportsVersions"],
  "extractors": [
    {
      "id": "gpt_ixp_67",
      "documentTypeId": "00000000-0000-0000-0000-000000000000",
      "projectVersion": 67
    }
  ],
  "projectVersions": [
    { "version": 67, "tag": "live", "deployed": true }
  ],
  "classifiers": []
}

Le nom de la balise, par exemple live, correspond au libellé Production ou Organisation dans l'interface utilisateur IXP.

Tenez compte des points suivants lors de l'appel des points de terminaison de l'extraction IXP:

• Balise = version du modèle : utilisez la balise qui correspond à la version de production ou de pré-production que vous souhaitez appeler.
• DocumentTypeId : les projets Extraction et traitement intelligents (IXP) utilisent généralement un seul type de document par défaut (00000000-0000-0000-0000-000000000000).
• Limites de pages: pour les limites de pages et de jetons, vérifiez les limites de traitement des documents.
• Mesure: pour de plus amples informations sur la façon dont l'extraction est facturée, consultez le régime IXP Flex, le régime Unified Pricing et la logique de mesure et de facturation (Régime Flex).
• Conservation des données: pour plus de détails sur la durée de conservation des résultats de la numérisation et de l’extraction, consultez la section Présentation de l’API Document Understanding.