Migração do Reconhecimento de Formulários v3.0

Importante

A API REST do Reconhecimento de Formulários v 3.0 introduz alterações significativas na solicitação da API REST e analisa o JSON de resposta.

O Reconhecimento de Formulários v3.0 apresenta vários novos recursos e funcionalidades:

Neste artigo, você aprenderá as diferenças entre o Reconhecimento de Formulários v2.1 e v3.0 e como mover para a versão mais recente da API.

Cuidado

  • A versão 2022-08-31 da API REST inclui uma alteração interruptiva no JSON de resposta de análise da API REST.
  • A propriedade boundingBox é renomeada para polygon em cada instância.

Alterações nos pontos de extremidade da API REST

A API REST v3.0 combina as operações de análise de layout, de modelos predefinidos e de modelos personalizados em apenas um par de operações, atribuindo documentModels e modelId à análise de layout (layout predefinido) e modelos predefinidos.

Solicitação POST

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

Solicitação GET

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2022-08-31

Operação de análise

  • O conteúdo de solicitação e o padrão de chamada permanecem inalterados.
  • A operação de análise especifica o documento de entrada e as configurações específicas de conteúdo, retornando a URL de resultado de análise por meio do cabeçalho Operation-Location na resposta.
  • Sonde esta URL de resultado de análise por meio de uma solicitação GET para verificar o status da operação de análise (o intervalo mínimo recomendado entre solicitações é de 1 segundo).
  • Após o êxito, o status é definido como bem-sucedido e analyzeResult é retornado no corpo da resposta. Se forem encontrados erros, o status será definido como failed e um erro será retornado.
Modelar v2.1 v3.0
Prefixo da URL de solicitação https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
N/D /documentModels/prebuilt-document:analyze
Layout /layout/analyze /documentModels/prebuilt-layout:analyze
Personalizado /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Fatura /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Receipt /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Documento de identificação /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Cartão de visita /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 /prebuilt/w-2/analyze /documentModels/prebuilt-w-2:analyze

Analisar o corpo da solicitação

O conteúdo a ser analisado é fornecido por meio do corpo da solicitação. A URL ou os dados codificados em base64 podem ser usados para construir a solicitação.

Para especificar uma URL da Web publicamente acessível, defina o  Content-Type comoapplication/json e envie o corpo do JSON a seguir:

{
  "urlSource": "{urlPath}"
}

A codificação Base64 também tem suporte no Reconhecimento de Formulários v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Parâmetros adicionais com suporte

Parâmetros que continuam com suporte:

  • pages: analise apenas um subconjunto específico de páginas no documento. Lista de números de página indexados do número 1 a ser analisado. Ex.: "1-3,5,7-9"
  • locale: dica de localidade para reconhecimento de texto e análise de documentos. O valor pode conter apenas o código de idioma (ex. "en", "fr") ou a marca de idioma do BCP 47 (ex. "en-US").

Parâmetros que não têm mais suporte:

  • includeTextDetails

O novo formato de resposta é mais compacto e a saída completa sempre é retornada.

Alterações para analisar o resultado

A resposta da análise foi refatorada para os resultados de alto nível a seguir a fim de dar suporte a elementos de várias páginas.

  • pages
  • tables
  • keyValuePairs
  • entities
  • styles
  • documents

Observação

As alterações de resposta do analyzeResult incluem várias alterações, como mover para cima de uma propriedade de páginas para uma propriedade de alavanca superior dentro de 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
}, ...
}
}, ...
]
}

Modelo de compilação ou treinamento

O objeto de modelo tem duas atualizações na nova API

  • modelId agora é uma propriedade que pode ser definida em um modelo para um nome legível humano.
  • modelName foi renomeado para description
  • buildMode é uma nova propriedade com valores template para modelos de formulário personalizados ou neural para modelos neurais personalizados.

A operação build é invocada para treinar um modelo. O conteúdo de solicitação e o padrão de chamada permanecem inalterados. A operação de compilação especifica o modelo e o conjunto de resultados de treinamento, retorna o resultado por meio do cabeçalho Operation-Location na resposta. Sonde esta URL operação de modelo por meio de uma solicitação GET para verificar o status da operação de compilação (o intervalo mínimo recomendado entre solicitações é de 1 segundo). Ao contrário da v2.1, essa URL não é o local do recurso do modelo. Em vez disso, a URL do modelo pode ser construída a partir do modelId fornecido, também recuperada da propriedade resourceLocation na resposta. Após o êxito, o status é definido como succeeded e o resultado contém as informações do modelo personalizado. Se forem encontrados erros, o status será definido como failed e o erro será retornado.

O código a seguir é uma solicitação de compilação de exemplo usando um token SAS. Observe a barra à direita ao definir o prefixo ou o caminho da pasta.

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/}"
  }
}

Alterações no modelo de composição

A composição de modelo agora está limitada a um único nível de aninhamento. Os modelos compostos agora são consistentes com modelos personalizados com a adição de propriedades modelId e description.

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

Alterações no modelo de cópia

O padrão de chamada para o modelo de cópia permanece inalterado:

  • Autorize a operação de cópia com a chamada de recurso de destino authorizeCopy. Agora uma solicitação POST.
  • Enviar a autorização para o recurso de origem para copiar a chamada de modelo copy-to
  • Sondar a operação retornada para validar que a operação foi concluída com êxito

As únicas alterações na função de modelo de cópia são:

  • A ação HTTP na authorizeCopy agora é uma solicitação POST.
  • A carga de autorização contém todas as informações necessárias para enviar a solicitação de cópia.

Autorize a cópia

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

Use o corpo da resposta da ação autorizar para construir a solicitação para a cópia.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copy-to?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"
}

Alterações em modelos de lista

Os modelos de lista foram estendidos para agora retornar modelos predefinidos e personalizados. Todos os nomes de modelo predefinidos começam com prebuilt-. Somente os modelos com um status de êxito são retornados. Para listar modelos que falharam ou estão em andamento, consulte Operações de lista.

Solicitação de modelos de lista de exemplo

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

Alterar para obter o modelo

Como obter modelo agora inclui modelos pré-construídos, a operação get retorna um dicionário docTypes. Cada tipo de documento é descrito por seu nome, descrição opcional, esquema de campo e confiança de campo opcional. O esquema de campo descreve a lista de campos potencialmente retornados com o tipo de documento.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

Nova operação obter informações

A operação info no serviço retorna a contagem de modelos personalizados e o limite de modelo personalizado.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

Resposta de exemplo

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

Próximas etapas

Neste guia de migração, você aprendeu a atualizar seu aplicativo Reconhecimento de Formulários existente para usar as APIs v3.0.