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

مقالة
06/01/2023

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

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

إنشاء مشروع دالة بدون خادم في Visual Studio
اختبار واجهات برمجة التطبيقات للدوال محليًا باستخدام وظائف OpenAPI المضمنة
نشر المشروع إلى تطبيق دالة في Azure باستخدام تكامل API Management
الحصول على مفتاح الوصول للدالة وتعيينه في API Management
تنزيل ملف تعريف OpenAPI

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

ملاحظة

تكامل OpenAPI وAPIM المميز في هذه المقالة مدعوم حاليا فقط لوظائف مكتبة فئة C#‎ قيد المعالجة . عملية عامل معزولة يجب أن تستخدم وظائف مكتبة فئة C# وجميع أوقات تشغيل اللغة الأخرى بدلا من ذلك تكامل Azure API Management من المدخل.

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

Visual Studio 2022. تأكد من تحديد حمل عمل Azure development أثناء التثبيت.
في حال كان لديك اشتراك Azure نشط، يُمكنك إنشاء حساب مجاني قبل البدء.

إنشاء مشروع دوال

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

من قائمة Visual Studio، حدد ملف>جديد>مشروع.
في إنشاء مشروع جديد، أدخل الدالات في مربع البحث، واختر قالب دالات Azure، ثم حدد التالي.
في Configure your new project، أدخل اسم مشروع لمشروعك مثل TurbineRepair، ثم حدد إنشاء.

بالنسبة لإعدادات إنشاء تطبيق Azure Functions جديد، استخدم القيم الموضحة في الجدول التالي:

إعداد	القيمة	الوصف
عامل الوظائف	.NET 6	تنشئ هذه القيمة مشروع دالة يعمل قيد المعالجة على الإصدار 4.x من وقت تشغيل Azure Functions، وهو مطلوب لإنشاء ملف OpenAPI.
قالب الدالة	مشغل HTTP مع OpenAPI	تنشئ هذه القيمة دالة مشغلة بواسطة طلب HTTP، مع القدرة على إنشاء ملف تعريف OpenAPI.
استخدام Azurite لحساب تخزين وقت التشغيل (AzureWebJobsStorage)	محدد	يمكنك استخدام المحاكي للتطوير المحلي لدوال مشغل HTTP. يُخصص حساب تخزين أو يُنشأ عند نشر المشروع على Azure لأن تطبيق الدالة في Azure يشترط توفره.
مستوى التخويل	وظيفة	عند التشغيل في Azure، يجب على العملاء توفير مفتاح عند الوصول إلى نقطة النهاية. لمزيد من المعلومات حول المفاتيح والتخويل، راجع مفاتيح الوصول إلى الوظائف.

إعدادات مشروع Azure Functions

حدد إنشاء لإنشاء مشروع الدالة ودالة مشغل HTTP، مع دعم لـ OpenAPI.

ينشئ Visual Studio مشروعًا وفئة تسمى Function1 تحتوي على رمز متداول لنوع دالة مشغل HTTP. بعد ذلك، يمكنك استبدال التعليمات البرمجية لقالب الدالة هذه بتعليماتك البرمجية المخصصة.

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

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

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

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

في ملف مشروع Function1.cs، استبدل محتويات التعليمات البرمجية لمكتبة الفئة التي تم إنشاؤها بالتعليمات البرمجية التالية:

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 Turbines
    {
        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 تجربة الدالة محليًا باستخدام صفحة تم إنشاؤها. لا تحتاج إلى توفير مفاتيح الوصول إلى الدالة عند التشغيل محليًا.

اضغط على F5 لبدء المشروع. عند بدء وقت تشغيل Functions محليًا، يتم عرض مجموعة من نقاط النهاية OpenAPI وSwagger في الإخراج، مع نقطة نهاية الدالة.
في المستعرض لديك، افتح نقطة النهاية RenderSwaggerUI، التي يجب أن تبدو مثل http://localhost:7071/api/swagger/ui. يتم تقديم صفحة، استنادًا إلى تعريفات OpenAPI.
حدد POST>جربه، وأدخل قيم hours وcapacity إما كمعلمات استعلام أو في نص طلب JSON، وحدد تنفيذ.
عند إدخال قيم عدد صحيح مثل 6 لـ hours و2500 لـ capacity، تحصل على استجابة JSON التي تبدو مثل المثال التالي:

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

نشر المشروع على Azure

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

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

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

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

إنشاء تطبيق دالة جديد في Azure باستخدام Storage

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

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

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

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

حدد إنشاء لإنشاء مثيل API Management باستخدام واجهة برمجة تطبيقات TurbineRepair من تكامل الدالة.
حدد إنهاء، وتحقق من ظهور جاهز للنشر في صفحة «نشر»، ثم حدد نشر لتوزيع الحزمة التي تحتوي على ملفات المشروع إلى تطبيق الدالة الجديد في Azure.

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

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

في علامة التبويب Publish، حدد علامات الحذف ( ... ) بجوار Hosting وحدد Open in Azure portal. يتم فتح تطبيق الدالة الذي أنشأته في مدخل Azure في المستعرض الافتراضي.
ضمن الوظائف، حدد الوظائف>TurbineRepair ثم حدد مفاتيح الدالة.
ضمن مفاتيح الدالة، حدد افتراضي وانسخ القيمة. يمكنك الآن تعيين هذا المفتاح في API Management بحيث يمكنه الوصول إلى نقطة نهاية الدالة.

تكوين API Management

في علامة التبويب Publish، حدد علامات الحذف ( ... ) بجوار Hosting وحدد Open API in Azure portal. يتم فتح مثيل API Management الذي أنشأته في مدخل Azure في المستعرض الافتراضي. تم ربط مثيل API Management هذا بتطبيق الدالة بالفعل.
ضمن واجهات برمجة التطبيقات، حدد مستند OpenAPI على Azure Functions>تشغيل POST، ثم ضمن معالجة الوارد حدد إضافة نهج.
أسفل معالجة الوارد، في تعيين معلمات الاستعلام، اكتب code لـ الاسم، وحدد +قيمة والصِقها في مفتاح الدالة المنسوخ ثم حدد حفظ. تتضمن API Management مفتاح الدالة عندما تمرر استدعاءات إلى نقطة نهاية الدالة.

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

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

في واجهة برمجة التطبيقات، حدد علامة التبويب اختبار ثم تشغيل POST، وأدخل التعليمات البرمجية التالية في نص الطلب>الأولي، وحدد إرسال:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
كما كان من قبل، يمكنك أيضًا توفير نفس القيم مثل معلمات الاستعلام.
حدد إرسال، ثم اعرض استجابة HTTP للتحقق من إرجاع نفس النتائج من واجهة برمجة التطبيقات.

تنزيل تعريف OpenAPI

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

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

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

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

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

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

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

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

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

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

Share via