إنشاء واجهات برمجة تطبيقات بلا خادم في Visual Studio باستخدام تكامل Azure Functions وAPIM

غالبا ما يتم وصف واجهات برمجة تطبيقات REST باستخدام ملف تعريف OpenAPI (المعروف سابقا باسم Swagger). يحتوي هذا الملف على معلومات حول العمليات في واجهة برمجة التطبيقات وكيفية تنظيم بيانات الطلب والاستجابة لواجهة برمجة التطبيقات.

في هذا البرنامج التعليمي، تتعلم كيفية:

• إنشاء مشروع التعليمات البرمجية في Visual Studio
• تثبيت ملحق OpenAPI
• إضافة نقطة نهاية مشغل HTTP، والتي تتضمن تعريفات OpenAPI
• اختبار واجهات برمجة التطبيقات للدوال محليًا باستخدام وظائف OpenAPI المضمنة
• نشر المشروع إلى تطبيق دالة في Azure
• تمكين تكامل APIM
• تنزيل ملف تعريف OpenAPI

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

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

• Visual Studio 2022. تأكد من تحديد حمل عمل Azure development أثناء التثبيت.

• في حال كان لديك اشتراك Azure نشط، يُمكنك إنشاء حساب مجاني قبل البدء.

إنشاء مشروع التعليمات البرمجية

ينشئ قالب مشروع Azure Functions في Visual Studio مشروع يمكنك نشره في تطبيق دالة ما في Azure. ستقوم أيضا بإنشاء دالة تم تشغيلها بواسطة HTTP من قالب يدعم إنشاء ملف تعريف OpenAPI (ملف Swagger سابقا).

1. من قائمة Visual Studio، حدد ملف>جديد>مشروع.

2. في إنشاء مشروع جديد، أدخل الدالات في مربع البحث، واختر قالب دالات Azure، ثم حدد التالي.

3. في Configure your new project، أدخل اسم مشروع لمشروعك مثل TurbineRepair، ثم حدد إنشاء.

4. بالنسبة لإعدادات تطبيق Create a new Azure Functions، حدد أحد هذه الخيارات ل Functions worker، حيث يعتمد الخيار الذي تختاره على نموذج العملية الذي اخترته:

   نموذج عامل معزول

   .NET 8.0 Isolated (Long Term Support): يتم تشغيل وظائف C# الخاصة بك في نموذج العامل المعزول، والذي يوصى به. لمزيد من المعلومات، راجع دليل نموذج العامل المعزول.

   قيد التنفيذ

   هام

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

   .NET 8.0 (الدعم طويل الأجل): تعمل وظائف C# في النموذج قيد المعالجة، والذي سيتم إيقافه. لمعرفة المزيد، راجع دليل النموذج قيد المعالجة.

5. بالنسبة لبقية الخيارات، استخدم القيم الموجودة في الجدول التالي:

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

6. حدد Create لإنشاء مشروع الدالة.

بعد ذلك، يمكنك تحديث المشروع عن طريق تثبيت ملحق OpenAPI لوظائف Azure، والذي يتيح إمكانية اكتشاف نقاط نهاية واجهة برمجة التطبيقات في تطبيقك.

تثبيت ملحق OpenAPI

لتثبيت ملحق OpenAPI:

1. من قائمة الأدواتاخترNuGet Package Manager>Package Manager Console.

2. في وحدة التحكم، قم بتشغيل الأمر Install-Package التالي لتثبيت ملحق OpenAPI:

   نموذج عامل معزول

   NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
   

   قد تحتاج إلى تحديث الإصدار المحدد، استنادا إلى إصدار .NET الخاص بك.

   نموذج قيد المعالجة

   NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.OpenApi -Version 1.5.1
   

   قد تحتاج إلى تحديث الإصدار المحدد، استنادا إلى إصدار .NET الخاص بك.

الآن، يمكنك إضافة دالة نقطة نهاية HTTP.

إضافة دالة نقطة نهاية HTTP

في مكتبة فئة C#، يتم تعريف الروابط المستخدمة بواسطة الدالة عن طريق تطبيق السمات في التعليمات البرمجية. لإنشاء دالة باستخدام مشغل HTTP:

1. في مستكشف الحلول، انقر بزر الماوس الأيمن فوق عقدة المشروع وحدد Add>New Azure Function.

2. أدخل Turbine.cs للفئة، ثم حدد إضافة.

3. اختر قالب مشغل Http، وقم بتعيين مستوى التخويل إلى دالة، ثم حدد إضافة. تتم إضافة ملف التعليمات البرمجية Turbine.cs إلى مشروعك الذي يحدد نقطة نهاية دالة جديدة مع مشغل HTTP.

الآن يمكنك استبدال التعليمات البرمجية لقالب مشغل HTTP بالتعليمات البرمجية التي تنفذ نقطة نهاية وظيفة التوربينات، جنبا إلى جنب مع السمات التي تستخدم OpenAPI لتعريف نقطة النهاية.

تحديث التعليمات البرمجية للدالة

تستخدم الدالة مشغل HTTP يتطلب معلمتين:

اسم المعلمة	‏‏الوصف
hours	الوقت المقدر لإجراء إصلاح التوربينات، تصل إلى أقرب ساعة كاملة.
القدرة	قدرة التوربينات، بالكيلوواط.

ثم تحسب الدالة مقدار تكاليف الإصلاح، ومقدار الإيرادات التي يمكن أن تحققها التوربينات في فترة 24 ساعة. يتم توفير المعلمات إما في سلسلة الاستعلام أو في حمولة طلب POST.

في ملف مشروع Turbine.cs، استبدل محتويات الفئة التي تم إنشاؤها من قالب مشغل HTTP بالتعليمات البرمجية التالية، والتي تعتمد على نموذج العملية الخاص بك:

نموذج عامل معزول

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;
using System.Net;

namespace TurbineRepair
{
    public class Turbine
    {
        const double revenuePerkW = 0.12;
        const double technicianCost = 250;
        const double turbineCost = 100;

        private readonly ILogger<Turbine> _logger;

        public Turbine(ILogger<Turbine> logger)
        {
            _logger = logger;
        }

        [Function("TurbineRepair")]
        [OpenApiOperation(operationId: "Run")]
        [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
        [OpenApiRequestBody("application/json", typeof(RequestBodyModel),
            Description = "JSON request body containing { hours, capacity}")]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(string),
            Description = "The OK response message containing a JSON result.")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            // Get request body data.
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic? data = JsonConvert.DeserializeObject(requestBody);
            int? capacity = data?.capacity;
            int? hours = data?.hours;

            // Return bad request if capacity or hours are not passed in
            if (capacity == null || hours == null)
            {
                return new BadRequestObjectResult("Please pass capacity and hours in the request body");
            }
            // Formulas to calculate revenue and cost
            double? revenueOpportunity = capacity * revenuePerkW * 24;
            double? costToFix = hours * technicianCost + turbineCost;
            string repairTurbine;

            if (revenueOpportunity > costToFix)
            {
                repairTurbine = "Yes";
            }
            else
            {
                repairTurbine = "No";
            };

            return new OkObjectResult(new
            {
                message = repairTurbine,
                revenueOpportunity = "$" + revenueOpportunity,
                costToFix = "$" + costToFix
            });
        }
        public class RequestBodyModel
        {
            public int Hours { get; set; }
            public int Capacity { get; set; }
        }
    }
}

نموذج قيد المعالجة

using System;
using System.IO;
using System.Net;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;

namespace TurbineRepair
{
    public static class Turbine
    {
        const double revenuePerkW = 0.12;
        const double technicianCost = 250;
        const double turbineCost = 100;

        [FunctionName("TurbineRepair")]
        [OpenApiOperation(operationId: "Run")]
        [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
        [OpenApiRequestBody("application/json", typeof(RequestBodyModel), 
            Description = "JSON request body containing { hours, capacity}")]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(string),
            Description = "The OK response message containing a JSON result.")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            // Get request body data.
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            int? capacity = data?.capacity;
            int? hours = data?.hours;

            // Return bad request if capacity or hours are not passed in
            if (capacity == null || hours == null)
            {
                return new BadRequestObjectResult("Please pass capacity and hours in the request body");
            }
            // Formulas to calculate revenue and cost
            double? revenueOpportunity = capacity * revenuePerkW * 24;
            double? costToFix = (hours * technicianCost) + turbineCost;
            string repairTurbine;

            if (revenueOpportunity > costToFix)
            {
                repairTurbine = "Yes";
            }
            else
            {
                repairTurbine = "No";
            };

            return (ActionResult)new OkObjectResult(new
            {
                message = repairTurbine,
                revenueOpportunity = "$" + revenueOpportunity,
                costToFix = "$" + costToFix
            });
        }
    }
    public class RequestBodyModel
    {
        public int Hours { get; set; }
        public int Capacity { get; set; } 
    }
}

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

تشغيل واجهة برمجة التطبيقات والتحقق منها محليًا

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

1. اضغط على F5 لبدء المشروع. عند بدء وقت تشغيل Functions محليًا، يتم عرض مجموعة من نقاط النهاية OpenAPI وSwagger في الإخراج، مع نقطة نهاية الدالة.

2. في المستعرض لديك، افتح نقطة النهاية RenderSwaggerUI، التي يجب أن تبدو مثل http://localhost:7071/api/swagger/ui. يتم تقديم صفحة، استنادًا إلى تعريفات OpenAPI.

3. حدد POST>جربه، وأدخل قيم hours وcapacity إما كمعلمات استعلام أو في نص طلب JSON، وحدد تنفيذ.

   

4. عند إدخال قيم عدد صحيح مثل 6 لـ hours و2500 لـ capacity، تحصل على استجابة JSON التي تبدو مثل المثال التالي:

   

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

كيفية نشر المشروع إلى Azure

قبل أن تتمكن من نشر مشروعك، يجب أن يكون لديك تطبيق دالة في اشتراكك على Azure. ينشئ نشر Visual Studio تطبيق دالة في المرة الأولى التي تنشر فيها مشروعك. كما يمكنه إنشاء مثيل API Management يتكامل مع تطبيق الدالة لعرض واجهة برمجة تطبيقات TurbineRepair.

1. في مستكشف الحلول، انقر بزر الماوس الأيمن فوق المشروع، وحدد نشر وفي الهدف، حدد Azure ثم التالي.

2. بالنسبة للهدف المحدد، اختر Azure Function App (Windows) لإنشاء تطبيق دالة يتم تشغيله على Windows، ثم حدد التالي.

3. في مثيل الدالة، اختر + إنشاء Azure Function جديدة....

   

4. إنشاء مثيل جديد باستخدام القيم المحددة في الجدول التالي:

   الإعداد	قيمة	‏‏الوصف
   الاسم	اسم فريد عالميًا	الاسم الذي يعرّف بشكل فريد تطبيق الدالة الجديد الخاص بك. اقبل هذا الاسم أو أدخل اسماً جديداً. الأحرف الصالحة هي: a-z، و0-9، و-.
   الاشتراك	اشتراكك	اشتراك معرف Azure المطلوب استخدامه. اقبل هذا الاشتراك أو حدد اشتراكاً جديداً من القائمة المنسدلة.
   مجموعة الموارد	قم بتسمية مجموعة الموارد لديك	مجموعة الموارد التي يتم من خلالها إنشاء تطبيق دالة. حدد مجموعة موارد موجودة من القائمة المنسدلة، أو اختر جديد لإنشاء مجموعة موارد جديدة.
   Plan Type	الاستهلاك‬	عند نشر المشروع إلى تطبيق دالة يعمل في خطة استهلاك، فإنك تدفع فقط مقابل تنفيذ تطبيق الدوال. تتكبد خطط الاستضافة الأخرى تكاليف أعلى.
   Location	موقع الخدمة	اختر الموقع في منطقة قريبة منك أو خدمات أخرى تصل دوالك إليها.
   تخزين Azure	حساب تخزين للأغراض العامة	حساب Azure Storage مطلوب من قِبل وقت تشغيل Functions. حدد جديد لتكوين حساب تخزين للأغراض العامة. كما يمكنك اختيار حساب موجود، والذي يجب أن يفي بمتطلبات حساب التخزين.

   

5. حدد إنشاء لإنشاء تطبيق وظائف وموارده ذات الصلة في Azure. تظهر حالة إنشاء المورد في أسفل يمين النافذة.

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

7. حدد التالي، وفي صفحة API Management، اختر أيضًا + إنشاء واجهة برمجة تطبيقات API Management.

8. أنشئ واجهة برمجة تطبيقات في API Management باستخدام القيم في الجدول التالي:

   الإعداد	قيمة	‏‏الوصف
   اسم واجهة برمجة التطبيقات	TurbineRepair	اسم لواجهة برمجة التطبيقات.
   اسم الاشتراك	اشتراكك	اشتراك معرف Azure المطلوب استخدامه. اقبل هذا الاشتراك أو حدد اشتراكاً جديداً من القائمة المنسدلة.
   مجموعة الموارد	قم بتسمية مجموعة الموارد لديك	حدد نفس مجموعة الموارد مثل تطبيق الدالة من القائمة المنسدلة.
   خدمة API Management	مثيل جديد	حدد New لإنشاء مثيل APIM جديد في نفس الموقع في المستوى بلا خادم. حدد OK لإنشاء المثيل.

   

9. حدد إنشاء لإنشاء مثيل API Management باستخدام واجهة برمجة تطبيقات TurbineRepair من تكامل الدالة.

10. حدد إنهاء وبعد اكتمال عملية إنشاء ملف تعريف النشر، حدد إغلاق.

11. تحقق من أن صفحة النشر تظهر الآن جاهزة للنشر، ثم حدد نشر لنشر الحزمة التي تحتوي على ملفات المشروع إلى تطبيق الوظائف الجديد في Azure.

    بعد اكتمال التوزيع، يظهر عنوان URL الجذر لتطبيق الدالة في Azure في علامة التبويب نشر.

لحصول على مفتاح الوصول إلى الدالة

1. في علامة التبويب Publish، حدد علامات الحذف (...) بجوار Hosting وحدد Open in Azure portal. يتم فتح تطبيق الدالة الذي أنشأته في مدخل Azure في المستعرض الافتراضي.

2. ضمن Functions في صفحة Overview، حدد> Turbine ثم حدد Function keys.

   

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

تكوين API Management

1. في صفحة تطبيق الوظائف، قم بتوسيع API وحدد API Management.

2. إذا لم يكن تطبيق الدالة متصلا بالفعل بمثيل APIM الجديد، فحدده ضمن API Management، وحدد API>OpenAPI Document على Azure Functions، وتأكد من تحديد Import functions، وحدد Link API. تأكد من تحديد TurbineRepair فقط للاستيراد ثم حدد.

3. حدد Go to API Management في أعلى الصفحة، وفي مثيل APIM، قم بتوسيع واجهات برمجة التطبيقات.

4. ضمن APIs>All APIs، حدد OpenAPI Document on Azure Functions>POST Run، ثم ضمن Inbound processing حدد Add policy>Set query parameters.

5. أسفل معالجة الوارد، في تعيين معلمات الاستعلام، اكتب code لـ الاسم، وحدد +قيمة والصِقها في مفتاح الدالة المنسوخ ثم حدد حفظ. تتضمن API Management مفتاح الدالة عندما تمرر استدعاءات إلى نقطة نهاية الدالة.

   

الآن بعد تعيين مفتاح الدالة، يمكنك استدعاء turbine نقطة نهاية واجهة برمجة التطبيقات للتحقق من أنه يعمل عند استضافته في Azure.

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

1. في واجهة برمجة التطبيقات، حدد علامة التبويب اختبار ثم تشغيل POST، وأدخل التعليمات البرمجية التالية في نص الطلب>الأولي، وحدد إرسال:

   {
       "hours": "6",
       "capacity": "2500"
   }
   

   

   كما كان من قبل، يمكنك أيضًا توفير نفس القيم مثل معلمات الاستعلام.

2. حدد إرسال، ثم اعرض استجابة HTTP للتحقق من إرجاع نفس النتائج من واجهة برمجة التطبيقات.

تنزيل تعريف OpenAPI

إذا كانت واجهة برمجة التطبيقات تعمل كما هو متوقع، يمكنك تنزيل تعريف OpenAPI لواجهات برمجة التطبيقات المستضافة الجديدة من APIM.

1. 1. ضمن واجهات برمجة التطبيقات، حدد مستند OpenAPI على Azure Functions، ثم حدد علامات الحذف (...) وحدد تصدير.

   

2. اختر وسائل تصدير واجهة برمجة التطبيقات، بما في ذلك ملفات OpenAPI بتنسيقات مختلفة. يمكنك أيضًا تصدير واجهات برمجة التطبيقات من Azure API Management إلى Power Platform.

تنظيف الموارد

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

من قائمة مدخل Microsoft Azure أو من Home، حدد Resource groups. ثم في صفحة مجموعة الموارد، حدد المجموعة التي أنشأتها.

في صفحة myResourceGroup، تأكد من أن الموارد المدرجة هي التي تريد حذفها.

حدد حذف مجموعة الموارد، واكتب اسم المجموعة في مربع النص للتأكيد، ثم حدد حذف.

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

لقد استخدمت Visual Studio 2022 لإنشاء دالة ذاتية التوثيق بسبب ملحق OpenAPI ومتكاملة مع APIM. يمكنك الآن تحسين التعريف في API Management في المدخل. يمكنك أيضًا معرفة المزيد حول API Management.

تحرير تعريف OpenAPI في API Management