دمج API Management مع Service Fabric في Azure

يعد نشر Azure API Management باستخدام Service Fabric سيناريو متقدم. تعد API Management مفيدة عندما تحتاج إلى نشر واجهات برمجة التطبيقات مع مجموعة غنية من قواعد التوجيه لخدمات Service Fabric الخلفية. تحتاج التطبيقات السحابية عادة إلى بوابة أمامية لتوفير نقطة دخول واحدة للمستخدمين أو الأجهزة أو التطبيقات الأخرى. في Service Fabric، يمكن أن تكون بوابة أي خدمة عديمة الحالة مصممة لدخول حركة المرور مثل تطبيق ASP.NET Core أو مراكز الأحداث أو IoT Hub أو Azure API Management.

توضح لك هذه المقالة كيفية إعداد Azure API Management باستخدام Service Fabric لتوجيه حركة المرور إلى خدمة خلفية في Service Fabric. عند الانتهاء، تكون قد نشرت API Management إلى VNET، وقمت بتكوين عملية واجهة برمجة التطبيقات لإرسال حركة المرور إلى الخدمات عديمة الحالة الخلفية. لمعرفة المزيد حول سيناريوهات Azure API Management باستخدام Service Fabric، راجع مقالة النظرة العامة.

إشعار

نوصي باستخدام الوحدة النمطية Azure Az PowerShell للتفاعل مع Azure. للبدء، راجع تثبيت Azure PowerShell. لمعرفة كيفية الترحيل إلى الوحدة النمطية Az PowerShell، راجع ترحيل Azure PowerShell من AzureRM إلى Az.

التوافر

هام

تتوفر هذه الميزة في Premium ومستويات المطورين في API Management نظرا لدعم الشبكة الافتراضية المطلوب.

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

قبل البدء:

• عند عدم وجود اشتراك في Azure، فقم بإنشاء حساب مجاني
• قم بتثبيت Azure PowerShell أو Azure CLI.
• إنشاء مجموعة Windows آمنة في مجموعة أمان شبكة.
• إذا قمت بنشر مجموعة Windows، فقم بإعداد بيئة تطوير Windows. تثبيت Visual Studio 2019 وتطوير Azure، تطوير ASP.NET والويب، وتطوير .NET Core عبر النظام الأساسي. ثم إعداد بيئة تطوير .NET.

طبولوجيا الشبكة

الآن بعد أن أصبح لديك مجموعة Windows آمنة على Azure، قم بنشر API Management على الشبكة الظاهرية (VNET) في الشبكة الفرعية وNSG المخصصة لAPI Management. بالنسبة لهذه المقالة، تم تكوين قالب API Management Resource Manager مسبقا لاستخدام أسماء VNET والشبكة الفرعية وNSG التي قمت بإعدادها في البرنامج التعليمي لنظام مجموعة Windows تنشر هذه المقالة الطبولوجيا التالية إلى Azure حيث توجد API Management وService Fabric في الشبكات الفرعية لنفس الشبكة الظاهرية:

سجل الدخول إلى Azure وحدد اشتراكك

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

Connect-AzAccount
Get-AzSubscription
Set-AzContext -SubscriptionId <guid>

az login
az account set --subscription <guid>

نشر خدمة خلفية لـ Service Fabric

قبل تكوين API Management لتوجيه حركة المرور إلى خدمة خلفية لـ Service Fabric، تحتاج أولا إلى خدمة قيد التشغيل لقبول الطلبات.

إنشاء خدمة أساسية ASP.NET موثوق بها باستخدام قالب مشروع Web API الافتراضي. يؤدي ذلك إلى إنشاء نقطة نهاية HTTP لخدمتك، والتي تقوم بعرضها من خلال Azure API Management.

بدء Visual Studio كمسؤول وإنشاء خدمة ASP.NET الأساسية:

1. في Visual Studio، حدد ملف -> مشروع جديد.

2. حدد قالب تطبيق Service Fabric ضمن السحابة وقم بتسميته "ApiApplication".

3. حدد قالب الخدمة الأساسية ASP.NET عديم الحالة وقم بتسمية المشروع "WebApiService".

4. حدد واجهة برمجة تطبيقات الويب ASP.NET قالب مشروع Core 2.1.

5. بمجرد إنشاء المشروع، افتح PackageRoot\ServiceManifest.xml وأزل السمة Port من تكوين مورد نقطة النهاية:

   <Resources>
     <Endpoints>
       <Endpoint Protocol="http" Name="ServiceEndpoint" Type="Input" />
     </Endpoints>
   </Resources>
   

   تسمح إزالة المنفذ لـ Service Fabric بتحديد منفذ ديناميكيا من نطاق منفذ التطبيق، الذي يتم فتحه من خلال مجموعة أمان الشبكة في قالب Resource Manager المجموعة، مما يسمح بتدفق حركة المرور إليه من API Management.

6. اضغط على F5 في Visual Studio للتحقق من توفر واجهة برمجة تطبيقات الويب محليا.

   افتح مستكشف Service Fabric وانتقل لأسفل إلى مثيل معين من خدمة ASP.NET Core لرؤية العنوان الأساسي الذي تستمع إليه الخدمة. أضف /api/values إلى العنوان الأساسي وافتحه في مستعرض، والذي يستدعي أسلوب Get على ValuesController في قالب Web API. ترجع الاستجابة الافتراضية التي يوفرها القالب، صفيف JSON يحتوي على سلسلتين:

   ["value1", "value2"]`
   

   هذه هي نقطة النهاية التي تعرضها من خلال API Management في Azure.

7. وأخيرا، قم بنشر التطبيق على مجموعتك في Azure. في Visual Studio، انقر بزر الماوس الأيمن فوق مشروع التطبيق وحدد نشر. قم بتوفير نقطة نهاية المجموعة (على سبيل المثال، mycluster.southcentralus.cloudapp.azure.com:19000) لنشر التطبيق إلى مجموعة Service Fabric في Azure.

يجب الآن تشغيل خدمة ASP.NET Core عديمة الحالة المسماة fabric:/ApiApplication/WebApiService في مجموعة Service Fabric في Azure.

تنزيل وفهم قوالب Resource Manager

قم بتنزيل ملف القوالب والمعلمات Resource Manager التالي وحفظه:

• network-apim.json
• network-apim.parameters.json
• apim.json
• apim.parameters.json

يقوم قالب network-apim.json بنشر شبكة فرعية جديدة ومجموعة أمان الشبكة في الشبكة الظاهرية حيث يتم نشر مجموعة Service Fabric.

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

Microsoft.ApiManagement/service

يصف Microsoft.ApiManagement/service مثيل خدمة API Management: الاسم أو وحدة SKU أو الطبقة وموقع مجموعة الموارد ومعلومات الناشر والشبكة الظاهرية.

Microsoft.ApiManagement/service/certificates

يقوم Microsoft.ApiManagement/service/certificates بتكوين أمان API Management. يجب أن تقوم API Management بالمصادقة باستخدام مجموعة Service Fabric الخاصة بك لاكتشاف الخدمة باستخدام شهادة عميل لديها حق الوصول إلى مجموعتك. تستخدم هذه المقالة نفس الشهادة المحددة مسبقا عند إنشاء نظام مجموعة Windows، والتي يمكن استخدامها افتراضيا للوصول إلى نظام المجموعة.

تستخدم هذه المقالة نفس الشهادة لمصادقة العميل وأمان عقدة إلى عقدة نظام المجموعة. يمكنك استخدام شهادة عميل منفصلة إذا كان لديك واحدة تم تكوينها للوصول إلى مجموعة Service Fabric الخاصة بك. قم بتوفير الاسم وكلمة المرور والبيانات (السلسلة المشفرة base-64) لملف المفتاح الخاص (.pfx) لشهادة نظام المجموعة التي قمت بتحديدها عند إنشاء مجموعة Service Fabric الخاصة بك.

Microsoft.ApiManagement/service/backends

يصف Microsoft.ApiManagement/service/backends خدمة الواجهة الخلفية التي يتم إعادة توجيه حركة المرور إليها.

بالنسبة للواجهات الخلفية لـ Service Fabric، تكون مجموعة Service Fabric هي الواجهة الخلفية بدلا من خدمة Service Fabric محددة. يسمح هذا لنهج واحد بالتوجيه إلى أكثر من خدمة واحدة في المجموعة. حقل عنوان محدد مواقع الويب هنا هو اسم خدمة مؤهل بالكامل لخدمة في مجموعتك يتم توجيه جميع الطلبات إليها بشكل افتراضي إذا لم يتم تحديد اسم خدمة في نهج الواجهة الخلفية. يمكنك استخدام اسم خدمة مزيف، مثل "fabric:/fake/service" إذا كنت لا تنوي الحصول على خدمة احتياطية. يحدد resourceId نقطة نهاية إدارة نظام المجموعة. clientCertificateThumbprint وserverCertificateThumbprints تحديد الشهادات المستخدمة للمصادقة مع المجموعة.

Microsoft.ApiManagement/service/products

يقوم Microsoft.ApiManagement/service/products بإنشاء منتج. في إدارة واجهة برمجة تطبيقات Azure، يحتوي المنتج على واحد أو أكثر من واجهات برمجة التطبيقات بالإضافة إلى حصة نسبية للاستخدام وشروط الاستخدام. بمجرد نشر منتج، يمكن للمطورين الاشتراك في المنتج والبدء في استخدام واجهات برمجة التطبيقات للمنتج.

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

Microsoft.ApiManagement/service/apis

يقوم Microsoft.ApiManagement/service/apis بإنشاء واجهة برمجة تطبيقات. تمثل واجهة برمجة التطبيقات في API Management مجموعة من العمليات التي يمكن استدعاؤها بواسطة تطبيقات العميل. بمجرد إضافة العمليات، تتم إضافة واجهة برمجة التطبيقات إلى منتج ويمكن نشرها. بمجرد نشر واجهة برمجة التطبيقات، يمكن للمطورين الاشتراك فيها واستخدامها.

• displayName يمكن أن يكون أي اسم لواجهة برمجة التطبيقات الخاصة بك. بالنسبة لهذه المقالة، استخدم "تطبيق Service Fabric".
• يوفر name اسما فريدا ووصفيا لواجهة برمجة التطبيقات، مثل "service-fabric-app". يتم عرضه في بوابات المطور والناشر.
• يشير serviceUrl إلى خدمة HTTP التي تنفذ واجهة برمجة التطبيقات. إن API Management تعيد توجيه الطلبات إلى هذا العنوان. بالنسبة للواجهات الخلفية لـ Service Fabric، لا يتم استخدام قيمة محدد مواقع الويب هذه. يمكنك وضع أي قيمة هنا. بالنسبة لهذه المقالة، على سبيل المثال "http://servicefabric"؛.
• المسار عبارة عن لاحقة بمحدد مواقع الويب الأساسي لخدمة API Management. محدد مواقع الويب الأساسي شائع لجميع واجهات برمجة التطبيقات التي يستضيفها مثيل خدمة إدارة API Management. تميز APIM واجهات برمجة التطبيقات بلاحقتها، وبالتالي يجب أن تكون اللاحقة فريدة لكل واجهة برمجة تطبيقات لناشر معين.
• تحدد البروتوكولات أي البروتوكولات التي يمكن استخدامها للوصول إلى واجهة برمجة التطبيقات. بالنسبة لهذه المقالة، قم بإدراج http وhttps.
• المسار هو لاحقة لواجهة برمجة التطبيقات. لهذه المقالة، استخدم "myapp".

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations قبل استخدام واجهة برمجة التطبيقات في API Management، يجب إضافة العمليات إلى واجهة برمجة التطبيقات. يستخدم العملاء الخارجيون عملية للاتصال بالخدمة عديمة الحالة الأساسية ASP.NET التي يتم تشغيلها في مجموعة Service Fabric.

لإضافة عملية واجهة برمجة تطبيقات أمامية، املأ القيم:

• displayNameوالوصف يصفان العملية. بالنسبة لهذه المقالة، استخدم "القيم".
• تحدد الطريقة الفعل HTTP. بالنسبة لهذه المقالة، حدد GET.
• يتم إلحاق urlTemplate بعنوان محدد مواقع الويب الأساسي لواجهة برمجة التطبيقات ويحدد عملية HTTP واحدة. بالنسبة لهذه المقالة، استخدم /api/values إذا قمت بإضافة خدمة الواجهة الخلفية.NET أو getMessage إذا قمت بإضافة خدمة الواجهة الخلفية Java. بشكل افتراضي، يكون مسار عنوان URL المحدد هنا هو مسار محدد مواقع الويب المرسل إلى خدمة Service Fabric الخلفية. إذا كنت تستخدم نفس مسار محدد مواقع الويب هنا الذي تستخدمه خدمتك، مثل "/api/values"، فستعمل العملية دون مزيد من التعديل. يمكنك أيضا تحديد مسار محدد مواقع الويب هنا يختلف عن مسار محدد مواقع الويب المستخدم من قبل خدمة Service Fabric الخلفية الخاصة بك، وفي هذه الحالة تحتاج أيضا إلى تحديد إعادة كتابة مسار في سياسة التشغيل الخاصة بك لاحقا.

Microsoft.ApiManagement/service/apis/policies

يقوم Microsoft.ApiManagement/service/apis/policies بإنشاء نهج الواجهة الخلفية، الذي يربط كل شيء معا. هذا هو المكان الذي تقوم فيه بتكوين خدمة Service Fabric الخلفية التي يتم توجيه الطلبات إليها. يمكنك تطبيق هذه السياسة على أي عملية واجهة برمجة التطبيقات. لمزيد من المعلومات، راجع نظرة عامة على عامل الجهاز الظاهري.

يوفر تكوين الواجهة الخلفية لـ Service Fabric عناصر التحكم التالية في توجيه الطلب:

• تحديد مثيل الخدمة عن طريق تحديد اسم مثيل خدمة Service Fabric، إما مشفر (على سبيل المثال، "fabric:/myapp/myservice") أو تم إنشاؤه من طلب HTTP (على سبيل المثال، "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]).
• دقة القسم عن طريق إنشاء مفتاح تقسيم باستخدام أي نظام تقسيم Service Fabric.
• اختيار نسخة طبق الأصل للخدمات الجيدة.
• شروط إعادة محاولة الحل التي تسمح لك بتحديد شروط إعادة حل موقع خدمة وإعادة إرسال طلب.

policyContent هو محتوى XML الهارب من Json للسياسة. بالنسبة لهذه المقالة، قم بإنشاء نهج خلفية لتوجيه الطلبات مباشرة إلى خدمة .NET أو Java عديمة الحالة التي تم نشرها مسبقا. أضف سياسة set-backend-service ضمن النهج الواردة. استبدل قيمة sf-service-instance-name بما إذا كنت قد قمت مسبقا بنشر خدمة الواجهة الخلفية .NET أو fabric:/ApiApplication/WebApiService إذا قمت بنشر fabric:/EchoServerApplication/EchoServerService خدمة Java. يشير backend-id إلى مورد الواجهة الخلفية، وفي هذه الحالة المورد المحدد Microsoft.ApiManagement/service/backends في قالب apim.json. يمكن أن يشير معرف الواجهة الخلفية أيضا إلى مورد خلفية آخر تم إنشاؤه باستخدام واجهات برمجة تطبيقات API Management. بالنسبة لهذه المقالة، قم بتعيين backend-id إلى قيمة المعلمة service_fabric_backend_name.

<policies>
  <inbound>
    <base/>
    <set-backend-service
        backend-id="servicefabric"
        sf-service-instance-name="service-name"
        sf-resolve-condition="@(context.LastError?.Reason == "BackendConnectionFailure")" />
  </inbound>
  <backend>
    <base/>
  </backend>
  <outbound>
    <base/>
  </outbound>
</policies>

للحصول على مجموعة كاملة من سمات نهج الواجهة الخلفية لـ Service Fabric، راجع وثائق الواجهة الخلفية لـ API Management

تعيين المعلمات ونشر API Management

املأ المعلمات الفارغة التالية في apim.parameters.json للنشر.

المعلمة	القيمة
apimInstanceName	sf-apim
apimPublisherEmail	myemail@contosos.com
apimSku	المطور
serviceFabricCertificateName	sfclustertutorialgroup320171031144217
certificatePassword	q6D7nN%6ck@6
serviceFabricCertificateThumbprint	C4C1E541AD512B8065280292A8BA6079C3F26F10
serviceFabricCertificate	<سلسلة مشفرة base-64>
مسار محدد مواقع الويب	/api/values
clusterHttpManagementEndpoint	https://mysfcluster.southcentralus.cloudapp.azure.com:19080
inbound_policy	<سلسلة XML>

certificatePassword وserviceFabricCertificateThumbprint يجب أن تتطابق مع شهادة نظام المجموعة المستخدمة لإعداد المجموعة.

serviceFabricCertificate هي الشهادة كسلسلة مشفرة base-64، والتي يمكن إنشاؤها باستخدام البرنامج النصي التالي:

$bytes = [System.IO.File]::ReadAllBytes("C:\mycertificates\sfclustertutorialgroup220171109113527.pfx");
$b64 = [System.Convert]::ToBase64String($bytes);
[System.Io.File]::WriteAllText("C:\mycertificates\sfclustertutorialgroup220171109113527.txt", $b64);

في inbound_policy، استبدل قيمة sf-service-instance-name بما إذا كنت قد قمت مسبقا بنشر خدمة الواجهة الخلفية .NET أو fabric:/ApiApplication/WebApiService إذا قمت بنشر fabric:/EchoServerApplication/EchoServerService خدمة Java. يشير backend-id إلى مورد الواجهة الخلفية، وفي هذه الحالة المورد المحدد Microsoft.ApiManagement/service/backends في قالب apim.json. يمكن أن يشير معرف الواجهة الخلفية أيضا إلى مورد خلفية آخر تم إنشاؤه باستخدام واجهات برمجة تطبيقات API Management. بالنسبة لهذه المقالة، قم بتعيين backend-id إلى قيمة المعلمة service_fabric_backend_name.

<policies>
  <inbound>
    <base/>
    <set-backend-service
        backend-id="servicefabric"
        sf-service-instance-name="service-name"
        sf-resolve-condition="@(context.LastError?.Reason == "BackendConnectionFailure")" />
  </inbound>
  <backend>
    <base/>
  </backend>
  <outbound>
    <base/>
  </outbound>
</policies>

استخدم البرنامج النصي التالي لنشر Resource Manager القالب وملفات المعلمات لـ API Management:

$groupname = "sfclustertutorialgroup"
$clusterloc="southcentralus"
$templatepath="C:\clustertemplates"

New-AzResourceGroupDeployment -ResourceGroupName $groupname -TemplateFile "$templatepath\network-apim.json" -TemplateParameterFile "$templatepath\network-apim.parameters.json" -Verbose

New-AzResourceGroupDeployment -ResourceGroupName $groupname -TemplateFile "$templatepath\apim.json" -TemplateParameterFile "$templatepath\apim.parameters.json" -Verbose

ResourceGroupName="sfclustertutorialgroup"
az deployment group create --name ApiMgmtNetworkDeployment --resource-group $ResourceGroupName --template-file network-apim.json --parameters @network-apim.parameters.json

az deployment group create --name ApiMgmtDeployment --resource-group $ResourceGroupName --template-file apim.json --parameters @apim.parameters.json

اختبره

يمكنك الآن محاولة إرسال طلب إلى الخدمة الخلفية في Service Fabric من خلال API Management مباشرة من مدخل Azure.

1. في خدمة API Management، حدد واجهة برمجة التطبيقات.

2. في واجهة برمجة تطبيقات Service Fabric التي أنشأتها في الخطوات السابقة، حدد علامة التبويب اختبار ثم عملية القيم.

3. انقر على الزر ⁧⁩إرسال⁧⁩ لإرسال طلب اختبار إلى واجهة برمجة تطبيقات الويب. من المفترض أن ترى استجابة HTTP مماثلة لـ:

   HTTP/1.1 200 OK
   
   Transfer-Encoding: chunked
   
   Content-Type: application/json; charset=utf-8
   
   Vary: Origin
   
   Ocp-Apim-Trace-Location: https://apimgmtstodhwklpry2xgkdj.blob.core.windows.net/apiinspectorcontainer/PWSQOq_FCDjGcaI1rdMn8w2-2?sv=2015-07-08&sr=b&sig=MhQhzk%2FEKzE5odlLXRjyVsgzltWGF8OkNzAKaf0B1P0%3D&se=2018-01-28T01%3A04%3A44Z&sp=r&traceId=9f8f1892121e445ea1ae4d2bc8449ce4
   
   Date: Sat, 27 Jan 2018 01:04:44 GMT
   
   
   ["value1", "value2"]
   

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

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

قم بتسجيل الدخول إلى Azure وحدد معرف الاشتراك الذي تريد باستخدامه إزالة نظام المجموعة. يمكنك العثور على معرف الاشتراك عن طريق تسجيل الدخول إلى مدخل Microsoft Azure. احذف مجموعة الموارد وجميع الموارد المرتبطة بها باستخدام Remove-AzResourceGroup cmdlet.

$ResourceGroupName = "sfclustertutorialgroup"
Remove-AzResourceGroup -Name $ResourceGroupName -Force

ResourceGroupName="sfclustertutorialgroup"
az group delete --name $ResourceGroupName

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

تعرف على المزيد حول استخدام API Management.

يمكنك أيضا استخدام مدخل Azure لإنشاء واجهات خلفية لـ Service Fabric لـ API Management وإدارتها.