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

オートメーションを Document Understanding API v1 から v2 に移行し、重大な変更と必要な更新に対応し、連携を機能させ続けます。

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

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

1. 応答プロパティの大文字と小文字を更新します (キャメルケースからパスカルケースに)。
2. ルート パスを更新します。
3. IXP の抽出結果の処理を更新します (Tables から FieldGroup に更新します)。
4. 再構築して非運用環境に再デプロイします。
5. オートメーションが以下の 4 つの側面すべてで期待どおりに動作することを検証します。
   • 発見
   • 分類
   • 抽出
   • 検証

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

応答プロパティの大文字と小文字: CamelCase が PascalCase に置き換えられました。

すべての v2 ルートの応答本文では、PascalCase プロパティ名が使用されます。

v1 では、ルート間で大文字と小文字の区別に一貫性がありません。フレームワークの分類、抽出、および検証のルートは、キャメルケースのプロパティ名を返し、生成 AI による抽出と IXP の抽出結果はパスカルケースを返します。v2 では、すべてのルートが PascalCase を返します。

Python や JavaScript で記述された連携など、大文字と小文字を区別する連携では、大文字と小文字が更新されるまで v2 の応答プロパティを読み取ることができません。

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

必要なアクション

1. 応答モデルと逆シリアル化ロジックを更新して、PascalCase のプロパティ名を予期させます。
2. プロパティへのアクセスを文字列キー ( response["documentId"]など) でパスカルケースに対応するものに更新します。

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

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 プロパティは返されなくなりました。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. 単一の tag 値を想定している場合は、ロジックを調整します。

IXP の抽出結果のスキーマの変更: Tables の削除、FieldType.FieldGroup による FieldType.Table の置き換え

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

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

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

v1 (IXP の抽出結果は Tables として返され、値はテキストとして表される)

{
  "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 の「表形式」の結果は、Fields 配列の FieldType.Table として表されており、利便性のために tables 構造にマッピングされていました。
• v2 では、IXP の結果は FieldType.FieldGroup として表され、FieldGroups (IXP FieldGroup と 1 対 1) として返されます。FieldType.Table またはテーブルを予期するロジックはすべて壊れます。

必要なアクション

1. Table ではなく FieldGroup を使用するように IXP の抽出結果の処理を更新します。
2. オートメーションで IXP の抽出結果を表として扱う場合は、新しい FieldGroup 構造と型指定されたフィールドを処理するように解析ロジックを更新します。
3. 文字列ベースの解析を、型を認識する処理に置き換えます。たとえば、次のとおりです。
   • Date: 日付値として解析します。
   • Number: 数値として解析します。
   • 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": ""
    }
  ]
}