إنشاء عملية طويلة الأمد API V2

تستخدم بعض واجهات برمجة التطبيقات في خرائط Azure نمط Request-Reply غير المتزامن. يسمح هذا النمط لخرائط Azure بتوفير خدمات عالية التوفر وسريعة الاستجابة. تشرح هذه المقالة التنفيذ المحدد لخريطة Azure لمعالجة الخلفية غير المتزامنة طويلة الأمد.

تقديم طلب

يبدأ تطبيق العميل عملية تشغيل طويلة من خلال استدعاء متزامن لواجهة برمجة تطبيقات HTTP. عادةً ما يكون هذا الاستدعاء في شكل طلب HTTP POST. عند إنشاء حمل عمل غير متزامن بنجاح، تقوم واجهة برمجة التطبيقات بإرجاع رمز حالة HTTP 202 ، مما يشير إلى أنه تم قبول الطلب. تحتوي هذه الاستجابة على رأس Location يشير إلى نقطة نهاية يمكن للعميل التحقق منها للتأكد من حالة العملية طويلة المدى.

مثال على استجابة النجاح

Status: 202 Accepted
Operation-Location: https://atlas.microsoft.com/service/operations/{operationId} 

إذا لم ينجح الاستدعاء في التحقق من الصحة، فترجع واجهة برمجة التطبيقات استجابة HTTP 400 لطلب غير صحيح. يوفر نص الاستجابة للعميل المزيد من المعلومات حول سبب عدم صلاحية الطلب.

مراقبة حالة العملية

يمكن التحقق من نقطة نهاية الموقع المتوفرة في رؤوس الاستجابة المقبولة للتحقق من حالة العملية طويلة المدى. يحتوي نص الاستجابة من طلب حالة العملية دائما على status الخصائص و created . الخاصية status تعرض الحالة الحالية للعملية طويلة المدى. تتضمن الحالات المحتملة "NotStarted" و"Running" و"Succeeded" و"Failed". الخاصية created تعرض الوقت الذي تم فيه تقديم الطلب الأولي لبدء العملية طويلة المدى. عندما تكون الحالة إما "NotStarted" أو "Running"، Retry-After يتم توفير عنوان أيضا مع الاستجابة. يمكن استخدام الرأس Retry-After، الذي يتم قياسه بالثواني، لتحديد متى يجب إجراء استدعاء التحقق التالي لحالة العملية API.

مثال على تشغيل استجابة الحالة

Status: 200 OK
Retry-After: 30
{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "3/11/2020 8:45:13 PM +00:00",
    "status": "Running"
}

التعامل مع إكمال العملية

بمجرد اكتمال العملية طويلة الأمد، تكون حالة الاستجابة إما "Succeeded" أو "Failed". ترجع جميع الاستجابات رمز HTTP 200 OK. عند إنشاء مورد جديد من عملية طويلة الأمد، تحتوي الاستجابة أيضا على Resource-Location عنوان يشير إلى بيانات التعريف حول المورد. عند الفشل، يكون للاستجابة error خاصية في الجسم. تلتزم بيانات الخطأ بمواصفات خطأ OData.

مثال على استجابة النجاح

Status: 200 OK
Resource-Location: "https://atlas.microsoft.com/tileset/{tileset-id}"
 {
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "2021-05-06T07:55:19.5256829+00:00",
    "status": "Succeeded"
}

مثال على استجابة الفشل

Status: 200 OK

{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "3/11/2020 8:45:13 PM +00:00",
    "status": "Failed",
    "error": {
        "code": "InvalidFeature",
        "message": "The provided feature is invalid.",
        "details": {
            "code": "NoGeometry",
            "message": "No geometry was provided with the feature."
        }
    }
}