Migrar automatizaciones de la API de Document Understanding v1 a v2

Al actualizar de la API de Document Understanding v1 a v2, se aplican los siguientes cambios importantes.Algunas actualizaciones requieren acción para garantizar que tus automatizaciones sigan funcionando como se espera.

Se recomienda que realices los siguientes pasos para migrar tus automatizaciones de la API de Document Understanding v1 a v2:

1. Actualizar las rutas.
2. Actualiza la gestión de resultados de Extracción y Procesamiento Inteligentes (IXP) (de Tablas a Grupos de Campo).
3. Vuelve a crear y vuelve a implementar en un entorno de no producción.
4. Valida que la automatización funcione como se espera en todas las cuatro dimensiones:
   • Descubrimiento,
   • Clasificación,
   • Extracción,
   • Validación.

Las siguientes secciones describen los cambios en detalle y los pasos de migración necesarios.

Cambios de Ruta del PuntoFinal

Se han normalizado las rutas basadas en etiquetas para mejorar la coherencia en toda la API.

Todos los puntos finales basados en etiquetas que utilizan la estructura de ruta anterior devuelven 400 Bad Request en v2.

El cambio afecta a todas las operaciones que incluyen {tag} directamente después de {projectId}.

v1

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

v2

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

Acción requerida

Busca en tu base de código: /projects/{projectId}/{tag}/

Reemplazar por: /projects/{projectId}/tags/{tag}/

Asegúrate de que esta actualización se aplique de forma coherente en todos los entornos.

Cambio de esquema de respuesta de descubrimiento: propiedad fields eliminada

La propiedad fields ya no se devuelve. Cualquier lógica de deserialización o cualquier modelo fuertemente tipado que haga referencia a los Campos dará Error o devolverá valores nulos.

v1

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

v2

{
  "taxonomy": {
    ...
  }
}

Acción requerida

1. Actualizar tus modelos de Respuesta para consumir el objeto taxonomy.
2. Refactoriza la lógica descendente que dependía previamente de fields.

Cambio de esquema de respuesta de descubrimiento: se ha cambiado el nombre de tag a tags

El análisis de la Respuesta puede generar un Error si tu modelo espera una propiedadtagindividual. Si utilizas la validación de esquema estricta, se requieren actualizaciones.

v1

{
  "tag": "staging"
}

v2

{
  "tags": ["staging"]
}

Acción requerida:

1. Actualiza los modelos de respuesta para sustituir tag por tags.
2. Ajusta la lógica si asumes un valor de etiqueta único.

Cambios en el esquema de resultados de Extracción y Procesamiento Inteligentes (IXP): se eliminan las Tablas y FieldType.Table se sustituye por FieldType.FieldGroup

Este cambio afecta solo a los resultados de extracción de Extracción y Procesamiento Inteligentes (IXP).

En la versión v1, la API devolvía un resultado de extracción de Extracción y Procesamiento Inteligentes (IXP) como una o más tablas.Esta fue una asignación del concepto de Extracción y Procesamiento Inteligentes (IXP) de FieldGroups a tablas. Todos los valores dentro de esas tablas se representaban como texto (string), independientemente de su tipo de datos de Extracción y Procesamiento Inteligentes (IXP) original.

En la versión 2, la API devuelve los resultados de extracción de Extracción y Procesamiento Inteligentes (IXP) como Grupos de campo.Esto introduce una asignación 1 a 1 con el concepto de Extracción y Procesamiento Inteligentes (IXP). Cada campo conserva su tipo de datos de Extracción y Procesamiento Inteligentes (IXP) actual (por ejemplo, Texto, Número, Fecha, Cantidad Monetaria).

v1 (resultado de extracción de Extracción y Procesamiento Inteligentes (IXP) devuelto como Tablas; valores representados como texto)

{
  "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 (resultado de extracción de Extracción y Procesamiento Inteligentes (IXP) devuelto como Grupos de Campo; los valores conservan los tipos de datos de Extracción y Procesamiento Inteligentes (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": ""
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

• En la versión v1, los resultados de Extracción y Procesamiento Inteligentes (IXP) se representaban como FieldType.Table en la matriz Campos y se asignaban a una estructura de tablas para mayor comodidad.
• En la versión 2, los resultados de Extracción y Procesamiento Inteligentes (IXP) se representan como FieldType.FieldGroup y se devuelven como FieldGroups (1:1 con FieldGroup de Extracción y Procesamiento Inteligentes (IXP)). Cualquier lógica que espere FieldType.Table o tablas se interrumpirá.

Acción requerida

1. Actualiza la gestión de resultados de extracción y procesamiento inteligentes (IXP) para utilizar Grupos de campo en lugar de Tablas.
2. Si tu automatización trata los resultados de extracción de Extracción y Procesamiento Inteligentes (IXP) como tablas, actualiza la lógica de análisis para manejar la nueva estructura de Grupo de Campo y los campos tipados.
3. Reemplaza el análisis basado en cadenas con el manejo sensible a tipos. Por ejemplo:
   • Fecha: analizar como un valor de fecha
   • Número: analizar como un valor numérico
   • Cantidad monetaria: manejar el valor y la moneda como un solo objeto de datos

{
  "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": ""
    }
  ]
}