Migrando automações da API do Document Understanding v1 para v2

Ao atualizar da API do Document Understanding v1 para a v2, as seguintes alterações interruptivas se aplicam. Algumas atualizações exigem ações para garantir que suas automações continuem a funcionar conforme o esperado.

É recomendável seguir as seguintes etapas para migrar suas automações da API do Document Understanding v1 para a v2:

1. Atualize caminhos de rota.
2. Atualize o processamento de resultados da extração de IXP (de Tabelas para GruposDeCampos).
3. Recompile e reimplante em um ambiente de não produção.
4. Valida que a automação funciona conforme o esperado em todas as quatro dimensões:
   • Descoberta,
   • Classificação,
   • Extração
   • Validação.

As seções a seguir descrevem as alterações em detalhes e as etapas de migração necessárias.

Alterações do caminho do endpoint

As rotas baseadas em tags foram normalizadas para melhorar a consistência em toda a API.

Todos os endpoints baseados em tag usando a estrutura de caminho anterior retornam 400 Bad Request na v2.

A alteração afeta todas as operações que incluem {tag} diretamente após {projectId}.

v1

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

v2

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

Ação necessária

Pesquisar sua base de código por: /projects/{projectId}/{tag}/

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

Certifique-se de que esta atualização seja aplicada de forma consistente em todos os ambientes.

Alteração do esquema de resposta da descoberta: propriedade fields removida

A propriedade fields não é mais retornada. Qualquer lógica de desserialização ou campos de referência de modelos fortemente digitados falharão ou retornarão valores nulos.

v1

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

v2

{
  "taxonomy": {
    ...
  }
}

Ação necessária

1. Atualize seus modelos de resposta para consumir o objeto taxonomy .
2. Refatore a lógica downstream que anteriormente dependia de fields.

Alteração do esquema de resposta da descoberta: tag renomeado para tags

A análise de resposta pode falhar se seu modelo esperar uma única propriedade tag . Se você estiver usando a validação estrita de esquema, as atualizações são necessárias.

v1

{
  "tag": "staging"
}

v2

{
  "tags": ["staging"]
}

Ação necessária:

1. Atualize modelos de resposta para substituir tag por tags.
2. Ajuste a lógica se estiver considerando um único valor de tag.

Alterações no esquema de resultados da extração de IXP: tabelas removidas e FieldType.Table substituído por FieldType.FieldGroup

Essa alteração afeta apenas os resultados da extração de IXP.

Na v1, a API retornava um resultado de extração de IXP como uma ou mais Tabelas. Este foi um mapeamento do conceito de IXP de FieldGroups para tabelas. Todos os valores dentro dessas tabelas eram representados como texto (string), independentemente de seu tipo de dados IXP original.

Na v2, a API retorna os resultados da extração da IXP como FieldGroups. Isso introduz um mapeamento 1 para 1 com o conceito FieldGroup do IXP. Cada campo preserva seu tipo de dados IXP real (por exemplo, Texto, Número, Data, Quantidade Monetária).

v1 (o resultado da extração IXP retorna como Tabelas; 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 (o resultado da extração da IXP é retornado como FieldGroups; os valores preservam os tipos de dados da 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": ""
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

• Na v1, os resultados “tipo tabela” do IXP eram representados como FieldType.Table na matriz Campos e mapeados para uma estrutura de tabelas por conveniência.
• Na v2, os resultados de IXP são representados como FieldType.FieldGroup e retornados como FieldGroups (1:1 com IXP FieldGroup). Qualquer lógica que espere FieldType.Table ou tabelas será interrompida.

Ação necessária

1. Atualize o processamento de resultados da extração de IXP para usar GruposDeCampos em vez de Tabelas.
2. Se sua automação tratar os resultados da extração IXP como tabelas, atualize a lógica de análise para lidar com a nova estrutura FieldGroup e campos digitados.
3. Substitua a análise baseada em string pelo manuseio com reconhecimento de tipo. Por exemplo:
   • Data: analisar como um valor de data
   • Número: analisar como um valor numérico
   • MonetaryQuantity: lidar com valor e moeda como um único objeto de dados

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