オートメーションを Document Understanding API v1 から v2 に移行する

Document Understanding API を v1 から v2 にアップグレードすると、以下の重大な変更が適用されます。一部の更新では、オートメーションを引き続き期待どおりに動作させるための対応が必要です。

以下の手順を実行して、 オートメーションを Document Understanding API v1 から v2 に移行することをお勧めします。

1. ルート パスを更新します。
2. IXP の抽出結果の処理を更新します ( テーブル から フィールド グループへ)。
3. 再構築して非運用環境に再デプロイします。
4. オートメーションが 4 つの次元すべてで期待どおりに動作することを検証します。
   • 発見
   • 分類
   • 抽出
   • 検証。

次のセクションでは、変更点の詳細と必要な移行手順について説明します。

エンドポイント パスの変更

タグベースのルートが正規化され、API 全体の一貫性が向上しました。

以前のパス構造を使用するすべてのタグベースのエンドポイントは、v2 で 400 Bad Request を返します。

この変更は、{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. 以前は ID に依存していた下流のロジックをリファクタリング fields。

検出応答スキーマの変更: tag に名前が変更され tags

モデルが単一の tag プロパティを必要とする場合、応答の解析が失敗する可能性があります。厳密なスキーマ検証を使用している場合は、更新が必要です。

v1

{
  "tag": "staging"
}

v2

{
  "tags": ["staging"]
}

必要なアクション:

1. 回答モデルを更新して、 tag を tagsに置き換えます。
2. 単一のタグ値を想定している場合は、ロジックを調整します。

IXP の抽出結果のスキーマの変更: テーブルが削除され、FieldType.Table が FieldType.FieldGroup に置き換えられる

この変更は、IXP の抽出結果にのみ影響します。

v1 では、API は IXP の抽出結果を 1 つ以上のテーブルとして返していました。これは、IXP のフィールド グループの概念をテーブルにマッピングしたものです。これらのテーブル内の値は、元の IXP のデータ型に関係なく、すべてテキスト (文字列) として表されていました。

v2 では、API は IXP の抽出結果を FieldGroups として返します。これにより、IXP フィールド グループの概念による 1 対 1 のマッピングが導入されます。各フィールドでは、実際の IXP のデータ型 ( Text、 Number、 Date、 MonetaryQuantity など) が保持されます。

v1 (IXP 抽出結果はテーブルとして返され、値はテキストとして表されます)

{
  "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 抽出結果は FieldGroups として返され、値は 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 の「テーブルのような」結果は 、Fields 配列の FieldType.Table として表され、便宜上 テーブル 構造にマップされていました。
• v2 では、IXP の結果は FieldType.FieldGroup として表され、FieldGroups (IXP FieldGroup と 1 対 1) として返されます。FieldType.Table またはテーブルを予期するロジックはすべて壊れます。

必要なアクション

1. IXP の抽出結果の処理を更新して 、テーブル ではなく フィールド グループ を使用するようにします。
2. オートメーションで IXP の抽出結果をテーブルとして扱う場合は、解析ロジックを更新して、新しい FieldGroup 構造体と型指定されたフィールドを処理します。
3. 文字列ベースの解析を型認識処理に置き換えます。例えば：
   • 日付: 日付値として解析します
   • 数値: 数値として解析します
   • MonetaryQuantity: 値と通貨を 1 つのデータ オブジェクトとして処理します。

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