ドキュメント インテリジェンス v4.0 の移行

SDk 移行ガイド

v4.0 SDK を使用するようにアプリケーション コードを更新する方法については、GitHub リポジトリの言語固有の SDK 移行ガイドを参照してください。 これらのガイドでは、新しい API メソッドを呼び出し、v4.0 で導入された更新された応答形式を処理するコードを更新する手順を示します。

• .NET/C# SDK

• Java SDK

• Python SDK

• JavaScript/TypeScript SDK*

v3.1 から v4.0 への移行

プレビュー API は定期的に非推奨になっています。 プレビュー API バージョンを使用している場合は、GA API バージョンをターゲットにするようにアプリケーションを更新します。 SDK を使用してプレビュー API バージョンから 2024-11-30 (GA) API バージョンに移行するには、 言語固有の SDK の現在のバージョンに更新します。

分析機能

✓ - 有効な O - 省略可能な数式/StyleFont/OCR 高解像度* - Premium 機能では追加コストが発生します

v3.0 からの移行

ドキュメント インテリジェンス v3.1 では、v3.0 と比較して、いくつかの新機能が導入されています。

• バーコード の抽出。
• 高解像度、数式、フォント プロパティの抽出などのアドオン機能。
• ドキュメントの分割と分類のためのカスタム分類モデル。
• 請求書および領収書モデルでは、言語拡張と新しいフィールドがサポートされます。
• ID ドキュメント モデルでの新しい ドキュメント の種類のサポート。
• 新しい事前構築済みの 医療保険カード モデル。
• Office/HTML ファイルは事前構築済みの読み取りモデルでサポートされており、境界ボックスを使用せずに単語や段落を抽出します。 埋め込みイメージはサポートされなくなりました。 Office/HTML ファイルに対してアドオン機能が要求された場合、エラーなしで空の配列が返されます。
• カスタム抽出および分類モデルのモデルの有効期限 - 新しいカスタム モデルは、品質向上のために定期的に更新する大規模なベース モデルに基づいて構築されます。 すべてのカスタム モデルに有効期限が導入され、対応する基本モデルの廃止が可能になります。 カスタム モデルの有効期限が切れたら、最新の API バージョン (基本モデル) を使用してモデルを再トレーニングする必要があります。

GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2023-09-24T12:54:35Z",
  "expirationDateTime": "2025-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}

• カスタム ニューラル モデルのビルド クォータ - 各サブスクリプションがリージョンごとにビルドできるニューラル モデルの数は、毎月制限されます。 結果の JSON を拡張してクォータと使用情報を含めることで、GET /info によって返されるリソース情報の一部として現在の使用状況を理解するのに役立ちます。

{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}

• 分析操作に対する省略可能な features クエリ パラメーターは、必要に応じて特定の機能を有効にすることができます。 一部の Premium 機能では、追加の課金が発生する可能性があります。 詳細については、 分析機能の一覧 を参照してください。
• 抽出された通貨フィールド オブジェクトを拡張して、可能な場合は正規化された通貨コード フィールドを出力します。 現在、現在のフィールドは金額 (例: 123.45) と currencySymbol (例: $) を返すことができます。 この機能は、通貨記号を正規の ISO 4217 コード (USD など) にマップします。 必要に応じて、モデルはグローバル ドキュメント コンテンツを利用して、通貨コードを明確にしたり推測したりできます。

{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

モデル品質の向上に加えて、これらの新機能の恩恵を受けるために、v3.1 を使用するようにアプリケーションを更新することを強くお勧めします。

v2.1 または v2.0 からの移行

ドキュメント インテリジェンス v3.1 は、最も豊富な機能、ほとんどの言語とドキュメントの種類のカバレッジ、およびモデル品質の向上を備えた最新の GA バージョンです。 v3.1 で使用できる機能については、 モデルの概要 を参照してください。

v3.0 以降では、 ドキュメント インテリジェンス REST API が再設計され、使いやすさが向上しました。 このセクションでは、ドキュメント インテリジェンス v2.0、v2.1、v3.1 の違いと、新しいバージョンの API に移行する方法について説明します。

REST API エンドポイントの変更

v3.1 REST API は、レイアウト分析、事前構築済みモデル、カスタム モデルの分析操作を 1 組の操作に組み合わせ、documentModelsモデルと事前構築済みモデルにmodelIdとを割り当てます。

POST 要求

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31

GET リクエスト

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31

分析操作

• 要求ペイロードと呼び出しパターンは変更されません。
• Analyze操作では、入力ドキュメントとコンテンツ固有の構成を指定し、応答の Operation-Location ヘッダーを介して分析された結果 URL を返します。
• GET 要求を使用して Analyze Result URL をポーリングして、 Analyze 操作の状態を確認します (要求間の最小推奨間隔は 1 秒です)。
• 成功すると、状態が成功に設定され、応答本文で analyzeResult が返されます。 エラーが発生した場合、状態は failedに設定され、エラーが返されます。

分析要求の本文

分析するコンテンツは、要求本文を介して提供されます。 URL または base64 でエンコードされたデータは、ユーザーが要求を作成できます。

パブリックにアクセスできる Web URL を指定するには、Content-Type を application/json に設定し、次の JSON 本文を送信します。

{
  "urlSource": "{urlPath}"
}

Base 64 エンコードは、ドキュメント インテリジェンス v3.0 でもサポートされています。

{
  "base64Source": "{base64EncodedContent}"
}

追加でサポートされるパラメーター

引き続きサポートされるパラメーター:

• pages : ドキュメント内のページの特定のサブセットのみを分析します。 分析するページ番号の一覧。番号 1 からインデックスが付けられます。 例。 "1-3,5,7-9"
• locale : テキスト認識とドキュメント分析のロケール ヒント。 値には、言語コード (例: en、 fr) または BCP 47 言語タグ (例: "en-US") のみを含めることができます。

パラメーターはサポートされなくなりました。

• テキスト詳細を含める

新しい応答形式はよりコンパクトになり、完全な出力が常に返されます。

結果を分析するための変更

分析応答は、次の最上位レベルの結果にリファクタリングされ、マルチページ要素をサポートします。

• pages
• tables
• keyValuePairs
• entities
• styles
• documents

{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and polygon coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
],
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

モデルの構築またはトレーニング

モデル オブジェクトには、新しい API で 3 つの更新プログラムがあります

• modelId は、人間が判読できる名前のモデルに設定できるプロパティになりました。
• modelName の名前が description に変更されました。
• buildMode は、カスタム フォーム モデルの場合は template 、カスタム ニューラル モデルの場合は neural の値を持つ新しいプロパティです。

モデルをトレーニングするために、 build 操作が呼び出されます。 要求ペイロードと呼び出しパターンは変更されません。 ビルド操作では、モデルとトレーニング データセットを指定し、応答の Operation-Location ヘッダーを介して結果を返します。 GET 要求を使用してこのモデル操作 URL をポーリングして、ビルド操作の状態を確認します (要求間の推奨される最小間隔は 1 秒です)。 v2.1 とは異なり、この URL はモデルのリソースの場所ではありません。 代わりに、指定された modelId からモデル URL を構築できます。また、応答の resourceLocation プロパティから取得することもできます。 成功すると、状態は succeeded に設定され、結果にはカスタム モデル情報が含まれます。 エラーが発生した場合、状態は failed に設定され、エラーが返されます。

次のコードは、SAS トークンを使用したビルド要求のサンプルです。 プレフィックスまたはフォルダー パスを設定するときに、末尾のスラッシュをメモします。

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

作成モデルの変更

モデルの構成は、単一レベルの入れ子に制限されるようになりました。 構成済みモデルは、 modelId プロパティと description プロパティを追加したカスタム モデルと一致するようになりました。

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

モデルのコピーに関する変更

コピー モデルの呼び出しパターンは変更されません。

• authorizeCopyを呼び出すターゲット リソースでコピー操作を承認します。 現在、POST リクエストです。
• ソース リソースに承認を送信し、モデル呼び出し元をコピーする copyTo
• 返された操作をポーリングして、操作が正常に完了したことを検証します

コピー モデル関数の変更点は次だけです。

• authorizeCopyに対する HTTP アクションが POST 要求になりました。
• 承認ペイロードには、コピー要求の送信に必要なすべての情報が含まれています。

コピーを承認する

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

承認アクションからの応答本文を使用して、コピーの要求を作成します。

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

リスト モデルの変更

リスト モデルが拡張され、事前構築済みモデルとカスタム モデルが返されるようになりました。 すべての事前構築済みモデル名は、 prebuilt-で始まります。 状態が成功のモデルのみが返されます。 失敗したモデルまたは進行中のモデルを一覧表示するには、「 操作の一覧表示」を参照してください。

サンプル リスト モデル要求

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

モデル操作を受け取るように変更する

Get Modelに事前構築済みモデルが含まれるようになったので、Get操作はdocTypesディクショナリを返します。 各ドキュメントの種類の説明には、名前、省略可能な説明、フィールド スキーマ、およびオプションのフィールド信頼度が含まれます。 フィールド スキーマは、ドキュメントの種類で返される可能性があるフィールドの一覧を記述します。

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

新しい情報の取得操作

サービスに対する info 操作は、カスタム モデル数とカスタム モデルの制限を返します。

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

応答のサンプル

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

次の手順

• 新しい REST API を確認する
• ドキュメント インテリジェンスとは
• ドキュメント インテリジェンスのクイック スタート 0