ترحيل الإصدار 3.0 من Form Recognizer

هام

يقدم نموذج واجهة برمجة التطبيقات REST API v3.0 تغييرات كسر في طلب REST API ويحلل استجابة JSON.

يقدم الإصدار 3.0 من Form Recognizer العديد من الميزات والإمكانات الجديدة:

في هذه المقالة، ستتعلم الاختلافات بين نموذج Recognizer v2.1 وv3.0 وكيفية الانتقال إلى الإصدار الأحدث من واجهة برمجة التطبيقات.

تنبيه

  • يتضمن إصدار 2022-08-31 لواجهة برمجة تطبيقات REST تغييرات في النظام تؤدي إلى فشل تحليل واجهة برمجة تطبيقات REST لاستجابة JSON.
  • تتم إعادة تسمية العقار boundingBox إلى polygon في كل حالة.

التغييرات في نقاط نهاية واجهة برمجة التطبيقات REST

تجمع واجهة برمجة تطبيقات REST v3.0 بين عمليات التحليل لتحليل التخطيط، والنماذج المعدة مسبقًا، والنماذج المخصصة في زوج واحد من العمليات من خلال تعيين documentModels و modelId إلى تحليل التخطيط (التخطيط المسبق) والنماذج المعدة مسبقًا.

طلب نشر

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

تحليل العملية

  • تظل حمولة الطلب ونمط الاستدعاء دون تغيير.
  • تحدد عملية Analyze مستند الإدخال والتكوينات الخاصة بالمحتوى، وتعيد عنوان URL لنتيجة التحليل عبر عنوان موقع التشغيل في الاستجابة.
  • قم باستطلاع عنوان URL لنتيجة التحليل هذا، عبر طلب GET للتحقق من حالة عملية التحليل (الحد الأدنى الموصى به للفاصل الزمني بين الطلبات هو 1 ثانية).
  • عند النجاح، يتم تعيين الحالة للنجاح ويتم إرجاع تحليل النتيجة في نص الاستجابة. في حالة حدوث أخطاء، فستُعيّن الحالة إلى failed وسيُرجع خطأ.
النموذج v2.1 الإصدار 3.0
بادئة عنوان URL للطلب https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
المستند العام غير متوفر /documentModels/prebuilt-document:analyze
Layout /layout/analysis /documentModels/prebuilt-layout:analyze
مخصص /custom/{modelId}/analyze /documentModels/{modelId}: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 أو البيانات المشفرة Base 64 مستخدمًا لإنشاء الطلب.

لتحديد عنوان URL للويب متاح للجمهور، قم بتعيين نوع المحتوى على التطبيق/json وأرسل نص JSON التالي:

{
  "urlSource": "{urlPath}"
}

يتم دعم ترميز Base 64 أيضًا في أداة التعرف على النموذج الإصدار 3.0:

{
  "base64Source": "{base64EncodedContent}"
}

معلمات إضافية مدعومة

المعلمات التي لا تزال مدعومة:

  • pages: قم بتحليل مجموعة فرعية محددة فقط من الصفحات في المستند. قائمة بأرقام الصفحات المفهرسة من الرقم 1 للتحليل. مثال. "1-3,5,7-9"
  • locale: تلميح محلي للتعرف على النص وتحليل المستندات. قد تحتوي القيمة فقط على رمز اللغة (مثل "en" أو "fr ") أو علامة لغة BCP 47 (مثل" en - US ").

لم تعد المعلمات مدعومة:

  • includeTextDetails

ويكون شكل الرد الجديد أكثر صغرا، ويتم دائما إرجاع الناتج الكامل.

تغييرات لتحليل النتيجة

تمت إعادة صياغة استجابة Analyze للنتائج التالية ذات المستوى الأعلى لدعم العناصر متعددة الصفحات.

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

ملاحظة

تتضمن تغييرات استجابة AnalysisResult عددًا من التغييرات مثل الانتقال من خاصية الصفحات إلى خاصية الرافعة العلوية ضمن AnalyResult.


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

بناء أو تدريب نموذج

يحتوي كائن النموذج على ثلاثة تحديثات في واجهة برمجة التطبيقات الجديدة

  • modelId هو الآن عقار يمكن تعيينه على نموذج لاسم مقروء للإنسان.
  • تمت إعادة تسميةmodelName إلى description
  • buildMode عبارة عن خاصية جديدة بقيم template لنماذج الاستمارة المخصصة أو neural للنماذج العصبية المخصصة.

يتم اللجوء إلى عملية build لتدريب نموذج. تظل حمولة الطلب ونمط الاستدعاء دون تغيير. تحدد عملية الإنشاء مجموعة بيانات النموذج والتدريب، وترجع النتيجة عبر عنوان Operation-Location في الاستجابة. قم باستطلاع عنوان URL لعملية هذا النموذج، عبر طلب GET للتحقق من حالة عملية الإنشاء (الحد الأدنى الموصى به للفاصل الزمني بين الطلبات هو 1 ثانية). على عكس الإصدار 2.1، فإن عنوان URL هذا ليس موقع المورد للنموذج. بدلاً من ذلك، يمكن إنشاء عنوان URL للنموذج من معرف النموذج المحدد، والذي يتم استرداده أيضًا من خاصية موقع المورد في الاستجابة. عند النجاح، يتم تعيين الحالة إلى 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. الآن طلب وظيفة.
  • إرسال التفويض إلى المورد المصدر لنسخ نموذج الاتصال copy-to
  • استطلاع الرأي حول العملية التي تم إرجاعها للتحقق من اكتمال العملية بنجاح

التغييرات الوحيدة على دالة نموذج النسخ هي:

  • إجراء HTTP على authorizeCopy هو الآن طلب مشاركة.
  • تحتوي حمولة التصريح على جميع المعلومات اللازمة لتقديم طلب النسخ.

تفويض النسخة

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

استخدم نص الرد من إجراء التفويض لإنشاء طلب النسخ.

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

التغييرات في نماذج القوائم

تم توسيع طرز القائمة لإرجاع الطرز السابقة الإنشاء والطرازات المخصصة. تبدأ جميع أسماء الطرازات المصممة مسبقًا بـ prebuilt-. يتم إرجاع النماذج ذات الحالة الناجحة فقط. لقائمة الطرز التي إما فشلت أو قيد التقدم، راجع قائمة العمليات.

طلب نماذج قائمة العينات

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

تغيير للحصول على نموذج

بما أن طراز GET يتضمن الآن نماذج معدة مسبقًا، فإن عملية GET ترجع 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
  }
}

الخطوات التالية

في دليل الترحيل هذا، تعلمت كيفية ترقية تطبيق نموذج Recognizer الحالي خاصتك لاستخدام واجهات برمجة التطبيقات v3.0.