将自动化从 Document Understanding API v1 迁移到 v2

将自动化从 Document Understanding API v1 迁移到 v2，解决重大变更和所需更新，以保持集成正常运行。

从 Document Understanding API v1 升级到 v2 时，将应用以下重大变更。某些更新需要执行操作，以确保您的自动化继续按预期运行。

建议采取以下步骤，将您的自动化从 Document Understanding API v1 迁移到 v2：

1. 更新路由路径。
2. 更新 IXP 提取结果处理（从 Table 到 FieldGroup）。
3. 重建并重新部署到非生产环境。
4. 验证自动化是否在所有四个维度中都按预期运行：
   • 发现、
   • 分类、
   • 提取、
   • 验证。

以下各节详细描述了这些变更以及所需的迁移步骤。

端点路径变更

基于标签的路由已规范化，以提高 API 之间的一致性。

在 v2 中，所有使用之前路径结构的基于标签的端点都返回 400 错误请求。

此变更会影响所有在 {projectId} 之后紧跟 {tag} 的所有操作。

v1

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

v2

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

需要执行的操作

在您的代码库中搜索：/projects/{projectId}/{tag}/

替换为：/projects/{projectId}/tags/{tag}/

确保此更新在所有环境中一致应用。

发现响应架构更改: 已删除fields属性

不再返回 fields 属性。任何反序列化逻辑或引用字段的强类型模型都将失败或返回 null 值。

v1

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

v2

{
  "taxonomy": {
    ...
  }
}

需要执行的操作

1. 更新您的响应模型以使用 taxonomy 对象。
2. 重构之前依赖于 fields 的下游逻辑。

发现响应架构更改： tag已重命名为tags

如果您的模型需要单一 tag 属性，则响应解析可能会失败。 如果您使用严格的架构验证，则需要更新。

v1

{
  "tag": "staging"
}

v2

{
  "tags": ["staging"]
}

需要执行的操作

1. 更新响应模型以将 tag 替换为 tags。
2. 若假定只有一个标签值，则调整逻辑。

IXP 提取结果架构变更：移除表格，且 FieldType.Table 替换为 FieldType.FieldGroup。

此变更仅影响 IXP 提取结果。

在 v1 中，API 将 IXP 提取结果作为一个或多个表格返回。这是将 FieldGroup 的 IXP 概念到表格的一种映射。这些表格中的所有值都表示为文本（字符串），不论其原始 IXP 数据类型如何。

在 v2 中，API 将 IXP 提取结果作为 FieldGroup 返回。这引入了 IXP FieldGroup 概念的 1 对 1 映射。每个字段都保留其实际的 IXP 数据类型（例如 Text、Number、Date、MonetaryQuantity）。

v1（IXP 提取结果作为 Table 返回；值以文本形式表示）

{
  "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（IXP 提取结果作为 FieldGroup 返回；值保留 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": ""
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

• 在 v1 中，方便起见，IXP“类表格”结果在字段数组中表示为 FieldType.Table，并映射到表格结构。
• 在 v2 中，IXP 结果表示为 FieldType.FieldGroup，并作为 FieldGroup 返回（对于 IXP FieldGroup 为 1:1）。任何需要 FieldType.Table 或表格的逻辑都将中断。

需要执行的操作

1. 更新 IXP 提取结果处理，以使用 FieldGroup，而不是 Table。
2. 如果您的自动化将 IXP 提取结果视为表格，请更新解析逻辑，以处理新的 FieldGroup 结构和带类型的字段。
3. 将基于字符串的解析替换为类型感知处理。 例如:
   • Date：解析为日期值
   • Number：解析为数值
   • MonetaryQuantity：将值和货币作为单个数据对象处理

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