表單辨識器 v3.0 遷移 |預覽

重要

表單辨識器 REST API v3.0 引進 REST API 要求中的重大變更,並分析回應 JSON。

表單辨識器 v3.0 (預覽版) 導入了數個新的特性和功能:

在本文中,您將瞭解表單辨識器2.1 和 v3.0 之間的差異,以及如何移至較新版本的 API。

REST API 端點的變更

V3.0 REST API 將配置分析、預建模型和自訂模型的分析作業,藉由指派 documentModels 和配置 modelId 分析 (預建的配置) 和預建模型,將配置分析、預先建立的模型和自訂模型合併成一對作業。

POST 要求

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-07-30-preview

GET 要求

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

分析作業

  • 要求承載和呼叫模式會維持不變。
  • 分析作業會指定輸入檔和內容特定的設定,它會透過回應中的 Operation-Location 標頭傳回分析結果 URL。
  • 透過 GET 要求來輪詢此分析結果 URL,以檢查分析作業的狀態 (要求之間的最小建議間隔為1秒) 。
  • 成功時,狀態會設定為成功,並在回應主體中傳回 analyzeResult 。 如果遇到錯誤,狀態將會設定為 [失敗],並會傳回錯誤。
模型 v2.1 v3.0
要求 URL 首碼 HTTPs://{您的表單辨識器-端點}/formrecognizer/v 2。1 HTTPs://{您的表單辨識器-端點}/formrecognizer
🆕 一般檔 N/A /documentModels/prebuilt-document:分析
版面配置 /layout/analyze /documentModels/prebuilt-layout:分析
Custom /custom/{modelId}/analyze /documentModels/{modelId}:分析
發票 /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:分析
收據 /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:分析
識別碼檔 /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:分析
名片 /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:分析

分析要求本文

要分析的內容是透過要求本文提供。 URL 或 base64 編碼的資料可以是使用者來建立要求。

若要指定可公開存取的 web URL,請將內容類型設定為 application/json,   然後傳送下列 json 主體:

{
  "urlSource": "{urlPath}"
}

表單辨識器 v3.0 也支援 Base64 編碼:

{
  "base64Source": "{base64EncodedContent}"
}

其他參數

繼續支援的參數:

  • 頁面
  • locale

不再支援的參數:

  • includeTextDetails

新的回應格式更為精簡,而且一律會傳回完整輸出。

分析結果的變更

分析回應已重構為下列最上層結果,以支援多個頁面元素。

  • 頁面
  • 資料表
  • keyValuePairs
  • 實體
  • 樣式
  • 文件

注意

AnalyzeResult 回應變更包含一些變更,例如,從頁面的某個屬性往上移至 analyzeResult 內的最上層拉杆屬性。


{
// Basic analyze result metadata
"apiVersion": "2021-07-30-preview", // 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 bounding box 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": [ // Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"boundingBox": [ ... ], // Bounding box
}
],
"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
}, ...
], // List of extracted entities
"entities": [
{
"category": "DateTime", // Primary entity category
"subCategory": "Date", // Secondary entity category
"content": "11/15/2019", // Entity content
"boundingRegions": [ ... ], // Entity bounding regions
"spans": [ ... ], // Entity spans
"confidence": 0.99 // Extraction confidence
}, ...
], // List of extracted styles
"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 中有兩項更新

  • modelId 現在是可在模型上設定的屬性,可供人們讀取的名稱。
  • modelName 已重新命名為 description

build 用作業來定型模型。 要求承載和呼叫模式會維持不變。 組建作業會指定模型和訓練資料集,並透過回應中的 Operation-Location 標頭傳回結果。 透過 GET 要求來輪詢此模型作業 URL,以檢查組建作業的狀態, (要求之間的最小建議間隔為1秒) 。 不同于2.1 版,此 URL 不是模型的資源位置。 相反地,您可以從指定的 modelId 中建立模型 URL,也可以從回應中的 >resourcelocation 屬性抓取。 成功時,狀態會設定為 succeeded ,且結果會包含自訂模型資訊。 如果遇到錯誤,則狀態會設定為, failed 而且會傳回錯誤。

下列程式碼是使用 SAS 權杖的範例組建要求。 設定前置詞或資料夾路徑時,請注意尾端斜線。

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2021-09-30-preview

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

撰寫模型的變更

模型撰寫現在僅限於單一的嵌套層級。 撰寫的模型現在會與自訂模型一致,並加上 modelIddescription 屬性。

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

複製模型的變更

複製模型的呼叫模式會維持不變:

  • 使用呼叫的目標資源來授權複製作業 authorizeCopy 。 現在是 POST 要求。
  • 提交授權給來源資源以複製模型呼叫 copy-to
  • 輪詢傳回的作業以驗證作業已順利完成

複製模型函數的唯一變更為:

  • 上的 HTTP 動作 authorizeCopy 現在是 POST 要求。
  • 授權承載包含提交複製要求所需的所有資訊。

授權複製

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2021-09-30-preview
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

使用授權動作中的回應主體來建立複本的要求。

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copy-to?api-version=2021-09-30-preview
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

變更清單模型

已擴充的清單模型現在會傳回預建和自訂模型。 所有預建模型名稱的開頭都是 prebuilt- 。 只會傳回狀態為 succeeded 的模型。 若要列出失敗或正在進行中的模型,請參閱 清單作業

範例清單模型要求

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2021-09-30-preview

變更為取得模型

因為 get 模型現在包含預建模型,所以 get 作業會傳回 docTypes 字典。 每個檔案類型都是以其名稱、選擇性描述、欄位架構和選擇性欄位信賴方式描述。 欄位架構會描述檔案類型可能傳回的欄位清單。

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview

新的取得資訊操作

服務上的作業會傳回 info 自訂模型計數和自訂模型的限制。

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2021-09-30-preview

範例回應

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

下一步

在此遷移指南中,您已瞭解如何將現有的表單辨識器應用程式升級為使用 v3.0 Api。 繼續針對所有 GA 功能使用 2.1 API,並針對任何預覽功能使用 3.0 API。