表格辨識器 v3.0 移轉

重要

表格辨識器 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 引進數個新功能:

在本文中,您將瞭解 表格辨識器 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 秒)。
  • 成功時,狀態會設定為成功,並在回應本文中傳回 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/}"
  }
}

撰寫模型的變更

模型撰寫現在僅限於單一層級的巢狀。 撰寫的模型現在與具有新增 modelIddescription 屬性的自訂模型一致。

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。