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

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

طلبات المعالجة

ضع في اعتبارك النقاط التالية عند تنفيذ التعليمة البرمجية للتعامل مع الطلبات.

يجب أن تكون إجراءات GET وPUT وDELETE وHEAD وPATCH خاملة

يجب ألا تفرض التعليمة البرمجية التي تنفذ هذه الطلبات أي آثار جانبية. يجب أن يؤدي تكرار الطلب نفسه على نفس المورد إلى نفس الحالة. على سبيل المثال، يجب أن يكون لإرسال طلبات DELETE متعددة إلى نفس URI نفس التأثير، على الرغم من أن رمز حالة HTTP في رسائل الاستجابة قد يكون مختلفا. قد يُرجع طلب DELETE الأول تعليمة برمجية الحالة 204 (لا يوجد محتوى)، بينما قد يُرجع طلب DELETE اللاحق التعليمة البرمجية لحالة 404 (لم يتم العثور عليه).

إشعار

تقدم المقالة أنماط Idempotency في مدونة جوناثان أوليفر نظرة عامة على العاطفة وكيفية ارتباطها بعمليات إدارة البيانات.

لا ينبغي أن يكون لإجراءات POST التي تنشئ موارد جديدة آثار جانبية غير ذات صلة

إذا كان الغرض من طلب POST هو إنشاء مورد جديد، يجب أن تقتصر آثار الطلب على المورد الجديد (وربما أي موارد ذات صلة مباشرة إذا كان هناك نوع من الروابط المعنية). على سبيل المثال، في نظام التجارة الإلكترونية، قد يقوم طلب POST الذي ينشئ طلب جديد للعميل بتعديل مستويات المخزون وإنشاء معلومات الفوترة، ولكن يجب ألا يعدل المعلومات غير المرتبطة مباشرة بالطلب أو أن يكون له أي آثار جانبية أخرى على الحالة العامة للنظام.

تجنب تنفيذ عمليات الدردشة POST وPUT وDELETE

دعم طلبات POST وPUT وDELETE عبر مجموعات الموارد. يمكن أن يحتوي طلب POST على تفاصيل عدة موارد جديدة وإضافتها جميعاً إلى المجموعة نفسها، ويمكن أن يحل طلب PUT محل مجموعة الموارد الكاملة في مجموعة، ويمكن لطلب DELETE إزالة مجموعة كاملة.

يوفر دعم OData المضمن في ASP.NET Web API 2 القدرة على تجميع الطلبات. يمكن لتطبيق العميل حزم العديد من طلبات واجهة برمجة تطبيقات الويب وإرسالها إلى الخادم في طلب HTTP واحد، وتلقي استجابة HTTP واحدة تحتوي على الردود على كل طلب. لمزيد من المعلومات، راجع تقديم دعم الدفعة في واجهة برمجة تطبيقات الويب وواجهة برمجة تطبيقات الويب OData.

اتبع مواصفات HTTP عند إرسال رد

يجب أن تقوم واجهة برمجة تطبيقات الويب بإرجاع الرسائل التي تحتوي على التعليمة البرمجية لحالة HTTP الصحيح لتمكين العميل من تحديد كيفية التعامل مع النتيجة، ورؤوس HTTP المناسبة حتى يفهم العميل طبيعة النتيجة، وهيئة منسقة بشكل مناسب لتمكين العميل من توزيع النتيجة.

على سبيل المثال، يجب أن تقوم عملية POST بإرجاع التعليمة البرمجية لحالة 201 (تم الإنشاء) ويجب أن تتضمن رسالة الاستجابة URI للمورد الذي تم إنشاؤه حديثاً في عنوان الموقع لرسالة الاستجابة.

دعم التفاوض على المحتوى

قد يحتوي نص رسالة الرد على بيانات بتنسيقات متنوعة. على سبيل المثال، يمكن لطلب HTTP GET إرجاع البيانات بتنسيق JSON أو XML. عندما يرسل العميل طلباً، يمكنه تضمين رأس قبول يحدد تنسيقات البيانات التي يمكنه التعامل معها. يتم تحديد هذه التنسيقات كأنواع وسائط. على سبيل المثال، يمكن للعميل الذي يُصدر طلب GET لاسترداد صورة تحديد رأس قبول يسرد أنواع الوسائط التي يمكن للعميل معالجتها، مثل image/jpeg, image/gif, image/png. عندما تعرض واجهة برمجة تطبيقات الويب النتيجة، يجب تنسيق البيانات باستخدام أحد أنواع الوسائط هذه وتحديد التنسيق في رأس نوع المحتوى للاستجابة.

إذا لم يحدد العميل عنوان قبول، فاستخدم تنسيقاً افتراضياً معقولاً لنص الاستجابة. كمثال، يتم تعيين إطار عمل ASP.NET Web API افتراضياً على JSON للبيانات المستندة إلى النص.

توفير روابط لدعم التنقل على غرار HATEOAS واكتشاف الموارد

يمكّن نهج HATEOAS العميل من التنقل واكتشاف الموارد من نقطة البداية الأولية. يتم تحقيق ذلك باستخدام الروابط التي تحتوي على URIs؛ عندما يصدر العميل طلب HTTP GET للحصول على مورد، يجب أن تحتوي الاستجابة على URIs التي تمكن تطبيق العميل من تحديد موقع أي موارد ذات صلة مباشرة بسرعة. على سبيل المثال، في واجهة برمجة تطبيقات الويب التي تدعم حل التجارة الإلكترونية، قد يكون العميل قد قدم العديد من الطلبات. عندما يقوم تطبيق العميل باسترداد التفاصيل الخاصة بالعميل، يجب أن تتضمن الاستجابة روابط تمكن تطبيق العميل من إرسال طلبات HTTP GET التي يمكنها استرداد هذه الطلبات. بالإضافة إلى ذلك، يجب أن تصف الروابط على غرار HATEOAS العمليات الأخرى (POST، PUT، DELETE، وما إلى ذلك) التي يدعمها كل مورد مرتبط مع URI المقابل لتنفيذ كل طلب. تم وصف هذا الأسلوب بمزيد من التفصيل في تصميم واجهة برمجة التطبيقات.

لا توجد حالياً معايير تحكم تنفيذ HATEOAS، ولكن المثال التالي يوضح نهجاً واحداً ممكناً. في هذا المثال، يقوم طلب HTTP GET الذي يبحث عن التفاصيل الخاصة بعميل بإرجاع استجابة تتضمن روابط HATEOAS التي تشير إلى الطلبات الخاصة بهذا العميل:

GET https://adventure-works.com/customers/2 HTTP/1.1
Accept: text/json
...

HTTP/1.1 200 OK
...
Content-Type: application/json; charset=utf-8
...
Content-Length: ...
{"CustomerID":2,"CustomerName":"Bert","Links":[
    {"rel":"self",
    "href":"https://adventure-works.com/customers/2",
    "action":"GET",
    "types":["text/xml","application/json"]},
    {"rel":"self",
    "href":"https://adventure-works.com/customers/2",
    "action":"PUT",
    "types":["application/x-www-form-urlencoded"]},
    {"rel":"self",
    "href":"https://adventure-works.com/customers/2",
    "action":"DELETE",
    "types":[]},
    {"rel":"orders",
    "href":"https://adventure-works.com/customers/2/orders",
    "action":"GET",
    "types":["text/xml","application/json"]},
    {"rel":"orders",
    "href":"https://adventure-works.com/customers/2/orders",
    "action":"POST",
    "types":["application/x-www-form-urlencoded"]}
]}

في هذا المثال، يتم تمثيل بيانات العميل من خلال الفئة Customer الموضحة في قصاصة برمجية التعليمة البرمجية التالي. روابط HATEOAS محفوظة في Links خاصية المجموعة:

public class Customer
{
    public int CustomerID { get; set; }
    public string CustomerName { get; set; }
    public List<Link> Links { get; set; }
    ...
}

public class Link
{
    public string Rel { get; set; }
    public string Href { get; set; }
    public string Action { get; set; }
    public string [] Types { get; set; }
}

تقوم عملية HTTP GET باسترداد بيانات العميل من التخزين وإنشاء عنصر Customer، ثم ملء مجموعة Links. يتم تنسيق النتيجة كرسالة استجابة JSON. يتضمن كل ارتباط الحقول التالية:

• العلاقة (Rel) بين الكائن الذي يتم إرجاعه والعنصر الموضح بواسطة الارتباط. في هذه الحالة، يشير self إلى أن الرابط هو إشارة إلى العنصر نفسه (على غرار this المؤشر في العديد من اللغات الموجهة للعناصر)، وorders هو اسم مجموعة تحتوي على معلومات الترتيب ذات الصلة.
• الارتباط التشعبي (Href) للعنصر الموصوف بواسطة الارتباط في شكل URI.
• نوع طلب HTTP (Action) الذي يمكن إرساله إلى URI هذا.
• تنسيق أي بيانات (Types) يجب توفيرها في طلب HTTP أو التي يمكن إرجاعها في الاستجابة، اعتماداً على نوع الطلب.

تشير روابط HATEOAS الموضحة في مثال استجابة HTTP إلى أن تطبيق العميل يمكنه تنفيذ العمليات التالية:

• طلب HTTP GET إلى URI https://adventure-works.com/customers/2 لجلب تفاصيل العميل (مرة أخرى). يمكن إرجاع البيانات بتنسيق XML أو JSON.
• طلب HTTP PUT إلى URI https://adventure-works.com/customers/2 لتعديل تفاصيل العميل. يجب تقديم البيانات الجديدة في رسالة الطلب بتنسيق x-www-form-urlencoded.
• طلب HTTP DELETE إلى URI https://adventure-works.com/customers/2 لحذف العميل. لا يتوقع الطلب أي معلومات إضافية أو إرجاع بيانات في نص رسالة الرد.
• طلب HTTP GET إلى URI https://adventure-works.com/customers/2/orders للعثور على جميع أوامر العميل. يمكن إرجاع البيانات بتنسيق XML أو JSON.
• طلب HTTP POST إلى URI https://adventure-works.com/customers/2/orders لإنشاء طلب جديد لهذا العميل. يجب تقديم البيانات في رسالة الطلب بتنسيق x-www-form-urlencoded.

معالجة الاستثناءات

ضع في اعتبارك النقاط التالية إذا أسفرت العملية عن استثناء غير معلوم.

التقط الاستثناءات وقم بإرجاع استجابة ذات مغزى للعملاء

يجب أن توفر التعليمة البرمجية التي تنفذ عملية HTTP معالجة استثناء شاملة بدلاً من السماح بانتشار الاستثناءات غير المعلنة في إطار العمل. إذا كان هناك استثناء يجعل من المستحيل إكمال العملية بنجاح، يمكن تمرير الاستثناء مرة أخرى في رسالة الاستجابة، ولكن يجب أن يتضمن وصفاً ذا مغزى للخطأ الذي تسبب في حدوث الاستثناء. يجب أن يتضمن الاستثناء أيضاً التعليمة البرمجية لحالة HTTP المناسب بدلاً من مجرد إرجاع التعليمة البرمجية لحالة 500 لكل موقف. على سبيل المثال، إذا تسبب طلب مستخدم في تحديث قاعدة بيانات ينتهك أحد القيود (مثل محاولة حذف عميل لديه طلبات معلقة)، يجب عليك إرجاع التعليمة البرمجية لحالة 409 (تعارض) ونص رسالة يشير إلى سبب التعارض. إذا كان هناك شرط آخر يجعل الطلب غير قابل للتحقيق، يمكنك إرجاع التعليمة البرمجية للحالة 400 (طلب غير صالح). يمكنك العثور على قائمة كاملة بالتعليمة البرمجية لحالة HTTP في صفحة تعريفات تعليمة برمجية الحالة على موقع W3C على الويب.

يقوم مثال التعليمة البرمجية بتعويض شروط مختلفة وإرجاع استجابة مناسبة.

[HttpDelete]
[Route("customers/{id:int}")]
public IHttpActionResult DeleteCustomer(int id)
{
    try
    {
        // Find the customer to be deleted in the repository
        var customerToDelete = repository.GetCustomer(id);

        // If there is no such customer, return an error response
        // with status code 404 (Not Found)
        if (customerToDelete == null)
        {
            return NotFound();
        }

        // Remove the customer from the repository
        // The DeleteCustomer method returns true if the customer
        // was successfully deleted
        if (repository.DeleteCustomer(id))
        {
            // Return a response message with status code 204 (No Content)
            // To indicate that the operation was successful
            return StatusCode(HttpStatusCode.NoContent);
        }
        else
        {
            // Otherwise return a 400 (Bad Request) error response
            return BadRequest(Strings.CustomerNotDeleted);
        }
    }
    catch
    {
        // If an uncaught exception occurs, return an error response
        // with status code 500 (Internal Server Error)
        return InternalServerError();
    }
}

تلميح

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

تقوم العديد من خوادم الويب بتعويض ظروف الخطأ نفسها قبل أن تصل إلى واجهة برمجة تطبيقات الويب. على سبيل المثال، إذا قمت بتكوين المصادقة لموقع ويب وفشل المستخدم في توفير معلومات المصادقة الصحيحة، يجب أن يستجيب خادم الويب بالتعليمة البرمجية لحالة 401 (غير مصرح به). بمجرد مصادقة العميل، يمكن للتعليمة البرمجية الخاصة بك إجراء فحوصات خاصة به للتحقق من أن العميل يجب أن يكون قادراً على الوصول إلى المورد المطلوب. إذا فشل هذا التفويض، يجب عليك إرجاع التعليمة البرمجية لحالة 403 (ممنوع).

تعامل مع الاستثناءات بشكل متسق وسجل المعلومات بشأن الأخطاء

للتعامل مع الاستثناءات بطريقة متسقة، ضع في اعتبارك تنفيذ إستراتيجية عالمية لمعالجة الأخطاء عبر واجهة برمجة تطبيقات الويب بالكامل. يجب عليك أيضاً تضمين تسجيل الأخطاء الذي يلتقط التفاصيل الكاملة لكل استثناء؛ يمكن أن يحتوي سجل الأخطاء هذا على معلومات مفصلة طالما لا يمكن الوصول إليها عبر الويب للعملاء.

التمييز بين أخطاء العميل والأخطاء من جانب الخادم

يميز بروتوكول HTTP بين الأخطاء التي تحدث بسبب تطبيق العميل (تعليمات برمجية لحالة HTTP 4xx) والأخطاء الناتجة عن حادث مؤسف على الخادم (تعليمات برمجية لحالة HTTP 5xx). تأكد من أنك تحترم هذه الاصطلاحية في أي رسائل استجابة للخطأ.

تحسين الوصول إلى البيانات من جانب العميل

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

دعم التخزين المؤقت من جانب العميل

يدعم بروتوكول HTTP 1.1 التخزين المؤقت في العملاء والخوادم الوسيطة التي يتم من خلالها توجيه الطلب باستخدام رأس Cache-Control. عندما يرسل تطبيق العميل طلب HTTP GET إلى واجهة برمجة تطبيقات الويب، يمكن أن تتضمن الاستجابة رأس Cache-Control الذي يشير إلى ما إذا كان يمكن تخزين البيانات الموجودة في نص الاستجابة مؤقتاً بأمان بواسطة العميل أو خادم وسيط يتم من خلاله الطلب، ومدة انتهاء صلاحيتها واعتبارها قديمة.

يوضح المثال التالي طلب HTTP GET والاستجابة المقابلة التي تتضمن رأس Cache-Control:

GET https://adventure-works.com/orders/2 HTTP/1.1

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: text/json; charset=utf-8
Content-Length: ...
{"orderID":2,"productID":4,"quantity":2,"orderValue":10.00}

في هذا المثال، يحدد رأس Cache-Control أن البيانات التي يتم إرجاعها يجب أن تنتهي صلاحيتها بعد 600 ثانية، وهي مناسبة فقط لعميل واحد ويجب ألا يتم تخزينها في ذاكرة تخزين مؤقت مشتركة يستخدمها العملاء الآخرون (فهي خاصة ). يمكن أن يحدد رأس Cache-Control ​​عام بدلاً من خاص وفي هذه الحالة يمكن تخزين البيانات في ذاكرة تخزين مؤقت مشتركة، أو يمكنه تحديد no-store في هذه الحالة، يجب عدم تخزين البيانات مؤقتاً بواسطة العميل. يوضح المثال التالي من التعليمة البرمجية كيفية إنشاء رأس Cache-Control في رسالة استجابة:

public class OrdersController : ApiController
{
    ...
    [Route("api/orders/{id:int:min(0)}")]
    [HttpGet]
    public IHttpActionResult FindOrderByID(int id)
    {
        // Find the matching order
        Order order = ...;
        ...
        // Create a Cache-Control header for the response
        var cacheControlHeader = new CacheControlHeaderValue();
        cacheControlHeader.Private = true;
        cacheControlHeader.MaxAge = new TimeSpan(0, 10, 0);
        ...

        // Return a response message containing the order and the cache control header
        OkResultWithCaching<Order> response = new OkResultWithCaching<Order>(order, this)
        {
            CacheControlHeader = cacheControlHeader
        };
        return response;
    }
    ...
}

يستخدم هذا التعليمة البرمجية فئة IHttpActionResult مخصصة تسمى OkResultWithCaching. تُمكِّن هذه الفئة وحدة التحكم من ضبط محتويات رأس ذاكرة التخزين المؤقت:

public class OkResultWithCaching<T> : OkNegotiatedContentResult<T>
{
    public OkResultWithCaching(T content, ApiController controller)
        : base(content, controller) { }

    public OkResultWithCaching(T content, IContentNegotiator contentNegotiator, HttpRequestMessage request, IEnumerable<MediaTypeFormatter> formatters)
        : base(content, contentNegotiator, request, formatters) { }

    public CacheControlHeaderValue CacheControlHeader { get; set; }
    public EntityTagHeaderValue ETag { get; set; }

    public override async Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
    {
        HttpResponseMessage response;
        try
        {
            response = await base.ExecuteAsync(cancellationToken);
            response.Headers.CacheControl = this.CacheControlHeader;
            response.Headers.ETag = ETag;
        }
        catch (OperationCanceledException)
        {
            response = new HttpResponseMessage(HttpStatusCode.Conflict) {ReasonPhrase = "Operation was cancelled"};
        }
        return response;
    }
}

إشعار

يحدد بروتوكول HTTP أيضاً التوجيه no-cache لرأس Cache-Control. من المربك أن هذا التوجيه لا يعني "عدم التخزين المؤقت" بل يعني "إعادة التحقق من المعلومات المخزنة مؤقتاً مع الخادم قبل إعادتها"؛ لا يزال من الممكن تخزين البيانات مؤقتاً، ولكن يتم فحصها في كل مرة يتم استخدامها للتأكد من أنها لا تزال حديثة.

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

إن قيمة max-age في رأس Cache-Control ليست سوى دليل وليست ضماناً بأن البيانات المقابلة لن تتغير خلال الوقت المحدد. يجب أن تحدد واجهة برمجة تطبيقات الويب الحد الأقصى للعمر على قيمة مناسبة اعتماداً على التقلب المتوقع للبيانات. عند انتهاء هذه الفترة، يجب على العميل تجاهل العنصر من ذاكرة التخزين المؤقت.

إشعار

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

تظهر بعض الخوادم الوكيلة الأقدم نفس السلوك وقد لا تخزن الطلبات مؤقتاً استناداً إلى عناوين URL بسلاسل استعلام. قد يكون هذا مشكلة لتطبيقات العميل المخصصة التي تتصل بخادم الويب من خلال هذا الوكيل.

قم بتوفير ETag لتحسين معالجة الاستعلام

عندما يسترد تطبيق العميل عنصراً، يمكن أن تتضمن رسالة الاستجابة أيضاً ETag (علامة الكيان). ETag عبارة عن سلسلة غير شفافة تشير إلى إصدار المورد؛ في كل مرة يتغير المورد، يتم أيضاً تعديل ETag. يجب تخزين ETag هذا كجزء من البيانات بواسطة تطبيق العميل. يوضح المثال التالي من التعليمة البرمجية كيفية إضافة ETag كجزء من الاستجابة لطلب HTTP GET. تستخدم هذه التعليمة البرمجية طريقة GetHashCode العنصر لتوليد قيمة رقمية تحدد العنصر (يمكنك تجاوز هذه الطريقة إذا لزم الأمر وإنشاء التجزئة الخاصة بك باستخدام خوارزمية مثل MD5):

public class OrdersController : ApiController
{
    ...
    public IHttpActionResult FindOrderByID(int id)
    {
        // Find the matching order
        Order order = ...;
        ...

        var hashedOrder = order.GetHashCode();
        string hashedOrderEtag = $"\"{hashedOrder}\"";
        var eTag = new EntityTagHeaderValue(hashedOrderEtag);

        // Return a response message containing the order and the cache control header
        OkResultWithCaching<Order> response = new OkResultWithCaching<Order>(order, this)
        {
            ...,
            ETag = eTag
        };
        return response;
    }
    ...
}

تبدو رسالة الرد التي نشرتها واجهة برمجة تطبيقات الويب على النحو التالي:

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: text/json; charset=utf-8
ETag: "2147483648"
Content-Length: ...
{"orderID":2,"productID":4,"quantity":2,"orderValue":10.00}

تلميح

لأسباب أمنية، لا تسمح بالتخزين المؤقت للبيانات الحساسة أو البيانات التي تم إرجاعها عبر اتصال (HTTPS) مصادق عليه.

يمكن لتطبيق العميل إصدار طلب GET لاحق لاسترداد نفس المورد في أي وقت، وإذا تم تغيير المورد (له ETag مختلف)، يجب تجاهل النسخة المخزنة مؤقتاً وإضافة الإصدار الجديد إلى ذاكرة التخزين المؤقت. إذا كان المورد كبيراً ويتطلب قدراً كبيراً من النطاق الترددي للإرسال مرة أخرى إلى العميل، فقد تصبح الطلبات المتكررة لجلب نفس البيانات غير فعالة. لمكافحة ذلك، يحدد بروتوكول HTTP العملية التالية لتحسين طلبات GET التي يجب أن تدعمها في واجهة برمجة تطبيقات الويب:

• ينشئ العميل طلب GET يحتوي على ETag للإصدار المخزن مؤقتاً حالياً من المورد المشار إليه في عنوان HTTP If-None-Match:

  GET https://adventure-works.com/orders/2 HTTP/1.1
  If-None-Match: "2147483648"
  

• تحصل عملية GET في واجهة برمجة تطبيقات الويب على ETag الحالي للبيانات المطلوبة (الطلب 2 في المثال أعلاه)، وتقارنها بالقيمة الموجودة في عنوان If-None-Match.

• إذا تطابق ETag الحالي للبيانات المطلوبة مع ETag المقدم من الطلب، فلن يتغير المورد ويجب أن تُرجع واجهة برمجة تطبيقات الويب استجابة HTTP بنص رسالة فارغ والتعليمة البرمجية لحالة 304 (غير معدل).

• إذا كان ETag الحالي للبيانات المطلوبة لا يتطابق مع ETag المقدم من قبل الطلب، فإن البيانات قد تغيرت ويجب أن تُرجع واجهة برمجة تطبيقات الويب استجابة HTTP بالبيانات الجديدة في نص الرسالة والتعليمة البرمجية لحالة 200 (موافق).

• إذا لم تعد البيانات المطلوبة موجودة، يجب أن تقوم واجهة برمجة تطبيقات الويب بإرجاع استجابة HTTP بالتعليمة البرمجية لحالة 404 (غير موجود).

• يستخدم العميل التعليمة البرمجية لحالة للحفاظ على ذاكرة التخزين المؤقت. إذا لم يتم تغيير البيانات (التعليمة البرمجية لحالة 304)، يمكن أن يظل العنصر مخبأ ويجب أن يستمر تطبيق العميل في استخدام هذا الإصدار من العنصر. إذا تم تغيير البيانات (التعليمة البرمجية لحالة 200)، يجب تجاهل العنصر المخزن مؤقتاً وإدراج العنصر الجديد. إذا لم تعد البيانات متوفرة (التعليمة البرمجية لحالة 404)، يجب إزالة العنصر من ذاكرة التخزين المؤقت.

إشعار

إذا كان رأس الاستجابة يحتوي على no-store رأس Cache-Control، يجب دائماً إزالة العنصر من ذاكرة التخزين المؤقت بغض النظر عن التعليمة البرمجية لحالة HTTP.

تظهر التعليمات البرمجية FindOrderByID التالية الأسلوب الموسع لدعم رأس If-None-Match. لاحظ أنه إذا تم حذف العنوان If-None-Match، فسيتم دائماً استرداد الترتيب المحدد:

public class OrdersController : ApiController
{
    [Route("api/orders/{id:int:min(0)}")]
    [HttpGet]
    public IHttpActionResult FindOrderByID(int id)
    {
        try
        {
            // Find the matching order
            Order order = ...;

            // If there is no such order then return NotFound
            if (order == null)
            {
                return NotFound();
            }

            // Generate the ETag for the order
            var hashedOrder = order.GetHashCode();
            string hashedOrderEtag = $"\"{hashedOrder}\"";

            // Create the Cache-Control and ETag headers for the response
            IHttpActionResult response;
            var cacheControlHeader = new CacheControlHeaderValue();
            cacheControlHeader.Public = true;
            cacheControlHeader.MaxAge = new TimeSpan(0, 10, 0);
            var eTag = new EntityTagHeaderValue(hashedOrderEtag);

            // Retrieve the If-None-Match header from the request (if it exists)
            var nonMatchEtags = Request.Headers.IfNoneMatch;

            // If there is an ETag in the If-None-Match header and
            // this ETag matches that of the order just retrieved,
            // then create a Not Modified response message
            if (nonMatchEtags.Count > 0 &&
                String.CompareOrdinal(nonMatchEtags.First().Tag, hashedOrderEtag) == 0)
            {
                response = new EmptyResultWithCaching()
                {
                    StatusCode = HttpStatusCode.NotModified,
                    CacheControlHeader = cacheControlHeader,
                    ETag = eTag
                };
            }
            // Otherwise create a response message that contains the order details
            else
            {
                response = new OkResultWithCaching<Order>(order, this)
                {
                    CacheControlHeader = cacheControlHeader,
                    ETag = eTag
                };
            }

            return response;
        }
        catch
        {
            return InternalServerError();
        }
    }
...
}

يدمج هذا المثال فئة IHttpActionResult مخصصة إضافية تسمى EmptyResultWithCaching. تعمل هذه الفئة ببساطة كغلاف بشأن عنصر HttpResponseMessage لا يحتوي على نص استجابة:

public class EmptyResultWithCaching : IHttpActionResult
{
    public CacheControlHeaderValue CacheControlHeader { get; set; }
    public EntityTagHeaderValue ETag { get; set; }
    public HttpStatusCode StatusCode { get; set; }
    public Uri Location { get; set; }

    public async Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
    {
        HttpResponseMessage response = new HttpResponseMessage(StatusCode);
        response.Headers.CacheControl = this.CacheControlHeader;
        response.Headers.ETag = this.ETag;
        response.Headers.Location = this.Location;
        return response;
    }
}

تلميح

في هذا المثال، يتم إنشاء ETag للبيانات عن طريق تجزئة البيانات المسترجعة من مصدر البيانات الأساسي. إذا كان من الممكن حساب ETag بطريقة أخرى، يمكن تحسين العملية بشكل أكبر ولا يلزم جلب البيانات إلا من مصدر البيانات إذا تم تغييرها. هذا الأسلوب مفيد بشكل خاص إذا كانت البيانات كبيرة أو يمكن أن يؤدي الوصول إلى مصدر البيانات إلى زمن انتقال كبير (على سبيل المثال، إذا كان مصدر البيانات عبارة عن قاعدة بيانات بعيدة).

استخدم ETags لدعم التزامن المتفائل

لتمكين التحديثات على البيانات المخزنة مؤقتاً مسبقاً، يدعم بروتوكول HTTP إستراتيجية التزامن متفائلة. إذا أرسل تطبيق العميل لاحقا طلب PUT أو DELETE لتغيير المورد أو إزالته بعد إحضاره والتخزين المؤقت له، فيجب أن يتضمن رأس If-Match الذي يشير إلى ETag. يمكن لواجهة برمجة تطبيقات الويب بعد ذلك استخدام هذه المعلومات لتحديد ما إذا كان قد تم تغيير المورد بالفعل من قبل مستخدم آخر منذ استرداده وإرسال استجابة مناسبة مرة أخرى إلى تطبيق العميل على النحو التالي:

• ينشئ العميل طلب PUT يحتوي على التفاصيل الجديدة للمورد وETag للإصدار المخزن مؤقتاً حالياً من المورد المشار إليه في رأس If-Match HTTP. يوضح المثال التالي طلب PUT الذي يقوم بتحديث الطلب:

  PUT https://adventure-works.com/orders/1 HTTP/1.1
  If-Match: "2282343857"
  Content-Type: application/x-www-form-urlencoded
  Content-Length: ...
  productID=3&quantity=5&orderValue=250
  

• تحصل عملية PUT في واجهة برمجة تطبيقات الويب على ETag الحالي للبيانات المطلوبة (الطلب 1 في المثال أعلاه)، وتقارنها بالقيمة الموجودة في عنوان If-Match.

• إذا كان ETag الحالي للبيانات المطلوبة يطابق ETag المقدم من الطلب، فلن يتغير المورد ويجب أن تجري واجهة برمجة تطبيقات الويب التحديث، وتعيد رسالة بالتعليمة البرمجية لحالة HTTP 204 (لا يوجد محتوى) إذا كان ناجحاً. يمكن أن تتضمن الاستجابة رؤوس Cache-Control وETag للإصدار المحدث من المورد. يجب أن تتضمن الاستجابة دائماً عنوان الموقع الذي يشير إلى URI للمورد الذي تم تحديثه حديثاً.

• إذا كان ETag الحالي للبيانات المطلوبة لا يتطابق مع ETag المقدم من الطلب، فحينئذٍ تم تغيير البيانات بواسطة مستخدم آخر منذ أن تم جلبها ويجب أن تُرجع واجهة برمجة تطبيقات الويب استجابة HTTP بنص رسالة فارغ والتعليمة البرمجية للحالة لـ 412 (فشل الشرط المسبق).

• إذا لم يعد المورد المطلوب تحديثه موجوداً، يجب أن تقوم واجهة برمجة تطبيقات الويب بإرجاع استجابة HTTP بالتعليمة البرمجية لحالة 404 (غير موجود).

• يستخدم العميل التعليمة البرمجية للحالة ورؤوس الاستجابة للحفاظ على ذاكرة التخزين المؤقت. إذا تم تحديث البيانات (التعليمة البرمجية لحالة 204)، يمكن للعنصر أن يظل مخبأ (طالما أن رأس Cache-Control لا يحدد no-store) ولكن يجب تحديث ETag. إذا تم تغيير البيانات بواسطة مستخدم آخر (رمز الحالة 412) أو لم يتم العثور عليها (رمز الحالة 404) فيجب تجاهل الكائن المخزن مؤقتا.

يوضح مثال التعليمة البرمجية التالي تنفيذ عملية PUT لوحدة التحكم في الطلبات:

public class OrdersController : ApiController
{
    [HttpPut]
    [Route("api/orders/{id:int}")]
    public IHttpActionResult UpdateExistingOrder(int id, DTOOrder order)
    {
        try
        {
            var baseUri = Constants.GetUriFromConfig();
            var orderToUpdate = this.ordersRepository.GetOrder(id);
            if (orderToUpdate == null)
            {
                return NotFound();
            }

            var hashedOrder = orderToUpdate.GetHashCode();
            string hashedOrderEtag = $"\"{hashedOrder}\"";

            // Retrieve the If-Match header from the request (if it exists)
            var matchEtags = Request.Headers.IfMatch;

            // If there is an ETag in the If-Match header and
            // this ETag matches that of the order just retrieved,
            // or if there is no ETag, then update the Order
            if (((matchEtags.Count > 0 &&
                String.CompareOrdinal(matchEtags.First().Tag, hashedOrderEtag) == 0)) ||
                matchEtags.Count == 0)
            {
                // Modify the order
                orderToUpdate.OrderValue = order.OrderValue;
                orderToUpdate.ProductID = order.ProductID;
                orderToUpdate.Quantity = order.Quantity;

                // Save the order back to the data store
                // ...

                // Create the No Content response with Cache-Control, ETag, and Location headers
                var cacheControlHeader = new CacheControlHeaderValue();
                cacheControlHeader.Private = true;
                cacheControlHeader.MaxAge = new TimeSpan(0, 10, 0);

                hashedOrder = order.GetHashCode();
                hashedOrderEtag = $"\"{hashedOrder}\"";
                var eTag = new EntityTagHeaderValue(hashedOrderEtag);

                var location = new Uri($"{baseUri}/{Constants.ORDERS}/{id}");
                var response = new EmptyResultWithCaching()
                {
                    StatusCode = HttpStatusCode.NoContent,
                    CacheControlHeader = cacheControlHeader,
                    ETag = eTag,
                    Location = location
                };

                return response;
            }

            // Otherwise return a Precondition Failed response
            return StatusCode(HttpStatusCode.PreconditionFailed);
        }
        catch
        {
            return InternalServerError();
        }
    }
    ...
}

تلميح

يعد استخدام عنوان If-Match اختيارياً تماماً، وإذا تم حذفه، فستحاول واجهة برمجة تطبيقات الويب دائماً تحديث الطلب المحدد، وربما الكتابة بشكل أعمى فوق تحديث تم إجراؤه بواسطة مستخدم آخر. لتجنب المشاكل بسبب فقد التحديثات، قم دائماً بتوفير عنوان If-Match.

التعامل مع الطلبات والاستجابات الكبيرة

قد تكون هناك حالات يحتاج فيها تطبيق العميل إلى إصدار طلبات ترسل أو تتلقى بيانات قد يكون حجمها عدة ميغابايت (أو أكبر). قد يؤدي الانتظار أثناء إرسال هذا القدر من البيانات إلى عدم استجابة تطبيق العميل. ضع في اعتبارك النقاط التالية عندما تحتاج إلى معالجة الطلبات التي تتضمن كميات كبيرة من البيانات:

تحسين الطلبات والاستجابات التي تتضمن أشياء كبيرة

قد تكون بعض الموارد كائنات كبيرة أو تتضمن حقولا كبيرة، مثل صور الرسومات أو أنواع أخرى من البيانات الثنائية. يجب أن تدعم واجهة برمجة تطبيقات الويب التدفق لتمكين التحميل والتنزيل المحسّن لهذه الموارد.

يوفر بروتوكول HTTP آلية ترميز النقل المقسم لدفق عناصر البيانات الكبيرة مرة أخرى إلى العميل. عندما يرسل العميل طلب HTTP GET لعنصر كبير، يمكن لواجهة برمجة تطبيقات الويب إرسال الرد مرة أخرى في أجزاء مجزأة عبر اتصال HTTP. قد لا يكون طول البيانات في الرد معروفا في البداية (قد يتم إنشاؤه)، لذلك يجب على الخادم الذي يستضيف واجهة برمجة تطبيقات الويب إرسال رسالة استجابة مع كل مجموعة تحدد Transfer-Encoding: Chunked العنوان بدلا من رأس طول المحتوى. يمكن أن يتلقى تطبيق العميل كل جزء بدوره لبناء استجابة كاملة. يكتمل نقل البيانات عندما يرسل الخادم مجموعة نهائية بحجم صفر مرة أخرى.

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

يمكنك تصغير حجم العناصر الكبيرة المنقولة عبر الشبكة باستخدام ضغط HTTP. يساعد هذا الأسلوب في تقليل مقدار نسبة استخدام الشبكة وزمن انتقال الشبكة المرتبط، ولكن على حساب طلب معالجة إضافية على العميل والخادم الذي يستضيف واجهة برمجة تطبيقات الويب. على سبيل المثال، يمكن أن يتضمن تطبيق العميل الذي يتوقع تلقي البيانات المضغوطة Accept-Encoding: gzip عنوان طلب (يمكن أيضا تحديد خوارزميات ضغط البيانات الأخرى). إذا كان الخادم يدعم الضغط، فيجب عليه الاستجابة بالمحتوى المحتفظ به بتنسيق gzip في نص الرسالة ورأس الاستجابة Content-Encoding: gzip .

يمكنك الجمع بين الضغط المشفر والتدفق؛ ضغط البيانات أولاً قبل دفقها، وتحديد ترميز محتوى gzip وتشفير النقل المقسم في رؤوس الرسائل. لاحظ أيضاً أنه يمكن تكوين بعض خوادم الويب (مثل خادم معلومات الإنترنت) لضغط استجابات HTTP تلقائياً بغض النظر عما إذا كانت واجهة برمجة تطبيقات الويب تضغط البيانات أم لا.

تنفيذ استجابات جزئية للعملاء الذين لا يدعمون العمليات غير المتزامنة

كبديل للدفق غير المتزامن، يمكن لتطبيق العميل أن يطلب صراحةً بيانات عناصر كبيرة في أجزاء، تُعرف باسم الاستجابات الجزئية. يرسل تطبيق العميل طلب HTTP HEAD للحصول على معلومات بشأن العنصر. إذا كانت واجهة برمجة تطبيقات الويب تدعم الاستجابات الجزئية، فيجب أن تستجيب لطلب HEAD برسالة استجابة تحتوي على Accept-Ranges رأس ورأس Content-Length يشير إلى الحجم الإجمالي للكائن، ولكن يجب أن يكون نص الرسالة فارغا. يمكن لتطبيق العميل استخدام هذه المعلومات لإنشاء سلسلة من طلبات GET التي تحدد نطاقاً من وحدات البايت لتلقيها. يجب أن تقوم واجهة برمجة تطبيقات الويب بإرجاع رسالة استجابة بحالة HTTP 206 (محتوى جزئي)، ورأس طول المحتوى الذي يحدد المقدار الفعلي للبيانات المضمنة في نص رسالة الاستجابة، ورأس نطاق المحتوى الذي يشير إلى الجزء (مثل وحدات البايت 4000 إلى 8000) للعنصر الذي تمثله هذه البيانات.

تم وصف طلبات HTTP HEAD والاستجابات الجزئية بمزيد من التفصيل في تصميم واجهة برمجة التطبيقات.

تجنب إرسال رسائل الحالة 100-متابعة غير الضرورية في تطبيقات العميل

قد يحدد تطبيق العميل الذي هو على وشك إرسال كمية كبيرة من البيانات إلى الخادم أولاً ما إذا كان الخادم مستعداً بالفعل لقبول الطلب أم لا. قبل إرسال البيانات، يمكن لتطبيق العميل إرسال طلب HTTP مع توقع: 100-متابعة رأس، رأس طول المحتوى يشير إلى حجم البيانات، ولكن نص رسالة فارغ. إذا كان الخادم على استعداد للتعامل مع الطلب، يجب أن يستجيب برسالة تحدد حالة HTTP 100 (متابعة). يمكن لتطبيق العميل بعد ذلك المتابعة وإرسال الطلب الكامل بما في ذلك البيانات الموجودة في نص الرسالة.

إذا كنت تستضيف خدمة باستخدام IIS، فإن برنامج تشغيل HTTP.sys يكتشف ويعالج المتوقع تلقائيا: 100-Continue headers قبل تمرير الطلبات إلى تطبيق الويب الخاص بك. هذا يعني أنه من غير المحتمل أن ترى هذه الرؤوس في التعليمة البرمجية للتطبيق الخاص بك، ويمكنك افتراض أن IIS قد قام بالفعل بتصفية أي رسائل يعتبرها غير مناسبة أو كبيرة جداً.

إذا قمت بإنشاء تطبيقات العميل باستخدام .NET Framework، فسترسل جميع رسائل POST و PUT أولا رسائل مع توقع: 100-متابعة العناوين بشكل افتراضي. كما هو الحال مع جانب الخادم، يتم التعامل مع العملية بشفافية بواسطة .NET Framework. ومع ذلك، ينتج عن هذه العملية كل طلب POST وPUT يتسبب في رحلتين ذهاباً وإياباً إلى الخادم، حتى للطلبات الصغيرة. إذا كان تطبيقك لا يرسل طلبات بكميات كبيرة من البيانات، يمكنك تعطيل هذه الميزة باستخدام فئة ServicePointManager لإنشاء ServicePoint عناصر في تطبيق العميل. يتعامل عنصر ServicePoint مع الاتصالات التي يقوم بها العميل بالخادم بناءً على المخطط وأجزاء المضيف من URIs التي تحدد الموارد على الخادم. يمكنك بعد ذلك تعيين خاصية Expect100Continue للعنصر ServicePoint على خطأ. سيتم إرسال جميع طلبات POST وPUT اللاحقة التي تم إجراؤها بواسطة العميل من خلال URI الذي يطابق المخطط وأجزاء المضيف للعنصر ServicePoint دون توقع: رؤوس 100-متابعة. توضح التعليمة البرمجية التالي كيفية تكوين عنصر ServicePoint الذي يقوم بتكوين جميع الطلبات المرسلة إلى URIs باستخدام مخطط http ومضيف www.contoso.com.

Uri uri = new Uri("https://www.contoso.com/");
ServicePoint sp = ServicePointManager.FindServicePoint(uri);
sp.Expect100Continue = false;

يمكنك أيضاً تعيين الخاصية الثابتة Expect100Continue للفئة ServicePointManager لتحديد القيمة الافتراضية لهذه الخاصية لجميع عناصر ServicePoint التي تم إنشاؤها لاحقاً.

دعم ترقيم الصفحات للطلبات التي قد ترجع أعداداً كبيرة من العناصر

إذا كانت المجموعة تحتوي على عدد كبير من الموارد، فقد يؤدي إصدار طلب GET إلى URI المقابل إلى معالجة كبيرة على الخادم الذي يستضيف واجهة برمجة تطبيقات الويب، ما يؤثر على الأداء، ويؤدي إلى إنشاء قدر كبير من حركة مرور الشبكة ما يؤدي إلى زيادة زمن الوصول.

للتعامل مع هذه الحالات، يجب أن تدعم واجهة برمجة تطبيقات الويب سلاسل الاستعلام التي تمكّن تطبيق العميل من تحسين الطلبات أو جلب البيانات في كتل (أو صفحات) منفصلة يمكن التحكم فيها بشكل أكبر. تظهر التعليمات البرمجية GetAllOrders التالية الأسلوب في Orders وحدة التحكم. هذه الطريقة تسترجع تفاصيل الطلبات. إذا كانت هذه الطريقة غير مقيدة، فمن الممكن أن تُرجع كمية كبيرة من البيانات. تهدف المعلمات limit وoffset إلى تقليل حجم البيانات إلى مجموعة فرعية أصغر، في هذه الحالة فقط الطلبات العشرة الأولى افتراضياً:

public class OrdersController : ApiController
{
    ...
    [Route("api/orders")]
    [HttpGet]
    public IEnumerable<Order> GetAllOrders(int limit=10, int offset=0)
    {
        // Find the number of orders specified by the limit parameter
        // starting with the order specified by the offset parameter
        var orders = ...
        return orders;
    }
    ...
}

يمكن لتطبيق العميل إصدار طلب لاسترداد 30 طلباً بدءاً من الإزاحة 50 باستخدام URI https://www.adventure-works.com/api/orders?limit=30&offset=50.

تلميح

تجنب تمكين تطبيقات العميل من تحديد سلاسل الاستعلام التي ينتج عنها URI يزيد طوله عن 2000 حرف. لا يمكن للعديد من عملاء الويب والخوادم التعامل مع معرفات URI هذه المدة الطويلة.

الحفاظ على الاستجابة وقابلية التوسع والتوافر

يمكن استخدام نفس واجهة برمجة تطبيقات الويب بواسطة العديد من تطبيقات العملاء التي تعمل في أي مكان في العالم. من المهم التأكد من أن واجهة برمجة تطبيقات الويب يتم تنفيذها للحفاظ على الاستجابة تحت عبء ثقيل، لتكون قابلة لتغيير الحجم لدعم أعباء عمل شديدة التباين، ولضمان التوافر للعملاء الذين يؤدون عمليات تجارية بالغة الأهمية. ضع في اعتبارك النقاط التالية عند تحديد كيفية تلبية هذه المتطلبات:

تقديم دعم غير متزامن للطلبات طويلة الأمد

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

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

يمكنك تنفيذ آلية اقتراع بسيطة من خلال توفير عنوان URI للاستقصاء الذي يعمل كمورد ظاهري باستخدام الأسلوب التالي:

1. يرسل تطبيق العميل الطلب الأولي إلى واجهة برمجة تطبيقات الويب.
2. تخزن واجهة برمجة تطبيقات الويب معلومات حول الطلب في جدول موجود في Azure Table Storage أو Microsoft Azure Cache وتنشئ مفتاحا فريدا لهذا الإدخال، ربما في شكل GUID. بدلا من ذلك، يمكن إرسال رسالة تحتوي على معلومات حول الطلب والمفتاح الفريد عبر ناقل خدمة Azure أيضا.
3. تبدأ واجهة برمجة تطبيقات الويب المعالجة كمهمة منفصلة أو مع مكتبة مثل Hangfire. تسجل واجهة برمجة تطبيقات الويب حالة المهمة في الجدول على أنها قيد التشغيل.
   • إذا كنت تستخدم ناقل خدمة Azure، فسيتم معالجة الرسائل بشكل منفصل عن واجهة برمجة التطبيقات، ربما باستخدام Azure Functions أو AKS.
4. ترجع واجهة برمجة تطبيقات الويب رسالة استجابة مع رمز حالة HTTP 202 (مقبول)، وURI يحتوي على المفتاح الفريد الذي تم إنشاؤه - شيء مثل /polling/{guid}.
5. عند اكتمال المهمة، تخزن واجهة برمجة تطبيقات الويب النتائج في الجدول، وتعين حالة المهمة إلى مكتملة. لاحظ أنه في حال فشل المهمة، يمكن لواجهة برمجة تطبيقات الويب أيضاً تخزين معلومات بشأن الفشل وتعيين الحالة على فشل.
   • ضع في اعتبارك تطبيق تقنيات إعادة المحاولة لحل حالات الفشل العابرة المحتملة.
6. أثناء تشغيل المهمة، يمكن للعميل متابعة تنفيذ المعالجة الخاصة به. يمكنه إرسال طلب بشكل دوري إلى URI الذي استلمه سابقا.
7. تقوم واجهة برمجة تطبيقات الويب في URI بالاستعلام عن حالة المهمة المقابلة في الجدول وإرجاع رسالة استجابة مع رمز حالة HTTP 200 (موافق) تحتوي على هذه الحالة (قيد التشغيل أو مكتمل أو فاشل). إذا اكتملت المهمة أو فشلت، يمكن أن تتضمن رسالة الاستجابة أيضاً نتائج المعالجة أو أي معلومات متاحة بشأن سبب الفشل.
   • إذا كانت العملية طويلة الأمد تحتوي على حالات متوسطة أكثر، فمن الأفضل استخدام مكتبة تدعم نمط الملحمة، مثل NServiceBus أو MassTransit.

تشمل خيارات تنفيذ الإخطارات ما يلي:

• استخدام مركز إعلام لدفع الاستجابات غير المتزامنة لتطبيقات العميل. لمزيد من المعلومات، راجع إرسال إعلامات إلى مستخدمين محددين باستخدام مراكز إعلام Azure.
• استخدام نموذج Comet للاحتفاظ باتصال شبكة مستمر بين العميل والخادم الذي يستضيف واجهة برمجة تطبيقات الويب، واستخدام هذا الاتصال لدفع الرسائل من الخادم إلى العميل مرة أخرى. تصف مقالة مجلة MSDN إنشاء تطبيق Comet بسيط في Microsoft .NET Framework مثالاً للحل.
• استخدام SignalR لدفع البيانات في الوقت الحقيقي من خادم الويب إلى العميل عبر اتصال شبكة دائم. يتوفر SignalR لتطبيقات الويب ASP.NET كحزمة NuGet. يمكنك العثور على مزيد من المعلومات على موقع الويب ASP.NET SignalR.

تأكد من أن كل طلب عديم الجنسية

يجب اعتبار كل طلب ذرياً. يجب ألا يكون هناك تبعيات بين طلب واحد مقدم بواسطة تطبيق العميل وأي طلبات لاحقة مقدمة من نفس العميل. هذا النهج يساعد في التوسع؛ يمكن توزيع مثيلات خدمة الويب على عدد من الخوادم. يمكن توجيه طلبات العميل إلى أي من هذه الحالات ويجب أن تكون النتائج هي نفسها دائماً. كما أنه يحسن التوافر لسبب مماثل؛ في حال فشل خادم الويب، يمكن توجيه الطلبات إلى مثيل آخر (باستخدام Azure Traffic Manager) أثناء إعادة تشغيل الخادم مع عدم وجود تأثيرات سيئة على تطبيقات العميل.

تعقب العملاء وتنفيذ التقييد لتقليل فرص هجمات DoS

إذا قدم عميل معين عدداً كبيراً من الطلبات خلال فترة زمنية معينة، فقد يحتكر الخدمة ويؤثر على أداء العملاء الآخرين. للتخفيف من هذه المشكلة، يمكن لواجهة برمجة تطبيقات الويب مراقبة المكالمات من تطبيقات العميل إما عن طريق تتبع عنوان IP لجميع الطلبات الواردة أو عن طريق تسجيل كل وصول مصدق عليه. يمكنك استخدام هذه المعلومات للحد من الوصول إلى الموارد. إذا تجاوز العميل حداً محدداً، يمكن لواجهة برمجة تطبيقات الويب إرجاع رسالة استجابة بالحالة 503 (الخدمة غير متوفرة) وتضمين رأس إعادة المحاولة - بعد الذي يحدد متى يمكن للعميل إرسال الطلب التالي دون رفضه. يمكن أن تساعد هذه الاستراتيجية في تقليل فرص هجوم رفض الخدمة (DoS) من مجموعة من العملاء الذين يعطلون النظام.

إدارة اتصالات HTTP المستمرة بعناية

يدعم بروتوكول HTTP اتصالات HTTP المستمرة حيثما كانت متاحة. أضافت مواصفات HTTP 1.0 الاتصال: رأس Keep-Alive الذي يمكّن تطبيق العميل من الإشارة إلى الخادم أنه يمكنه استخدام نفس الاتصال لإرسال الطلبات اللاحقة بدلاً من فتح طلبات جديدة. يتم إغلاق الاتصال تلقائياً إذا لم يقم العميل بإعادة استخدام الاتصال خلال فترة يحددها المضيف. هذا السلوك هو الإعداد الافتراضي في HTTP 1.1 كما تستخدمه خدمات Azure، لذلك ليست هناك حاجة لتضمين رؤوس Keep-Alive في الرسائل.

يمكن أن يساعد الحفاظ على الاتصال مفتوحاً في تحسين الاستجابة عن طريق تقليل زمن الانتقال وازدحام الشبكة، ولكن يمكن أن يكون ضاراً بقابلية التوسع من خلال إبقاء الاتصالات غير الضرورية مفتوحة لفترة أطول من المطلوب، ما يحد من قدرة العملاء المتزامنين الآخرين على الاتصال. يمكن أن يؤثر أيضاً على عمر البطارية إذا كان تطبيق العميل يعمل على جهاز محمول؛ إذا كان التطبيق يقوم فقط بطلبات من حين لآخر إلى الخادم، فإن الحفاظ على اتصال مفتوح يمكن أن يؤدي إلى استنزاف البطارية بشكل أسرع. لضمان عدم استمرار الاتصال مع HTTP 1.1، يمكن للعميل تضمين اتصال: إغلاق رأس مع رسائل لتجاوز السلوك الافتراضي. وبالمثل، إذا كان الخادم يتعامل مع عدد كبير جداً من العملاء، يمكنه تضمين اتصال: إغلاق رأس في رسائل الاستجابة التي يجب أن تغلق الاتصال وتحفظ موارد الخادم.

إشعار

اتصالات HTTP المستمرة هي ميزة اختيارية بحتة لتقليل الحمل على الشبكة المرتبط بإنشاء قناة اتصالات بشكل متكرر. لا يجب أن تعتمد واجهة برمجة تطبيقات الويب ولا تطبيق العميل على توفر اتصال HTTP مستمر. لا تستخدم اتصالات HTTP المستمرة لتنفيذ أنظمة الإعلام على غرار Comet؛ بدلا من ذلك، يجب استخدام مآخذ التوصيل (أو مآخذ الويب إذا كانت متوفرة) في طبقة TCP. أخيراً، لاحظ أن رؤوس Keep-Alive تكون محدودة الاستخدام إذا كان تطبيق العميل يتصل بخادم عبر وكيل؛ سيستمر الاتصال بالعميل والوكيل فقط.

نشر وإدارة واجهة برمجة تطبيقات الويب

لإتاحة واجهة برمجة تطبيقات الويب لتطبيقات العميل، يجب توزيع واجهة برمجة تطبيقات الويب في بيئة مضيفة. هذه البيئة عادةً ما تكون خادم ويب، على الرغم من أنها قد تكون نوعاً آخر من عمليات الاستضافة. يجب مراعاة النقاط التالية عند نشر واجهة برمجة تطبيقات الويب:

• يجب مصادقة جميع الطلبات وترخيصها، ويجب فرض المستوى المناسب من التحكم في الوصول.
• قد تخضع واجهة برمجة تطبيقات الويب التجارية لضمانات جودة مختلفة تتعلق بأوقات الاستجابة. من المهم التأكد من أن بيئة المضيف قابلة للتطوير إذا كان الحمل يمكن أن يختلف بشكل كبير بمرور الوقت.
• قد يكون من الضروري قياس الطلبات لأغراض تحقيق الدخل.
• قد يكون من الضروري تنظيم تدفق نسبة استخدام الشبكة إلى واجهة برمجة تطبيقات الويب، وتنفيذ التقييد لعملاء محددين استنفدوا حصصهم.
• قد تتطلب المتطلبات التنظيمية التسجيل والتدقيق لجميع الطلبات والردود.
• لضمان التوفر، قد يكون من الضروري مراقبة صحة الخادم الذي يستضيف واجهة برمجة تطبيقات الويب وإعادة تشغيله إذا لزم الأمر.

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

• العمل كنقطة تكامل لواجهات برمجة تطبيقات الويب المتعددة.
• تحويل الرسائل وترجمة بروتوكولات الاتصالات للعملاء التي تم إنشاؤها باستخدام تقنيات مختلفة.
• طلبات واستجابات التخزين المؤقت لتقليل الحمل على الخادم الذي يستضيف واجهة برمجة تطبيقات الويب.

اختبار واجهة برمجة تطبيقات الويب

يجب اختبار واجهة برمجة تطبيقات الويب تماماً مثل أي برنامج آخر. يجب أن تفكر في إنشاء اختبارات وحدة للتحقق من صحة الوظيفة.

تجلب طبيعة واجهة برمجة تطبيقات الويب متطلبات إضافية خاصة بها للتحقق من أنها تعمل بشكل صحيح. يجب أن تولي اهتماماً خاصاً للجوانب التالية:

• اختبر جميع المسارات للتحقق من أنها تستدعي العمليات الصحيحة. كن على دراية بشكل خاص بالتعليمة البرمجية لحالة HTTP 405 (الطريقة غير مسموح بها) التي يتم إرجاعها بشكل غير متوقع حيث يمكن أن يشير ذلك إلى عدم تطابق بين المسار وطرق HTTP (GET، POST، PUT، DELETE) التي يمكن إرسالها إلى هذا المسار.

  إرسال طلبات HTTP إلى المسارات التي لا تدعمها، مثل إرسال طلب POST إلى مورد معين (يجب إرسال طلبات POST فقط إلى مجموعات الموارد). في هذه الحالات، فإن الاستجابة الصالحة الوحيدة يجب أن تكون التعليمة البرمجية لحالة 405 (غير مسموح به).

• تحقق من أن جميع المسارات محمية بشكل صحيح وتخضع لفحوصات المصادقة والتفويض المناسبة.

  إشعار

  من المرجح أن تكون بعض جوانب الأمان مثل مصادقة المستخدم على عاتق البيئة المضيفة بدلاً من واجهة برمجة تطبيقات الويب، ولكن لا يزال من الضروري تضمين اختبارات الأمان كجزء من عملية التوزيع.

• اختبر معالجة الاستثناءات التي تقوم بها كل عملية وتحقق من تمرير استجابة HTTP مناسبة وذات مغزى إلى تطبيق العميل.

• تحقق من أن رسائل الطلب والرد جيدة التنسيق. على سبيل المثال، إذا كان طلب HTTP POST يحتوي على بيانات لمورد جديد بتنسيق x-www-form-urlencoded، فتأكد من أن العملية المقابلة توزع البيانات بشكل صحيح، وتُنشئ الموارد، وتُرجع استجابة تحتوي على تفاصيل المورد الجديد، بما في ذلك عنوان الموقع الصحيح.

• تحقق من جميع الروابط وعناوين URL في رسائل الرد. على سبيل المثال، يجب أن تقوم رسالة HTTP POST بإرجاع URI للمورد الذي تم إنشاؤه حديثاً. يجب أن تكون جميع روابط HATEOAS صالحة.

• تأكد من أن كل عملية تقوم بإرجاع التعليمة البرمجية للحالة الصحيحة لمجموعات مختلفة من المدخلات. على سبيل المثال:

  • إذا كان الاستعلام ناجحاً، يجب أن تُرجع التعليمة البرمجية لحالة 200 (موافق)
  • إذا لم يتم العثور على مورد، يجب أن تقوم العملية بإرجاع التعليمة البرمجية لحالة HTTP 404 (غير موجود).
  • إذا أرسل العميل طلباً أدى إلى حذف مورد بنجاح، يجب أن تكون التعليمة البرمجية لحالة هو 204 (لا يوجد محتوى).
  • إذا أرسل العميل طلباً لإنشاء مورد جديد، يجب أن تكون التعليمة البرمجية لحالة 201 (تم الإنشاء).

احترس من التعليمة البرمجية لحالة الاستجابة غير المتوقعة في النطاق 5xx. عادةً ما يتم الإبلاغ عن هذه الرسائل بواسطة الخادم المضيف للإشارة إلى أنه غير قادر على تلبية طلب صالح.

• اختبر مجموعات رؤوس الطلبات المختلفة التي يمكن أن يحددها تطبيق العميل وتأكد من أن واجهة برمجة تطبيقات الويب تُرجع المعلومات المتوقعة في رسائل الاستجابة.

• اختبار سلاسل الاستعلام. إذا كانت العملية يمكن أن تأخذ معلمات اختيارية (مثل طلبات ترقيم الصفحات)، فاختبر المجموعات المختلفة وترتيب المعلمات.

• تحقق من اكتمال العمليات غير المتزامنة بنجاح. إذا كانت واجهة برمجة تطبيقات الويب تدعم التدفق للطلبات التي تُرجع عناصر ثنائية كبيرة (مثل الفيديو أو الصوت)، فتأكد من عدم حظر طلبات العميل أثناء تدفق البيانات. إذا نفذت واجهة برمجة تطبيقات الويب الاقتراع لعمليات تعديل البيانات طويلة الأمد، فتأكد من أن العمليات تبلغ عن حالتها بشكل صحيح أثناء متابعتها.

يجب عليك أيضاً إنشاء اختبارات أداء وتشغيلها للتحقق من أن واجهة برمجة تطبيقات الويب تعمل بشكل مُرضٍ تحت الإكراه. يمكنك إنشاء أداء ويب وتحميل مشروع اختبار باستخدام Visual Studio Ultimate.

استخدام إدارة Azure APIM

في Azure، ضع في اعتبارك استخدام إدارة واجهة برمجة تطبيقات Azure APIM لنشر واجهة برمجة تطبيقات الويب وإدارتها. باستخدام هذا المرفق، يمكنك إنشاء خدمة تعمل كواجهة لواحدة أو أكثر من واجهات برمجة تطبيقات الويب. الخدمة نفسها هي خدمة ويب قابلة لتغيير الحجم يمكنك إنشاؤها وتكوينها باستخدام مدخل Microsoft Azure. يمكنك استخدام هذه الخدمة لنشر وإدارة واجهة برمجة تطبيقات الويب على النحو التالي:

1. قم بتوزيع واجهة برمجة تطبيقات الويب على موقع ويب أو خدمة Azure السحابية أو جهاز Azure الظاهري.

2. قم بتوصيل خدمة إدارة API بواجهة برمجة تطبيقات الويب. يتم تعيين الطلبات المرسلة إلى عنوان URL لواجهة برمجة التطبيقات للإدارة مع URIs في واجهة برمجة تطبيقات الويب. يمكن لخدمة إدارة واجهة برمجة التطبيقات نفسها توجيه الطلبات إلى أكثر من واجهة برمجة تطبيقات ويب واحدة. يمكّنك هذا من تجميع عدة واجهات برمجة تطبيقات على الويب في خدمة إدارة واحدة. وبالمثل، يمكن الرجوع إلى نفس واجهة برمجة تطبيقات الويب من أكثر من خدمة إدارة واجهة برمجة تطبيقات إذا كنت بحاجة إلى تقييد أو تقسيم الوظائف المتاحة لتطبيقات مختلفة.

   إشعار

   يجب أن تشير عناوين URL، في ارتباطات HATEOAS التي تم إنشاؤها كجزء من الاستجابة لطلبات HTTP GET، إلى عنوان URL لخدمة إدارة واجهة برمجة التطبيقات وليس خادم الويب الذي يستضيف واجهة برمجة تطبيقات الويب.

3. لكل واجهة برمجة تطبيقات ويب، حدد عمليات HTTP التي تعرضها واجهة برمجة تطبيقات الويب مع أي معلمات اختيارية يمكن أن تتخذها العملية كمدخلات. يمكنك أيضاً تكوين ما إذا كان يجب على خدمة إدارة واجهة برمجة التطبيقات تخزين الاستجابة المستلمة من واجهة برمجة تطبيقات الويب لتحسين الطلبات المتكررة لنفس البيانات. سجل تفاصيل استجابات HTTP التي يمكن أن تولدها كل عملية. تُستخدم هذه المعلومات لإنشاء وثائق للمطورين، لذلك من المهم أن تكون دقيقة وكاملة.

   يمكنك إما تحديد العمليات يدوياً باستخدام المعالجات التي توفرها مدخل Microsoft Azure، أو يمكنك استيرادها من ملف يحتوي على التعريفات بتنسيق WADL أو Swagger.

4. قم بتكوين إعدادات الأمان للاتصالات بين خدمة إدارة API وخادم الويب الذي يستضيف واجهة برمجة تطبيقات الويب. تدعم خدمة إدارة واجهة برمجة التطبيقات حالياً المصادقة الأساسية والمصادقة المتبادلة باستخدام الشهادات وتفويض مستخدم OAuth 2.0.

5. إنشاء منتج. المنتج هو وحدة النشر. تقوم بإضافة واجهات برمجة تطبيقات الويب التي قمت بتوصيلها مسبقاً بخدمة الإدارة بالمنتج. عندما يتم نشر المنتج، تصبح واجهات برمجة تطبيقات الويب متاحة للمطورين.

   إشعار

   قبل نشر أحد المنتجات، يمكنك أيضاً تحديد مجموعات المستخدمين التي يمكنها الوصول إلى المنتج وإضافة مستخدمين إلى هذه المجموعات. يمنحك هذا التحكم في المطورين والتطبيقات التي يمكنها استخدام واجهة برمجة تطبيقات الويب. إذا كانت واجهة برمجة تطبيقات الويب خاضعة للموافقة، فقبل التمكن من الوصول إليها، يجب على المطور إرسال طلب إلى مسؤول المنتج. يمكن للمسؤول منح أو رفض الوصول إلى المطور. يمكن أيضاً حظر المطورين الحاليين إذا تغيرت الظروف.

6. تكوين النُهج لكل واجهة برمجة تطبيقات على الويب. تحكم النُهج جوانب مثل ما إذا كان يجب السماح بالمكالمات عبر النطاقات، وكيفية مصادقة العملاء، وما إذا كان سيتم التحويل بين تنسيقات بيانات XML وJavaScript Object Notation بشفافية، وما إذا كان سيتم تقييد المكالمات من نطاق IP معين، وحصص الاستخدام، وما إذا كان سيتم تقييد معدل المكالمات. يمكن تطبيق النُهج عالمياً عبر المنتج بأكمله، لواجهة برمجة تطبيقات ويب واحدة في منتج، أو للعمليات الفردية في واجهة برمجة تطبيقات الويب.

لمزيد من المعلومات، راجع وثائق APIM.

تلميح

يوفر Azure Traffic Manager الذي يمكّنك من تنفيذ تجاوز الفشل وموازنة التحميل، وتقليل زمن الوصول عبر مثيلات متعددة لموقع ويب مستضاف في مواقع جغرافية مختلفة. يمكنك استخدام Azure Traffic Manager بالتزامن مع خدمة APIM؛ يمكن لخدمة إدارة واجهة برمجة التطبيقات توجيه الطلبات إلى مثيلات موقع الويب من خلال Azure Traffic Manager. لمزيد من المعلومات، راجع طرق توجيه Traffic Manager.

في هذه البنية، إذا كنت تستخدم أسماء DNS مخصصة لمواقع الويب الخاصة بك، يجب تكوين سجل CNAME المناسب لكل موقع ويب للإشارة إلى اسم DNS لموقع Azure Traffic Manager على الويب.

دعم المطورين من جانب العميل

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

قم بتوثيق عمليات REST لواجهة برمجة تطبيقات الويب

تشتمل خدمة Azure APIM على مدخل مطور يصف عمليات REST المعروضة بواسطة واجهة برمجة تطبيقات الويب. عندما يتم نشر منتج ما فإنه يظهر على هذه المدخل. يمكن للمطورين استخدام هذه المدخل للتسجيل للوصول؛ يمكن للمسؤول بعد ذلك الموافقة على الطلب أو رفضه. إذا تمت الموافقة على المطور، يتم تعيين مفتاح اشتراك يتم استخدامه لمصادقة المكالمات من تطبيقات العميل التي يقومون بتطويرها. يجب توفير هذا المفتاح مع كل استدعاء لواجهة برمجة تطبيقات الويب وإلا فسيتم رفضه.

توفر هذه المدخل أيضاً:

• توثيق المنتج، وسرد العمليات التي يعرضها، والمعلمات المطلوبة، والاستجابات المختلفة التي يمكن إرجاعها. لاحظ أنه يتم إنشاء هذه المعلومات من التفاصيل المقدمة في الخطوة 3 في القائمة في نشر واجهة برمجة تطبيقات الويب باستخدام قسم Microsoft Azure APIM Service.
• مقتطفات التعليمة البرمجية التي توضح كيفية استدعاء العمليات من عدة لغات، بما في ذلك JavaScript وC# وJava وRuby وPython وPHP.
• وحدة تحكم للمطورين تمكن المطور من إرسال طلب HTTP لاختبار كل عملية في المنتج وعرض النتائج.
• صفحة يمكن للمطور من خلالها الإبلاغ عن أي مشكلات أو مشاكل يتم العثور عليها.

يمكّنك مدخل Microsoft Azure من تخصيص مدخل المطور لتغيير التصميم والتخطيط لمطابقة العلامة التجارية لمؤسستك.

تنفيذ عميل SDK

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

يعد إنشاء SDK من جانب العميل مهمة كبيرة حيث يجب تنفيذها باستمرار واختبارها بعناية. ومع ذلك، يمكن إجراء الكثير من هذه العملية بطريقة ميكانيكية، ويقوم العديد من البائعين بتوفير الأدوات التي يمكنها أتمتة العديد من هذه المهام.

مراقبة واجهة برمجة تطبيقات الويب

بناءً على كيفية قيامك بتوزيع وتوزيع واجهة برمجة تطبيقات الويب الخاصة بك، يمكنك مراقبة واجهة برمجة تطبيقات الويب مباشرةً، أو يمكنك جمع معلومات الاستخدام والحالة عن طريق تحليل نسبة استخدام الشبكة التي تمر عبر خدمة إدارة واجهة برمجة التطبيقات (APIM).

مراقبة واجهة برمجة تطبيقات الويب مباشرة

إذا كنت قد نفذت واجهة برمجة تطبيقات الويب الخاصة بك باستخدام قالب ASP.NET Web API (إما كمشروع Web API أو كدور ويب في خدمة Azure السحابية) وVisual Studio 2013، يمكنك جمع بيانات التوافر والأداء والاستخدام عن طريق باستخدام ASP.NET Application Insights. Application Insights عبارة عن حزمة تتعقب وتسجيل المعلومات المتعلقة بالطلبات والاستجابات بشفافية عند توزيع واجهة برمجة تطبيقات الويب في السحابة؛ بمجرد تثبيت الحزمة وتكوينها، لن تحتاج إلى تعديل أي تعليمة برمجية في واجهة برمجة تطبيقات الويب الخاصة بك لاستخدامها. عندما تقوم بتوزيع واجهة برمجة تطبيقات الويب على موقع ويب Azure، يتم فحص كل نسبة استخدام الشبكة ويتم جمع الإحصائيات التالية:

• وقت استجابة الخادم.
• عدد طلبات الخادم وتفاصيل كل طلب.
• أبطأ الطلبات من حيث متوسط ​​وقت الاستجابة.
• تفاصيل أي طلبات فاشلة.
• عدد الجلسات التي بدأها مختلف المتصفحات ووكلاء المستخدم.
• الصفحات الأكثر مشاهدة (مفيدة بشكل أساسي لتطبيقات الويب بدلاً من واجهات برمجة تطبيقات الويب).
• تقوم أدوار المستخدم المختلفة بالوصول إلى واجهة برمجة تطبيقات الويب.

يمكنك عرض هذه البيانات في الوقت الحقيقي في مدخل Microsoft Azure. يمكنك أيضاً إنشاء اختبارات ويب تراقب سلامة واجهة برمجة تطبيقات الويب. يرسل اختبار الويب طلباً دورياً إلى URI محدد في واجهة برمجة تطبيقات الويب ويلتقط الاستجابة. يمكنك تحديد تعريف استجابة ناجحة (مثل التعليمة البرمجية لحالة HTTP 200)، وإذا لم يُرجع الطلب هذه الاستجابة، يمكنك الترتيب لإرسال تنبيه إلى المسؤول. إذا لزم الأمر، يمكن للمسؤول إعادة تشغيل الخادم الذي يستضيف واجهة برمجة تطبيقات الويب إذا فشلت.

لمزيد من المعلومات، راجع Application Insights - بدء استخدام ASP.NET.

مراقبة واجهة برمجة تطبيقات الويب من خلال خدمة إدارة واجهة برمجة التطبيقات (APIM)

إذا قمت بنشر واجهة برمجة تطبيقات الويب الخاصة بك باستخدام خدمة إدارة واجهة برمجة التطبيقات (APIM)، فإن صفحة إدارة واجهة برمجة التطبيقات في مدخل Microsoft Azure تحتوي على لوحة معلومات تمكنك من عرض الأداء العام للخدمة. تمكّنك صفحة التحليلات من التعمق في تفاصيل كيفية استخدام المنتج. تحتوي هذه الصفحة على علامات التبويب التالية:

• الاستخدام. توفر علامة التبويب هذه معلومات بشأن عدد مكالمات API التي تم إجراؤها وعرض النطاق الترددي المستخدم للتعامل مع هذه المكالمات بمرور الوقت. يمكنك تصفية تفاصيل الاستخدام حسب المنتج وواجهة برمجة التطبيقات والتشغيل.
• صحة. تتيح لك علامة التبويب هذه عرض نتائج طلبات واجهة برمجة التطبيقات (تم إرجاع التعليمة البرمجية لحالة HTTP) وفعالية نهج التخزين المؤقت ووقت استجابة واجهة برمجة التطبيقات ووقت استجابة الخدمة. مرة أخرى، يمكنك تصفية البيانات الصحية حسب المنتج وواجهة برمجة التطبيقات والتشغيل.
• النشاط. توفر علامة التبويب هذه ملخصاً نصياً لأرقام المكالمات الناجحة والمكالمات الفاشلة والمكالمات المحظورة ومتوسط ​​وقت الاستجابة وأوقات الاستجابة لكل منتج وواجهة برمجة تطبيقات ويب وعملية. تسرد هذه الصفحة أيضاً عدد المكالمات التي أجراها كل مطور.
• لمحة سريعة. تعرض علامة التبويب هذه ملخصاً لبيانات الأداء، بما في ذلك المطورين المسؤولين عن إجراء معظم استدعاءات واجهة برمجة التطبيقات والمنتجات وواجهات برمجة تطبيقات الويب والعمليات التي تلقت هذه المكالمات.

يمكنك استخدام هذه المعلومات لتحديد ما إذا كانت واجهة برمجة تطبيقات ويب معينة أو عملية معينة تتسبب في حدوث ازدحام، وإذا لزم الأمر تغيير حجم المضيف وإضافة المزيد من الخوادم. يمكنك أيضاً التأكد مما إذا كان تطبيق واحد أو أكثر يستخدم حجماً غير متناسب من الموارد وتطبيق النُهج المناسبة لتعيين الحصص النسبية والحد من أسعار المكالمات.

إشعار

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

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

• يحتوي ASP.NET Web API OData على أمثلة ومزيد من المعلومات بشأن تنفيذ واجهة برمجة تطبيقات الويب OData باستخدام ASP.NET.
• تقديم الدعم المجمع في Web API وWeb API OData يصف كيفية تنفيذ العمليات المجمعة في واجهة برمجة تطبيقات الويب باستخدام OData.
• توفر أنماط Idempotency في مدونة Jonathan Oliver نظرة عامة على العاطفة وكيفية ارتباطها بعمليات إدارة البيانات.
• تحتوي تعريفات التعليمة البرمجية لحالة على موقع W3C على قائمة كاملة بتعليمات برمجية لحالة HTTP وأوصافها.
• يوفر تشغيل مهام الخلفية باستخدام WebJobs معلومات وأمثلة بشأن استخدام WebJobs لإجراء عمليات في الخلفية.
• تُظهر مراكز إعلام Azure للمستخدمين كيفية استخدام مركز إعلام Azure لدفع الاستجابات غير المتزامنة لتطبيقات العميل.
• تصف إدارة واجهة برمجة التطبيقات (APIM) كيفية نشر منتج يوفر وصولاً متحكماً وآمناً إلى واجهة برمجة تطبيقات الويب.
• يصف مرجع Azure APIM REST API كيفية استخدام API Management REST API لإنشاء تطبيقات إدارة مخصصة.
• طرق توجيه Traffic Manager تلخص كيفية استخدام Azure Traffic Manager لطلبات موازنة التحميل عبر مثيلات متعددة من موقع ويب يستضيف واجهة برمجة تطبيقات ويب.
• توفر Application Insights - بدء استخدام ASP.NET معلومات تفصيلية بشأن تثبيت وتكوين Application Insights في مشروع ASP.NET Web API.