التعافي من الكوارث

ينطبق هذا المحتوى على:v4.0 (معاينة) | الإصدارات السابقة:v3.1 (GA)v3.0 (GA)v2.1 (GA)

عند إنشاء مورد Document Intelligence في مدخل Microsoft Azure، يمكنك تحديد منطقة. من ذلك الحين فصاعداً، تظل مواردك وجميع عملياتها مرتبطة بمنطقة خادم Azure المحددة هذه. من النادر، ولكن ليس من المستحيل، مواجهة مشكلة في الشبكة تضرب منطقة بأكملها. إذا كان الحل الخاص بك بحاجة إلى أن يكون متاحاً دائماً، يجب عليك تصميمه إما لتجاوز الفشل في منطقة أخرى أو تقسيم حِمل العمل بين منطقتين أو أكثر. يتطلب كلا النهجين موردين على الأقل من معلومات المستند في مناطق مختلفة والقدرة على مزامنة النماذج المخصصة عبر المناطق.

تمكن واجهة برمجة تطبيقات النسخ هذا السيناريو من خلال السماح لك بنسخ نماذج مخصصة من حساب Document Intelligence واحد أو إلى حسابات أخرى، والتي يمكن أن توجد في أي منطقة جغرافية مدعومة. يوضح لك هذا الدليل كيفية استخدام Copy REST API مع cURL. يمكنك أيضا استخدام خدمة طلب HTTP لإصدار الطلبات.

سيناريوهات +العمل

إذا كان تطبيقك أو نشاطك التجاري يعتمد على استخدام نموذج مخصص ل Document Intelligence، نوصي بنسخ النموذج الخاص بك إلى حساب Document Intelligence آخر في منطقة أخرى. في حال حدوث انقطاع إقليمي، يمكنك بعد ذلك الوصول إلى النموذج الخاص بك في المنطقة التي تم نسخه فيها.

المتطلبات الأساسية

1. موردان ل Document Intelligence Azure في مناطق Azure مختلفة. إذا لم يكن لديك، فانتقل إلى مدخل Microsoft Azure وأنشئ موردا جديدا ل Document Intelligence.
2. المفتاح وعنوان URL لنقطة النهاية ومعرف الاشتراك لمورد Document Intelligence. يمكنك العثور على هذه القيم في علامة التبويب Overview للمورد في مدخل Microsoft Azure.

نظرة عامة على نسخ API

تتكون عملية نسخ نموذج مخصص من الخطوات التالية:

1. أولا، يمكنك إصدار طلب تخويل نسخ إلى المورد الهدف - أي المورد الذي يتلقى النموذج المنسوخ. تتلقى عنوان URL للنموذج الهدف الذي تم إنشاؤه حديثا الذي يتلقى النموذج المنسخ.
2. بعد ذلك، ترسل طلب النسخ إلى مصدر المورد - المورد الذي يحتوي على النموذج المراد نسخه مع الحمولة (تخويل النسخ) التي تم إرجاعها من الاستدعاء السابق. تتلقى عنوان URL الذي يمكنك الاستعلام فيه لتعقب تقدم العملية.
3. يمكنك استخدام بيانات اعتماد مورد المصدر للاستعلام عن عنوان URL للتقدم حتى يتم نجاح العملية. يمكنك أيضاً الاستعلام عن معرف النموذج الجديد في المورد الهدف للحصول على حالة النموذج الجديد.

إنشاء طلب ترخيص النسخ

يحصل طلب HTTP التالي على إذن نسخة من موردك المستهدف. تحتاج إلى إدخال نقطة النهاية ومفتاح المورد الهدف كعناوين.

POST https://<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

نص الطلب

{
  "modelId": "target-model-name",
  "description": "Copied from SCUS"
}

تتلقى رمز استجابة 200 مع نص استجابة يحتوي على حمولة JSON المطلوبة لبدء النسخة.

{
  "targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
  "targetResourceRegion": "region",
  "targetModelId": "target-model-name",
  "targetModelLocation": "model path",
  "accessToken": "access token",
  "expirationDateTime": "timestamp"
}

بدء عملية النسخ

يبدأ طلب HTTP التالي عملية النسخ على مصدر المورد. تحتاج إلى إدخال نقطة النهاية ومفتاح المورد المصدر الخاص بك كعنوان URL ورأس. لاحظ أن عنوان URL للطلب يحتوي على معرف النموذج الخاص بالنموذج المصدر الذي تريد نسخه.

POST https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

نص طلبك هو الرد من الخطوة السابقة.

{
  "targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
  "targetResourceRegion": "region",
  "targetModelId": "target-model-name",
  "targetModelLocation": "model path",
  "accessToken": "access token",
  "expirationDateTime": "timestamp"
}

تتلقى استجابة 202\Accepted مع عنوان Operation-Location. هذه القيمة هي عنوان URL الذي تستخدمه لتعقب تقدم العملية. انسخه إلى موقع مؤقت للخطوة التالية.

HTTP/1.1 202 Accepted
Operation-Location: https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

إشعار

تدعم Copy API بشفافية ميزة AEK/CMK. لا يتطلب هذا أي عملية خاصة، ولكن لاحظ أنه إذا كنت تنسخ بين مورد غير مشفر إلى مورد مشفر، فأنت بحاجة إلى تضمين رأس الطلب x-ms-forms-copy-degrade: true. إذا لم يتم تضمين هذا الرأس، فستفشل عملية النسخ وستُرجع DataProtectionTransformServiceError.

تتبع تقدم النسخ

GET https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{<operation-id>}?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

تعقب معرف النموذج الهدف

يمكنك أيضا استخدام واجهة برمجة تطبيقات Get model لتعقب حالة العملية عن طريق الاستعلام عن النموذج الهدف. استدعاء واجهة برمجة التطبيقات باستخدام معرف النموذج الهدف الذي نسخته من استجابة طلب تخويل إنشاء نسخة.

GET https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}?api-version=2024-02-29-preview" -H "Ocp-Apim-Subscription-Key: <your-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 لإجراء استدعاءات API. تحتاج أيضا إلى ملء معرفات النموذج ومعلومات الاشتراك الخاصة بمواردك الخاصة.

إنشاء تخويل النسخ

Request

curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'modelId': '{modelId}',
  'description': '{description}'
}"

استجابة ناجحة

{
  "targetResourceId": "string",
  "targetResourceRegion": "string",
  "targetModelId": "string",
  "targetModelLocation": "string",
  "accessToken": "string",
  "expirationDateTime": "string"
}

بدء عملية النسخ

Request

curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'targetResourceId': '{targetResourceId}',
  'targetResourceRegion': {targetResourceRegion}',
  'targetModelId': '{targetModelId}',
  'targetModelLocation': '{targetModelLocation}',
  'accessToken': '{accessToken}',
  'expirationDateTime': '{expirationDateTime}'
}"

استجابة ناجحة

HTTP/1.1 202 Accepted
Operation-Location: https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

تعقب تقدم عملية النسخ

يمكنك استخدام Get operation API لسرد جميع عمليات نموذج المستند (الناجحة أو قيد التقدم أو الفاشلة) المقترنة بمورد Document Intelligence. تستمر معلومات العملية لمدة 24 ساعة فقط. فيما يلي قائمة بالعملية (operationId) التي يمكن إرجاعها:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

تعقب معرف النموذج الهدف

إذا كانت العملية ناجحة، يمكن الوصول إلى نموذج المستند باستخدام واجهات برمجة التطبيقات getModel (الحصول على نموذج واحد)، أو GetModels (الحصول على قائمة بالنماذج).

رسائل رمز الخطأ الشائعة

خطأ	نوع الحل
400/طلب سيّئ مع "code:" "1002"	يشير إلى خطأ في التحقق من الصحة أو طلب نسخة تم تكوينه بشكل سيئ. تشمل المشكلات الشائعة ما يلي: أ) حمولة copyAuthorization غير صالحة أو معدلة. ب) قيمة منتهية الصلاحية لرمز expirationDateTimeTicks (حمولةcopyAuthorization صالحة لمدة 24 ساعة). ج) غير صالح أو غير مدعوم targetResourceRegion. د) سلسلة targetResourceId غير صالحة أو مشوهة.
فشل التخويل بسبب مطالبات التخويل المفقودة أو غير الصالحة.	يحدث عند تعديل الحمولة copyAuthorization أو المحتوى من copyAuthorization واجهة برمجة التطبيقات. تأكد من أن الحمولة هي نفس المحتوى الذي تم إرجاعه من مكالمة copyAuthorization السابقة.
تعذر استرداد بيانات تعريف التخويل.	يشير إلى أنه تتم إعادة استخدام حمولة copyAuthorization مع طلب نسخ. لا يسمح طلب النسخ الذي ينجح بأي طلبات أخرى تستخدم نفس copyAuthorization الحمولة. إذا قمت برفع خطأ منفصل وأعدت محاولة النسخة لاحقا بنفس حمولة التخويل، يتم رفع هذا الخطأ. يتمثل الحل في إنشاء حمولة copyAuthorization جديدة ثم إعادة إصدار طلب النسخ.
لا يسمح بطلب نقل البيانات لأنه يتراجع إلى نظام حماية بيانات أقل أمانا.	يحدث عند النسخ بين مورد AEK ممكّن إلى مورد غير ممكّن AEK. للسماح بنسخ النموذج المشفر إلى الهدف باعتباره غير مشفر، حدد العنوان x-ms-forms-copy-degrade: true مع طلب النسخ.
"تعذر إحضار معلومات للمورد المعرفي باستخدام المعرف...".	يشير إلى أن مورد Azure المشار إليه بواسطة targetResourceId ليس مورداً معرفياً صالحاً أو أنه غير موجود. لحل هذه المشكلة، تحقق من طلب النسخ وأعد إصداره. تأكد من أن المورد صالح وموجود في المنطقة المحددة، مثل، westus2

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

في هذا الدليل، تعلمت كيفية استخدام Copy API لنسخ نماذجك المخصصة احتياطيا إلى مورد ثانوي ل Document Intelligence. بعد ذلك، استكشف مستندات مرجع واجهة برمجة التطبيقات لمعرفة ما يمكنك القيام به أيضا باستخدام Document Intelligence.

• المستندات المرجعية لواجهة برمجة تطبيقات REST