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

Migre automações da API do Document Understanding v1 para v2, abordando alterações significativas e atualizações necessárias para manter as integrações funcionando.

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. Atualize a caixa de propriedade de resposta (de CamelCase para PascalCase).
2. Atualizar caminhos de rota.
3. Atualizar o tratamento dos resultados de Extração e Processamento Inteligente (IXP) (de Tabelas para FieldGroups).
4. Recriar e implantar novamente em um ambiente de não produção.
5. 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.

Caixa da propriedade de resposta: CamelCase substituída por PascalCase

Os corpos de resposta em todas as rotas v2 usam nomes da propriedades PascalCase.

Na v1, as maiúsculas e minúsculas são inconsistentes entre as rotas. As rotas de classificação, extração e validação do framework retornam nomes de propriedades CamelCase, enquanto a extração generativa e os resultados da extração IXP retornam PascalCase. Na v2, todas as rotas retornam PascalCase.

Integrações que diferenciam maiúsculas de minúsculas, como aquelas escritas em Python ou JavaScript, não podem ler propriedades de resposta v2 até que as maiúsculas e minúsculas sejam atualizadas.

v1

{
  "classificationResults": [
    {
      "documentTypeId": "invoices",
      "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
      "confidence": 0.6170391,
      "ocrConfidence": -1
    }
  ]
}

v2

{
  "ClassificationResults": [
    {
      "DocumentTypeId": "invoices",
      "DocumentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
      "Confidence": 0.6170391,
      "OcrConfidence": -1
    }
  ]
}

Ação necessária

1. Atualize modelos de resposta e lógica de desserialização para esperar nomes de propriedades PascalCase.
2. Atualize o acesso à propriedade por chave de string, como response["documentId"], para o equivalente do PascalCase.

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