Migração de automações da API do Document Understanding v1 para v2

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

Recomenda-se que você siga as seguintes etapas para migrar suas automações da API do Document Understanding v1 para v2:

1. Atualizar caminhos de rota.
2. Atualizar o tratamento dos resultados de Extração e Processamento Inteligente (IXP) (de Tabelas para FieldGroups).
3. Recriar e implantar novamente em um ambiente de não produção.
4. Valide se sua automação está funcionando como esperado em Todos os quatro aspectos
   • Discovery,
   • 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 no caminho do ponto de extremidade

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

Todos os pontos de extremidade baseados em tags que usam 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 em sua base de código por: /projects/{projectId}/{tag}/

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

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

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

A propriedade fields não é mais retornada. Qualquer lógica de desserialização ou modelos com estrutura de dados rigorosa que façam referência a campos 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 subsequente 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 propriedade únicatag. Se você estiver usando validação de esquema rigorosa, são necessárias atualizações.

v1

{
  "tag": "staging"
}

v2

{
  "tags": ["staging"]
}

Ação necessária

1. Atualizar 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ída por FieldType.FieldGroup

Essa alteração afeta apenas os resultados da Extração e Processamento Inteligente (IXP).

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

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

v1 (resultado da extração do IXP retornado 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 (resultado da extração do IXP retornado como FieldGroups; os valores preservam os tipos de dados do 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 "semelhantes a tabelas" da Extração e Processamento Inteligente (IXP) eram representados como FieldType.Table na matriz Campos e mapeados para uma estrutura de tabelas por conveniência.
• Na v2, os resultados da Extração e Processamento Inteligente (IXP) são representados como FieldType.FieldGroup e retornados como FieldGroups (1:1 com FieldGroup IXP).Qualquer lógica que espere FieldType.Table ou tabelas será interrompida.

Ação necessária

1. Atualize o tratamento do resultado de extração do IXP para usar FieldGroups em vez de Tabelas.
2. Se sua automação tratar resultados de extração de IXP como tabelas, atualize a lógica de análise para lidar com a nova estrutura de FieldGroup e campos digitados.
3. Substitua a análise baseada em strings por tratamento sensível a tipos. Por exemplo:
   • Data: analise como um valor de data.
   • Número: analise como um valor numérico.
   • Quantidade Monetária: trate 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": ""
    }
  ]
}