Form Recognizer v3.0 마이그레이션

  • 아티클
  • 읽는 데 15분 걸림

중요

Form Recognizer 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의 현재 버전으로 업데이트합니다.

API에는 2022-08-31 미리 보기 API 버전에서 몇 가지 업데이트가 있습니다.

  • 필드 이름 변경: boundingBox를 다각형으로 변경하여 사변형이 아닌 다각형 영역을 지원합니다.
  • 삭제된 필드: 일반 문서 모델의 결과에서 항목이 제거되었습니다.
  • 필드 이름 변경: documentLanguage.languageCode를 로캘로 변경
  • HEIF 형식에 대한 지원 추가
  • 레이아웃 및 일반 문서 모델에 대한 역할 분류와 함께 단락 검색 기능 추가
  • 구문 분석된 주소 필드에 대한 지원이 추가되었습니다.

v2.1에서 마이그레이션

Form Recognizer 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초).
  • 성공하면 상태가 '성공'으로 설정되고 analyzeResult가 응답 본문에 반환됩니다. 오류가 발생하면 상태가 failed로 설정되고 오류가 반환됩니다.
모델 v2.1 v3.0
요청 URL 접두사 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
일반 문서 해당 없음 /documentModels/prebuilt-document:analyze
레이아웃: /layout/analyze /documentModels/prebuilt-layout:analyze
사용자 지정 /custom/{modelId}/analyze /documentModels/{modelId}:analyze
청구서 /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Receipt /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
ID 문서 /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로 인코딩된 데이터는 요청을 생성하는 사용자일 수 있습니다.

공개적으로 액세스할 수 있는 웹 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

참고

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
}, ...
], // 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를 사용하도록 기존 Form Recognizer 애플리케이션을 업그레이드하는 방법을 알아보았습니다.