النسخ الاحتياطي لنماذج أداة التعرف على النماذج واستردادها
عند إنشاء مورد التعرف على النموذج في مدخل Azure، فإنك تحدد منطقة. ومنذ ذلك الحين فصاعدا، يظل موردك وجميع عملياته مرتبطين بمنطقة خادم Azure المحددة. من النادر ، ولكن ليس من المستحيل ، مواجهة مشكلة في الشبكة تضرب منطقة بأكملها. إذا كان الحل الخاص بك يحتاج إلى أن يكون متاحا دائما ، فيجب عليك تصميمه إما لتجاوز الفشل في منطقة أخرى أو تقسيم عبء العمل بين منطقتين أو أكثر. يتطلب كلا النهجين موردين على الأقل من موارد التعرف على النماذج في مناطق مختلفة والقدرة على مزامنة النماذج المخصصة عبر المناطق.
تمكن واجهة برمجة تطبيقات النسخ هذا السيناريو من خلال السماح لك بنسخ النماذج المخصصة من حساب "التعرف على النماذج" أو إلى حسابات أخرى، والتي يمكن أن توجد في أي منطقة جغرافية معتمدة. يوضح لك هذا الدليل كيفية استخدام واجهة برمجة تطبيقات Copy REST مع cURL. يمكنك أيضا استخدام خدمة طلب HTTP مثل ساعي البريد لإصدار الطلبات.
سيناريوهات الأعمال
إذا كان تطبيقك أو نشاطك التجاري يعتمد على استخدام نموذج مخصص لأداة التعرف على النماذج، نوصيك بنسخ النموذج إلى حساب آخر في أداة التعرف على النماذج في منطقة أخرى. في حالة حدوث انقطاع إقليمي، يمكنك بعد ذلك الوصول إلى النموذج الخاص بك في المنطقة التي تم نسخه فيها.
المتطلبات الأساسية
- Two Form Recognizer Azure resources في مناطق Azure مختلفة. إذا لم يكن لديك هذه العناصر، فانتقل إلى مدخل Azure وقم بإنشاء مورد جديد للتعرف على النماذج .
- المفتاح وعنوان URL لنقطة النهاية ومعرف الاشتراك لمورد "التعرف على النماذج". يمكنك العثور على هذه القيم في علامة التبويب نظرة عامة على المورد على مدخل Azure.
نظرة عامة على واجهة برمجة التطبيقات (API)
تتكون عملية نسخ نموذج مخصص من الخطوات التالية:
- أولا ، تقوم بإصدار طلب تخويل نسخ إلى المورد الهدف - أي المورد الذي سيتلقى النموذج المنسوخ. يمكنك استعادة عنوان URL للنموذج المستهدف الذي تم إنشاؤه حديثا ، والذي سيتلقى البيانات المنسوخة.
- بعد ذلك ترسل طلب النسخ إلى المورد المصدر - المورد الذي يحتوي على النموذج المراد نسخه. ستحصل على عنوان URL يمكنك الاستعلام عنه لتتبع تقدم العملية.
- ستستخدم بيانات اعتماد مورد المصدر للاستعلام عن عنوان URL للتقدم حتى تنجح العملية. يمكنك أيضا الاستعلام عن معرف النموذج الجديد في المورد الهدف للحصول على حالة النموذج الجديد.
إنشاء طلب تفويض نسخ
يحصل طلب HTTP التالي على تفويض نسخ من المورد المستهدف. ستحتاج إلى إدخال نقطة النهاية ومفتاح المورد المستهدف كرؤوس.
POST https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}
ستحصل على 201\Created استجابة ذات modelId قيمة في الجسم. هذه السلسلة هي معرف النموذج (الفارغ) الذي تم إنشاؤه حديثا. accessToken هناك حاجة إلى واجهة برمجة التطبيقات لنسخ البيانات إلى هذا المورد expirationDateTimeTicks ، والقيمة هي انتهاء صلاحية الرمز المميز. احفظ جميع هذه القيم الثلاث في موقع آمن.
HTTP/1.1 201 Created
Location: https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/33f4d42c-cd2f-4e74-b990-a1aeafab5a5d
{"modelId":"<your model ID>","accessToken":"<your access token>","expirationDateTimeTicks":637233481531659440}
بدء عملية النسخ
يبدأ طلب HTTP التالي عملية النسخ على المورد المصدر. ستحتاج إلى إدخال نقطة النهاية ومفتاح مورد المصدر كرؤوس. لاحظ أن عنوان URL للطلب يحتوي على معرف الطراز للنموذج المصدر الذي تريد نسخه.
POST https://{SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/<your model ID>/copy HTTP/1.1
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}
يجب أن يحتوي نص طلبك على التنسيق التالي. ستحتاج إلى إدخال معرف المورد واسم المنطقة للمورد المستهدف. يمكنك العثور على معرف المورد الخاص بك في علامة التبويب خصائص المورد الخاص بك في مدخل Azure، ويمكنك العثور على اسم المنطقة في علامة التبويب المفاتيح ونقطة النهاية . ستحتاج أيضا إلى معرف الطراز ورمز الوصول المميز وقيمة انتهاء الصلاحية التي نسختها من الخطوة السابقة.
{
"targetResourceId": "{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_ID}",
"targetResourceRegion": "{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_REGION_NAME}",
"copyAuthorization": {"modelId":"<your model ID>","accessToken":"<your access token>","expirationDateTimeTicks":637233481531659440}
}
ملاحظة
تدعم واجهة برمجة تطبيقات النسخ بشفافية ميزة AEK/CMK . لا يتطلب هذا أي معاملة خاصة ، ولكن لاحظ أنه إذا كنت تقوم بالنسخ بين مورد غير مشفر إلى مورد مشفر ، فأنت بحاجة إلى تضمين رأس x-ms-forms-copy-degrade: trueالطلب . إذا لم يتم تضمين هذا الرأس، ستفشل عملية النسخ وترجع ملف DataProtectionTransformServiceError.
ستحصل على رد برأس 202\Accepted Operation-Location. هذه القيمة هي عنوان URL الذي ستستخدمه لتتبع تقدم العملية. انسخه إلى موقع مؤقت للخطوة التالية.
HTTP/1.1 202 Accepted
Operation-Location: https://{SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/eccc3f13-8289-4020-ba16-9f1d1374e96f/copyresults/02989ba8-1296-499f-aaf4-55cfff41b8f1
الأخطاء الشائعة
| خطأ | الدقة |
|---|---|
400 / طلب سيئ مع "code:" "1002" |
يشير إلى خطأ في التحقق من الصحة أو طلب نسخ تم تشكيله بشكل سيء. وتشمل المشاكل الشائعة ما يلي: أ) الحمولة غير صالحة أو معدلة copyAuthorization . ب) قيمة منتهية الصلاحية للرمز expirationDateTimeTicks المميز (الحمولةcopyAuhtorization صالحة لمدة 24 ساعة). ج) غير صالح أو غير مدعوم targetResourceRegion. د) سلسلة غير صالحة أو مشوهة targetResourceId . |
تتبع تقدم النسخ
تتبع تقدمك عن طريق الاستعلام عن واجهة برمجة تطبيقات الحصول على نسخة من نتيجة النموذج مقابل نقطة نهاية المورد المصدر.
GET https://{SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/eccc3f13-8289-4020-ba16-9f1d1374e96f/copyresults/02989ba8-1296-499f-aaf4-55cfff41b8f1 HTTP/1.1
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}
ستختلف استجابتك حسب حالة العملية. ابحث عن الحقل "status" في نص JSON. إذا كنت تقوم بأتمتة مكالمة واجهة برمجة التطبيقات هذه في برنامج نصي، فإننا نوصي بالاستعلام عن العملية مرة كل ثانية.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"succeeded","createdDateTime":"2020-04-23T18:18:01.0275043Z","lastUpdatedDateTime":"2020-04-23T18:18:01.0275048Z","copyResult":{}}
الأخطاء الشائعة
| خطأ | الدقة |
|---|---|
| "أخطاء":[{"رمز":"خطأ التفويض", "الرسالة":"فشل التفويض بسبب مطالبات التفويض المفقودة أو غير الصالحة."}] |
يحدث عندما يتم تعديل الحمولة copyAuthorization أو المحتوى مما تم إرجاعه بواسطة copyAuthorization واجهة برمجة التطبيقات. تأكد من أن الحمولة هي نفس المحتوى الدقيق الذي تم إرجاعه من المكالمة السابقة copyAuthorization . |
| "أخطاء":[{"رمز":"خطأ التفويض", "الرسالة":"تعذر استرداد التفويض البيانات الوصفية. إذا استمرت هذه المشكلة ، فاستخدم طريقة مختلفة النموذج المستهدف للنسخ إليه."}] |
يشير إلى أنه يتم إعادة استخدام الحمولة copyAuthorization مع طلب نسخ. لن يسمح طلب النسخ الذي ينجح بأي طلبات أخرى تستخدم نفس copyAuthorization الحمولة. إذا قمت برفع خطأ منفصل (مثل الأخطاء المذكورة أدناه) وقمت لاحقا بإعادة محاولة النسخة بنفس حمولة التفويض، رفع هذا الخطأ. الحل هو إنشاء حمولة جديدة copyAuthorization ثم إعادة إصدار طلب النسخ. |
| "errors":[{"code":"DataProtectionTransformServiceError", "الرسالة":"طلب نقل البيانات غير مسموح به لأنه يخفض إلى نظام حماية البيانات أقل أمانا. إحالة الوثائق أو الاتصال بمسؤول الخدمة لمزيد من التفاصيل."}] |
يحدث عند النسخ بين AEK مورد ممكن إلى مورد غير AEK ممكن. للسماح بنسخ النموذج المشفر إلى الهدف كنموذج غير مشفر ، حدد x-ms-forms-copy-degrade: true الرأس مع طلب النسخ. |
| "أخطاء":[{"رمز":"ResourceResolverError", "الرسالة":"تعذر جلب معلومات للموارد المعرفية باستخدام ID '...'. تأكد من أن المورد صالح وموجود في المنطقة المحددة "westus2".."}] |
يشير إلى أن مورد Azure المشار إليه بواسطة targetResourceId المورد ليس موردا معرفيا صالحا أو غير موجود. تحقق من طلب النسخ وإعادة إصداره لحل هذه المشكلة. |
[اختياري] تتبع معرف النموذج المستهدف
يمكنك أيضا استخدام واجهة برمجة تطبيقات الحصول على نموذج مخصص لتتبع حالة العملية عن طريق الاستعلام عن النموذج الهدف. اتصل بواجهة برمجة التطبيقات هذه باستخدام معرف الطراز المستهدف الذي نسخته في الخطوة الأولى.
GET https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/33f4d42c-cd2f-4e74-b990-a1aeafab5a5d HTTP/1.1
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}
في نص الاستجابة، سترى معلومات حول النموذج. تحقق من الحقل "status" لمعرفة حالة النموذج.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"modelInfo":{"modelId":"33f4d42c-cd2f-4e74-b990-a1aeafab5a5d","status":"ready","createdDateTime":"2020-02-26T16:59:28Z","lastUpdatedDateTime":"2020-02-26T16:59:34Z"},"trainResult":{"trainingDocuments":[{"documentName":"0.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"1.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"2.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"3.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"4.pdf","pages":1,"errors":[],"status":"succeeded"}],"errors":[]}}
نموذج شفرة cURL
تستخدم مقتطفات التعليمات البرمجية التالية cURL لإجراء استدعاءات واجهة برمجة التطبيقات الموضحة في الخطوات أعلاه. ستظل بحاجة إلى ملء معرفات النماذج ومعلومات الاشتراك الخاصة بمواردك الخاصة.
إنشاء طلب تفويض نسخ
curl -i -X POST "https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization" -H "Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}"
بدء عملية النسخ
curl -i -X POST "https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}" --data-ascii "{ \"targetResourceId\": \"{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_ID}\", \"targetResourceRegion\": \"{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_REGION_NAME}\", \"copyAuthorization\": "{\"modelId\":\"33f4d42c-cd2f-4e74-b990-a1aeafab5a5d\",\"accessToken\":\"1855fe23-5ffc-427b-aab2-e5196641502f\",\"expirationDateTimeTicks\":637233481531659440}"}"
تتبع تقدم النسخ
curl -i GET "https://<SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT>/formrecognizer/v2.1/custom/models/{SOURCE_MODELID}/copyResults/{RESULT_ID}" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}"
الخطوات التالية
في هذا الدليل، تعلمت كيفية استخدام نسخ واجهة برمجة التطبيقات لإجراء نسخ احتياطي لنماذجك المخصصة إلى مورد ثانوي للتعرف على النماذج. بعد ذلك، استكشف المستندات المرجعية لواجهة برمجة التطبيقات لمعرفة ما يمكنك فعله باستخدام أداة التعرف على النماذج.