Migration d’automatisations de l’API Document Understanding v1 vers v2

Lors de la mise à niveau de l’API Document Understanding v1 vers v2, les modifications majeures suivantes s’appliquent.Certaines mises à jour nécessitent une action pour garantir que vos automatisations continuent de fonctionner comme prévu.

Il est recommandé de suivre les étapes suivantes pour migrer vos automatisations de l’API Document Understanding v1 vers v2 :

1. Mettez à jour les chemins de routage.
2. Mettez à jour la gestion des résultats de l'extraction Extraction et traitement intelligents (IXP) (des tables aux FieldGroups).
3. Recréez et redéployez vers un environnement de non-production.
4. Validez que l’automatisation fonctionne comme prévu dans l'ensemble des quatre dimensions :
   • Découverte
   • Classification
   • Extraction
   • Validation

Les sections suivantes décrivent en détail les modifications et les étapes de migration requises.

Modifications du chemin du point de terminaison

Les routages basés sur des balises ont été normalisés pour améliorer la cohérence sur l’API.

Tous les points de terminaison basés sur des balises utilisant la structure de chemin précédente retournent 400 Bad Request dans v2.

La modification affecte toutes les opérations qui incluent {tag} directement après {projectId}.

v1

POST /projects/{projectId}/{tag}/classification

v2

POST /projects/{projectId}/tags/{tag}/classification

Action requise

Recherchez dans votre base de code : /projects/{projectId}/{tag}/

Remplacez par : /projects/{projectId}/tags/{tag}/

Assurez-vous que cette mise à jour est appliquée de manière cohérente dans tous les environnements.

Modification du schéma de réponse de découverte : fields propriété supprimée

La propriété fields n’est plus retournée.Toute logique de désérialisation ou des modèles fortement typés référençant des champs échoueront ou retourneront des valeurs nulles.

v1

{
  "fields": [
    {
      "name": "InvoiceNumber",
      "type": "string"
    }
  ]
}

v2

{
  "taxonomy": {
    ...
  }
}

Action requise

1. Mettez à jour vos modèles de réponse pour consommer l’Object taxonomy.
2. Refactorisez la logique en aval qui dépendait précédemment de fields.

Modification du schéma de réponse de découverte : tag renommé en tags

L’analyse de la réponse peut échouer si votre modèle attend une seule propriété tag.Si vous utilisez la validation stricte du schéma, des mises à jour sont requises.

v1

{
  "tag": "staging"
}

v2

{
  "tags": ["staging"]
}

Action requise :

1. Mettez à jour les modèles de réponse pour remplacer tag par tags.
2. Ajustez la logique si vous supposez une seule valeur de balise.

Modifications du schéma des résultats de l’extraction Extraction et traitement intelligents (IXP) : tables supprimées et FieldType.Table remplacé par FieldType.FieldGroup

Cette modification affecte uniquement les résultats de l’extraction Extraction et traitement intelligents (IXP).

Dans v1, l’API retournait un résultat d’extraction Extraction et traitement intelligents (IXP) sous forme d’une ou de plusieurs tables. Il s’agissait d’un mappage du concept Extraction et traitement intelligents (IXP) de FieldGroups aux tables. Toutes les valeurs à l’intérieur de ces tables étaient représentées sous forme de Text (string), quel que soit leur type de données Extraction et traitement intelligents (IXP) d’origine.

Dans v2, l’API renvoie les résultats de l’extraction Extraction et traitement intelligents (IXP) en tant que FieldGroups.Cela introduit un mappage 1-1 avec le concept FieldGroup Extraction et traitement intelligents (IXP).Chaque champ préserve son type de données Extraction et traitement intelligents (IXP) réel (par exemple, Text, Nombre, Date, MonetaryQuantity).

v1 (résultat de l’extraction Extraction et traitement intelligents (IXP) retourné sous forme de tables ; valeurs représentées sous forme de Text)

{
  "Tables": [
    {
      "FieldId": "Seller",
      "FieldName": "Seller",
      "IsMissing": false,
      "DataSource": "Automatic",
      "DataVersion": 0,
      "OperatorConfirmed": false,
      "Values": [
        {
          "OperatorConfirmed": true,
          "Confidence": 0.9999834,
          "OcrConfidence": 1.0,
          "Cells": [
            {
              "RowIndex": 0,
              "ColumnIndex": 0,
              "IsHeader": true,
              "IsMissing": false,
              "OperatorConfirmed": false,
              "DataSource": "Automatic",
              "DataVersion": 0,
              "Values": [
                {
                  "Components": [],
                  "Value": "Name",
                  "UnformattedValue": "Name",
                  "Reference": {
                    "TextStartIndex": 0,
                    "TextLength": 0,
                    "Tokens": []
                  },
                  "DerivedFields": [],
                  "Confidence": -1.0,
                  "OperatorConfirmed": false,
                  "OcrConfidence": 1.0,
                  "TextType": "Unknown"
                }
              ]
            }
          ],
          "ColumnInfo": [
            {
              "FieldId": "Name",
              "FieldName": "Name",
              "FieldType": "Text"
            }
          ],
          "NumberOfRows": 2
        }
      ]
    }
  ]
}

v2 (résultat de l’extraction Extraction et traitement intelligents (IXP) retourné en tant que FieldGroups ; les valeurs préservent les types de données Extraction et traitement intelligents (IXP))

{
  "Fields": [
    {
      "FieldId": "Default.Seller",
      "FieldName": "Seller",
      "FieldType": "FieldGroup",
      "IsMissing": false,
      "DataSource": "Automatic",
      "Values": [
        {
          "Components": [
            {
              "FieldId": "Default.Seller.Name",
              "FieldName": "Name",
              "FieldType": "Text",
              "IsMissing": false,
              "DataSource": "Automatic",
              "Values": [
                {
                  "Components": [],
                  "Value": "John Doe",
                  "UnformattedValue": "John Doe",
                  "Reference": {
                    "TextStartIndex": 0,
                    "TextLength": 8,
                    "Tokens": [
                      "..."
                    ]
                  },
                  "DerivedFields": [],
                  "Confidence": 0.9999834,
                  "OperatorConfirmed": false,
                  "OcrConfidence": 0.90999997,
                  "TextType": "Text",
                  "ValidatorNotes": "",
                  "ValidatorNotesInfo": ""
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

• Dans v1, les résultats « semblables à des tables » Extraction et traitement intelligents (IXP) étaient représentés comme FieldType.Table dans l’Array Champs et mappés à une structure de tables à des fins de commodité.
• Dans v2, les résultats Extraction et traitement intelligents (IXP) sont représentés comme FieldType.FieldGroup et retournés en tant que FieldGroups (1:1 avec FieldGroup Extraction et traitement intelligents (IXP)).Toute logique attendant FieldType.Table ou des tables s'interrompt.

Action requise

1. Mettez à jour la gestion des résultats de l’extraction Extraction et traitement intelligents (IXP) pour utiliser des FieldGroups au lieu de tables.
2. Si votre automatisation traite les résultats de l’extraction Extraction et traitement intelligents (IXP) comme des tables, mettez à jour la logique d’analyse pour gérer la nouvelle structure FieldGroup et les champs saisis.
3. Remplacez l’analyse basée sur les chaînes par une gestion sensible au type. Par exemple :
   • Date : analyser en tant que valeur de date
   • Nombre : analyser en tant que valeur numérique
   • MonetaryQuantity : gérez la valeur et la devise en tant qu’un seul objet de données

{
  "Fields": [
    {
      "FieldId": "Seller",
      "FieldName": "Seller",
      "FieldType": "Table",
      "IsMissing": false,
      "DataSource": "Automatic",
      "Values": [
        {
          "Components": [
            {
              "FieldId": "Seller.Header",
              "FieldName": "Header",
              "FieldType": "Internal",
              "IsMissing": false,
              "DataSource": "Automatic",
              "Values": [],
              "DataVersion": 0,
              "OperatorConfirmed": false,
              "ValidatorNotes": ""
            },
            {
              "FieldId": "Seller.Body",
              "FieldName": "Body",
              "FieldType": "Internal",
              "IsMissing": false,
              "DataSource": "Automatic",
              "Values": [],
              "DataVersion": 0,
              "OperatorConfirmed": false,
              "ValidatorNotes": ""
            }
          ],
          "Value": "",
          "UnformattedValue": "",
          "Reference": {
            "TextStartIndex": 0,
            "TextLength": 0,
            "Tokens": []
          },
          "DerivedFields": [],
          "Confidence": 0.9999834,
          "OperatorConfirmed": true,
          "OcrConfidence": 1.0,
          "TextType": "Unknown"
        }
      ],
      "DataVersion": 0,
      "OperatorConfirmed": false,
      "ValidatorNotes": ""
    }
  ]
}