表格辨識器 v3.0 移轉

發行項
01/26/2023

重要

表格辨識器 REST API v3.0 引進 REST API 要求中的中斷性變更，並分析回應 JSON。

從 v3.0 預覽 API 版本移轉

預覽 API 會定期淘汰。如果您使用預覽 API 版本，請規劃更新您的應用程式，以推出之後的 GA API 版本為目標。若要從 2021-09-30-preview 或 2022-01-30-preview API 版本移轉至 2022-08-31 使用 SDK 的 (GA) API 版本，請更新為目前的語言特定 SDK 版本。

2022-08-31API 有一些來自預覽 API 版本的更新：

欄位重新命名：將 boundingBox 重新命名為 polygon，以支援非四邊形的多邊形區域。
欄位已刪除：已從一般文件模型的結果中移除實體。
欄位重新命名：將 documentLanguage.languageCode 重新命名為 locale
已新增對 HEIF 格式的支援
已新增段落偵測，其中包含適用於配置和一般文件模型的角色分類
已新增對已剖析位址欄位的支援。

從 v2.1 移轉

表格辨識器 v3.0 引進數個新功能：

表格辨識器 REST API 已經過重新設計，以提升可用性。
一般文件 (v3.0) 模型是新的 API，可從表單和文件中擷取文字、資料表、結構和索引鍵/值組。
自訂神經模型 (v3.0) 是新的自訂模型類型，可從結構化和非結構化文件擷取欄位。
收據 (v3.0) 模型支援單頁旅館收據處理。
識別碼文件 (v3.0) 模型支援從美國駕照擷取違規記錄、限制和車輛分類。
自訂模型 API (v3.0) 支援自訂範本模型的簽章偵測。
自訂模型 API (v3.0) 支援分析所有新增的預建模型。如需預先建置模型的完整清單，請參閱 [概觀] 頁面。

在本文中，您將瞭解表格辨識器 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 秒)。
成功時，狀態會設定為成功，並在回應本文中傳回 analyzeResult。如果發生錯誤，狀態會設定為 failed，並傳回錯誤。

模型	v2.1	v3.0
要求 URL 首碼	https://{your-form-recognizer-endpoint}/formrecognizer/v2.1	https://{your-form-recognizer-endpoint}/formrecognizer
一般文件	N/A	`/documentModels/prebuilt-document:analyze`
版面配置	/layout/analyze	`/documentModels/prebuilt-layout:analyze`
Custom	/custom/{modelId}/analyze	`/documentModels/{modelId}:analyze`
發票	/prebuilt/invoice/analyze	`/documentModels/prebuilt-invoice:analyze`
收據	/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}"
}

表格辨識器 v3.0 中也支援 Base64 編碼：

{
  "base64Source": "{base64EncodedContent}"
}

其他支援的參數

繼續提供支援的參數：

pages：僅分析文件中的特定頁面子集。從要分析的數字 1 編製索引的頁碼清單。例如 "1-3,5,7-9"
locale：文字辨識和文件分析的地區設定提示。值只能包含語言代碼 (例如「en」、「fr」) 或 BCP 47 語言標記 (例如「en-US」)。

不再支援的參數：

includeTextDetails

新的回應格式比較精簡，且一律會傳回完整輸出。

分析結果的變更

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

pages
tables
keyValuePairs
entities
styles
documents

注意

analyzeResult 回應變更包含許多變更，例如從頁面的屬性向上移動至 analyzeResult 內頂端的 lever 屬性。


{
// 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
}, ...
], // 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
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
  }
}

下一步

在此移轉指南中，您已瞭解如何升級現有的表格辨識器應用程式以使用 v3.0 API。