Migrar automatizaciones de la API de Document Understanding v1 a v2

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

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

1. Actualizar rutas de ruta.
2. Actualizar la gestión de resultados de extracción de Extracción y Procesamiento Inteligentes (IXP) (de Tablas a GruposDeCampos).
3. Reconstruir y volver a implementar en un entorno que no sea de producción.
4. Valida que la automatización funciona como se espera en 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 en la ruta del punto final

Las rutas basadas en etiquetas se han normalizado para mejorar la coherencia en toda la API.

Todos los puntos finales basados en etiquetas que utilizan la estructura de ruta anterior devuelven 400 Solicitudes incorrectas 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

Busque en su código base: /projects/{projectId}/{tag}/

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

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

Cambio en el esquema de respuesta de descubrimiento: propiedad fields eliminada

La propiedad fields ya no se devuelve. Cualquier lógica de deserialización o modelos fuertemente tipados que hagan referencia a campos fallará o devolverá valores nulos.

v1

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

v2

{
  "taxonomy": {
    ...
  }
}

Acción requerida

1. Actualiza tus modelos de respuesta para consumir el objeto taxonomy .
2. Refactorizar la lógica descendente que anteriormente dependía de fields.

Cambio de esquema de respuesta de descubrimiento: tag renombrado a tags

El análisis de respuesta puede fallar si tu modelo espera una sola propiedad tag . Si utilizas la validación de esquema estricta, se requieren actualizaciones.

v1

{
  "tag": "staging"
}

v2

{
  "tags": ["staging"]
}

Acción requerida:

1. Actualice los modelos de respuesta para reemplazar tag por tags.
2. Ajuste la lógica si se supone un único valor de etiqueta.

Cambios en el esquema de resultados de extracción de IXP: tablas eliminadas y FieldType.Table reemplazado por FieldType.FieldGroup

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

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

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

v1 (resultado de la extracción 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 IXP devuelto como GruposDeCampos; los valores conservan los tipos de datos de 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 v1, los resultados "tipo tabla" de Extracción y Procesamiento Inteligentes (IXP) se representaban como FieldType.Table en la matriz de campos y se asignaban a una estructura de tablas para mayor comodidad.
• En v2, los resultados de Extracción y Procesamiento Inteligentes (IXP) se representan como TipoDeCampo.GrupoDeCampos y se devuelven como GruposDeCampos (1:1 con GrupoDeCampos de Extracción y Procesamiento Inteligentes (IXP)). Cualquier lógica que espere FieldType.Table o tablas se romperá.

Acción requerida

1. Actualice la gestión de resultados de extracción de Extracción y Procesamiento Inteligentes (IXP) para utilizar FieldGroups en lugar de Tables.
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 gestionar la nueva estructura de GrupoDeCampos y los campos escritos.
3. Reemplaza el análisis basado en cadenas por el manejo con reconocimiento de tipos. Por ejemplo:
   • Fecha: analizar como un valor de fecha
   • Número: analizar como un valor numérico
   • MonetaryQuantity: gestiona el valor y la moneda como un único 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": ""
    }
  ]
}