Migrasi Form Recognizer v3.0

Penting

Form Recognizer REST API v3.0 memperkenalkan perubahan signifikan dalam permintaan REST API dan menganalisis respons JSON.

Form Recognizer v3.0 memperkenalkan sejumlah fitur dan kemampuan baru:

Pada artikel ini, Anda akan mempelajari perbedaan antara Form Recognizer v2.1 dan v3.0, serta cara beralih ke versi API yang lebih baru.

Perhatian

  • Rilis 2022-08-31 REST API meliputi perubahan yang dapat menyebabkan gangguan dalam JSON respons analisis REST API.
  • Properti boundingBox diganti namanya menjadi polygon di setiap instans.

Perubahan pada titik akhir REST API

REST API v3.0 menggabungkan operasi analisis untuk analisis tata letak, model bawaan, dan model kustom ke dalam satu pasang operasi dengan menetapkan documentModels dan modelId untuk analisis tata letak (tata letak bawaan) dan model bawaan.

Permintaan POST

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

Permintaan GET

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

Operasi Analyze

  • Payload permintaan dan pola panggilan tetap tidak berubah.
  • Operasi Analyze menentukan dokumen input dan konfigurasi khusus konten, operasi ini mengembalikan URL hasil analisis melalui header Operation-Location dalam respons.
  • Polling URL Hasil Analisis ini, melalui permintaan GET untuk memeriksa status operasi analisis (interval minimum yang disarankan antara permintaan adalah 1 detik).
  • Setelah sukses, status diatur ke berhasil dan analyzeResult dikembalikan dalam badan respons. Jika kesalahan ditemukan, status akan ditetapkan ke failed, dan kesalahan akan ditampilkan.
Model v2.1 v3.0
Meminta prefiks URL https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Dokumen umum T/A /documentModels/prebuilt-document:analyze
Layout /layout/analyze /documentModels/prebuilt-layout:analyze
Kustom /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Faktur /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Tanda Terima /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Dokumen ID /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Kartu nama /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 /prebuilt/w-2/analyze /documentModels/prebuilt-w-2:analyze

Menganalisis badan permintaan

Konten yang akan dianalisis disediakan melalui badan permintaan. Baik URL atau data yang dikodekan base64 dapat digunakan untuk membuat permintaan.

Untuk menentukan URL web yang dapat diakses publik, atur Jenis Konten keapplication/json dan kirim isi JSON berikut:

{
  "urlSource": "{urlPath}"
}

Pengodean Base64 juga didukung dalam Form Recognizer v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Parameter tambahan yang didukung

Parameter yang terus didukung:

  • pages : Hanya menganalisis subset halaman tertentu dalam dokumen. Daftar nomor halaman yang diindeks dari angka 1 untuk dianalisis. Mis. "1-3,5,7-9"
  • locale : Petunjuk lokal untuk pengenalan teks dan analisis dokumen. Nilai hanya boleh berisi kode bahasa (mis. "en", "fr") atau tag bahasa BCP 47 (mis. "en-US").

Paramater yang tidak lagi didukung:

  • includeTextDetails

Format respons baru lebih ringkas dan output penuh selalu dikembalikan.

Perubahan untuk hasil analisis

Respons analisis telah direfaktor ke hasil tingkat atas berikut untuk mendukung elemen multihalaman.

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

Catatan

Perubahan respons AnalyzeResult mencakup sejumlah perubahan seperti naik dari properti halaman ke properti tingkat atas dalam 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
}, ...
}
}, ...
]
}

Membangun atau melatih model

Objek model memiliki tiga pembaruan di API baru

  • modelId sekarang adalah properti yang dapat diatur pada model untuk nama yang dapat dibaca manusia.
  • modelName telah diubah namanya menjadi description
  • buildMode adalah properti dengan nilai template untuk model formulir kustom neural untuk model neural kustom.

Operasi build ini dipanggil untuk melatih model. Payload permintaan dan pola panggilan tetap tidak berubah. Operasi build menentukan model dan himpunan data pelatihan, yang mengembalikan hasilnya melalui header Operation-Location dalam respons. Polling URL operasi model ini, melalui permintaan GET untuk memeriksa status operasi build (interval minimum yang disarankan antara permintaan adalah 1 detik). Tidak seperti v2.1, URL ini bukan lokasi sumber daya model. Sebagai gantinya, URL model dapat dibangun dari modelId yang diberikan, juga diambil dari properti resourceLocation dalam respons. Setelah sukses, status diatur ke succeeded dan hasilnya berisi info model kustom. Jika kesalahan ditemukan, status ditetapkan ke failed dan kesalahan akan ditampilkan.

Kode berikut adalah permintaan build sampel menggunakan token SAS. Perhatikan garis miring belakangnya saat mengatur awalan atau jalur folder.

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

Perubahan untuk compose

Model compose sekarang terbatas pada satu tingkat dimensi. Model yang disusun sekarang konsisten dengan model kustom dengan penambahan properti modelId dan description.

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

Perubahan pada model salin

Pola panggilan untuk model salin tetap tidak berubah:

  • Otorisasi operasi salin dengan panggilan sumber daya target authorizeCopy. Sekarang permintaan POST.
  • Kirimkan otorisasi ke sumber daya sumber untuk menyalin panggilan model copy-to
  • Polling operasi yang dikembalikan untuk memvalidasi operasi berhasil selesai

Satu-satunya perubahan pada fungsi model salin adalah:

  • Tindakan HTTP pada authorizeCopy sekarang adalah permintaan POST.
  • Payload otorisasi berisi semua informasi yang diperlukan untuk mengirimkan permintaan salin.

Mengotorisasi salinan

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

Gunakan badan respons dari tindakan otorisasi untuk membangun permintaan untuk salinan.

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

Perubahan pada model daftar

Model Daftar telah diperluas untuk mengembalikan model bawaan dan kustom. Semua nama model bawaan dimulai dengan prebuilt-. Hanya model dengan status berhasil yang dikembalikan. Untuk membuat daftar model yang gagal atau sedang berlangsung, lihat Operasi Daftar.

Sampel permintaan model daftar

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

Perubahan untuk model GET

Karena model get sekarang mencakup model bawaan, operasi get mengembalikan kamus docTypes. Setiap jenis dokumen dijelaskan dengan namanya, deskripsi opsional, skema bidang, dan keyakinan bidang opsional. Skema bidang menjelaskan daftar bidang yang berpotensi dikembalikan dengan jenis dokumen.

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

Operasi get info baru

Operasi info pada layanan mengembalikan jumlah model kustom dan batas model kustom.

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

Respons sampel

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

Langkah berikutnya

Dalam panduan migrasi ini, Anda telah mempelajari cara memutakhirkan aplikasi Form Recognizer yang ada untuk menggunakan API v3.0.