Form Recognizer v3.0 への移行

2023-03-24

重要

Form Recognizer REST API v3.0 では、REST API の要求と分析の応答 JSON で破壊的変更が行われています。

v3.0 プレビュー API バージョンからの移行

プレビュー API は定期的に非推奨になっています。プレビュー API バージョンを使用している場合は、使用可能になったら GA API バージョンをターゲットにするようにアプリケーションを更新するよう計画してください。 SDK を使用して 2021-09-30-preview または 2022-01-30-preview API バージョンから 2022-08-31 (GA) API バージョンに移行するには、現在のバージョンの言語固有の SDK に更新します。

2022-08-31 API には、プレビュー API バージョンのいくつかの更新プログラムがあります。

フィールド名の変更: 四角形以外の多角形領域をサポートするために、boundingBox を多角形に変換します。
フィールドの削除: 一般的なドキュメントモデルの結果から削除されたエンティティ。
フィールド名の変更: documentLanguage.languageCode からロケールへ
HEIF 形式のサポートが追加されました
レイアウトモデルと一般的なドキュメントモデルのロール分類を使用して、段落検出を追加しました。
解析されたアドレスフィールドのサポートが追加されました。

v2.1 からの移行

Form Recognizer v3.0 では、次のいくつかの新機能が導入されています。

Form Recognizer REST API は、いっそう使いやすいように再設計されました。
一般ドキュメント (v3.0) モデルは新しい API であり、テキスト、テーブル、構造、キーと値のペアがフォームとドキュメントから抽出されます。
カスタムニューラルモデル (v3.0) は、構造化ドキュメントおよび非構造化ドキュメントからフィールドを抽出するための新しいカスタムモデルの種類です。
領収書 (v3.0) モデルでは、単一ページのホテルの領収書の処理がサポートされます。
身分証明書 (v3.0) モデルでは、米国の運転免許証からの署名、制限、車両分類の抽出がサポートされています。
カスタムモデル API (v3.0) では、カスタムテンプレートモデルの署名検出がサポートされています。
カスタムモデル API (v3.0) では、新しく追加されたすべての事前構築済みモデルの分析がサポートされています。事前構築済みモデルの完全な一覧については、概要ページを参照してください。

この記事では、Form Recognizer v2.1 と v3.0 の違いと、新しいバージョンの API に移行する方法について説明します。

注意事項

REST API 2022-08-31 リリースには、REST API 分析応答 JSON の破壊的変更が含まれています。
boundingBox プロパティは各インスタンスで polygon に名前が変更されます。

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

v3.0 の REST API では、レイアウト分析 (事前構築済みレイアウト) と事前構築済みモデルに documentModels と modelId を割り当てることにより、レイアウト分析、事前構築済みモデル、カスタムモデルの分析操作が、操作の単一のペアに結合されています。

POST 要求

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

GET 要求

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

分析操作

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

モデル	v2.1	v3.0
要求 URL のプレフィックス	https:// /formrecognizer/v2.1	https:///formrecognizer
	該当なし	`/documentModels/prebuilt-document:analyze`
レイアウト	/layout/analyze	`/documentModels/prebuilt-layout:analyze`
カスタム	/custom/<モデル ID>/analyze	`/documentModels/{modelId}:analyze`
請求書	/prebuilt/invoice/analyze	`/documentModels/prebuilt-invoice:analyze`
Receipt	/prebuilt/receipt/analyze	`/documentModels/prebuilt-receipt:analyze`
身分証明書	/prebuilt/idDocument/analyze	`/documentModels/prebuilt-idDocument:analyze`
名刺	/prebuilt/businessCard/analyze	`/documentModels/prebuilt-businessCard:analyze`
W-2	/prebuilt/w-2/analyze	`/documentModels/prebuilt-w-2:analyze`

分析要求の本文

分析対象のコンテンツは、要求本文で提供されます。要求を作成するには、URL または base64 でエンコードされたデータを使用できます。

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

{
  "urlSource": "{urlPath}"
}

base64 エンコードは、Form Recognizer v3.0 でもサポートされています。

{
  "base64Source": "{base64EncodedContent}"
}

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

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

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

サポートされなくなったパラメーター:

includeTextDetails

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

結果の分析に関する変更

分析応答は、複数ページの要素をサポートするため、次の最上位レベルの結果にリファクタリングされています。

pages
tables
keyValuePairs
entities
styles
documents

Note

analyzeResult 応答の変更には、ページのプロパティから analyzeResult 内の最上位レベルのプロパティへの移動など、多くの変更が含まれます。


{
// 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 はモデルのリソースの場所ではありません。代わりに、モデルの URL は、特定の modelId から作成でき、応答の 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

モデルの取得に関する変更

モデルの取得に事前構築済みモデルが含まれるようになったので、取得操作からは 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
  }
}

次のステップ

この移行ガイドでは、既存の Form Recognizer アプリケーションを、v3.0 API を使用するようにアップグレードする方法について説明しました。