次の方法で共有


Form Recognizer v3.0 への移行

重要

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 では、レイアウト分析 (事前構築済みレイアウト) と事前構築済みモデルに documentModelsmodelId を割り当てることにより、レイアウト分析、事前構築済みモデル、カスタム モデルの分析操作が、操作の単一のペアに結合されています。

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 を使用するようにアップグレードする方法について説明しました。