نشر Microsoft Azure Data Manager لواجهات برمجة تطبيقات الطاقة إلى بوابة API آمنة

تعمل Azure API Management كوسيط حاسم بين تطبيقات العميل وواجهات برمجة التطبيقات الخلفية. يسهل على العملاء الوصول إلى الخدمات عن طريق إخفاء التفاصيل التقنية ومنح المؤسسات التحكم في أمان واجهة برمجة التطبيقات.

من خلال نشر Azure Data Manager لواجهات برمجة تطبيقات الطاقة من خلال Azure API Management، يمكنك استخدام قدرة Azure Data Manager for Energy Private Link لحركة المرور الخاصة وإزالة الوصول العام المباشر تماما إلى المثيل الخاص بك.

توضح هذه المقالة كيفية إعداد Azure API Management لتأمين Azure Data Manager لواجهات برمجة تطبيقات الطاقة.

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

تحتاج إلى المكونات والأدوات والمعلومات التالية المتوفرة لإكمال هذه المعاينة:

• شبكة ظاهرية مع شبكتين فرعيتين متاحتين، واحدة لنقطة النهاية الخاصة Azure Data Manager for Energy والأخرى لحقن الشبكة الظاهرية لإدارة واجهة برمجة تطبيقات Azure.

• تم تكوين Azure Data Manager for Energy مع ارتباط خاص تم نشره في الشبكة الفرعية.

• تم توفير Azure API Management ونشرها في الشبكة الظاهرية باستخدام حقن الشبكة الظاهرية. حدد الوضع الخارجي ، أو راجع قسم الخيارات الأخرى في الوضع الداخلي .

• محرر التعليمات البرمجية مثل Visual Studio Code لتعديل مواصفات Azure Data Manager for Energy OpenAPI لكل من واجهات برمجة التطبيقات التي يتم نشرها.

• قم بتنزيل Azure Data Manager لمواصفات Energy OpenAPI من مستودع GitHub لعينات adme. انتقل إلى دليل rest-apis وحدد الإصدار المناسب للتطبيق الخاص بك.

• من تسجيل التطبيق لتطبيق Azure Data Manager for Energy الذي تم استخدامه في وقت التوفير، لاحظ معرف المستأجر ومعرف العميل:

  

إعداد مثيل APIM

استخدم الخطوات التالية لإجراء تغييرات التكوين على مثيل Azure API Management:

1. من جزء All resources، اختر مثيل Azure API Management المستخدم لهذه المعاينة.

2. انتقل إلى صفحة إعدادات المنتجات عن طريق اختيارها من تجميع إعدادات واجهة برمجة التطبيقات:

   

3. في صفحة المنتجات، حدد الزر إضافة لإنشاء منتج جديد. تسمح لك منتجات إدارة واجهة برمجة تطبيقات Azure بإنشاء مجموعة غير مقترنة بشكل فضفاض من واجهات برمجة التطبيقات التي يمكن التحكم فيها وإدارتها معا. نقوم بإنشاء منتج ل Azure Data Manager لواجهات برمجة تطبيقات الطاقة.

4. في صفحة إضافة منتج، أدخل القيم الموضحة في الجدول التالي لإنشاء المنتج.

   

   الإعداد	القيمة
   الاسم المعروض‬	"Azure Data Manager for Energy Product"
   بطاقة تعريف	"adme-product"
   ‏‏الوصف	أدخل وصفا يشير إلى المطورين لواجهات برمجة التطبيقات التي نقوم بتجميعها
   تم النشر	حدد هذا المربع لنشر المنتج الذي نقوم بإنشائه
   يتطلب الاشتراك	حدد هذا المربع لتوفير التخويل الأساسي لواجهات برمجة التطبيقات الخاصة بنا
   يتطلب الموافقة	حدد اختياريا ما إذا كنت تريد من المسؤول مراجعة محاولات الاشتراك في هذا المنتج وقبولها أو رفضها. إذا لم يتم تحديدها، تتم الموافقة على محاولات الاشتراك تلقائيا.
   حد عدد الاشتراكات	حدد عدد الاشتراكات المتزامنة المتعددة بشكل اختياري.
   ‏‏الشروط القانونية	حدد اختياريا شروط الاستخدام للمنتج الذي يجب على المشتركين قبوله لاستخدام المنتج.
   واجهات برمجة التطبيقات (API)	يمكننا تجاهل هذه الميزة. نقوم بربط واجهات برمجة التطبيقات لاحقا في هذه المقالة

5. حدد إنشاء لإنشاء قائمة العبارة الجديدة.

6. بمجرد الانتهاء من إنشاء المنتج، يقوم المدخل بإرجاعك إلى صفحة المنتجات. حدد منتجنا الذي تم إنشاؤه حديثا Azure Data Manager لمنتج الطاقة للانتقال إلى صفحة مورد المنتج. حدد عنصر قائمة إعداد النهج من قائمة الإعدادات.

   

7. في جزء Inbound processing، حدد الأيقونة </> ، والتي تسمح لك بتعديل نهج المنتج. يمكنك إضافة ثلاث مجموعات من النهج لتحسين أمان الحل:

   • التحقق من صحة الرمز المميز لمعرف Entra لضمان اكتشاف الطلبات غير المصادق عليها في بوابة واجهة برمجة التطبيقات
   • حد الحصة النسبية والمعدل للتحكم في معدل الطلبات وإجمالي الطلبات/البيانات المنقولة
   • تعيين الرأس لإزالة الرؤوس التي تم إرجاعها بواسطة واجهات برمجة التطبيقات الخلفية، والتي قد تكشف عن تفاصيل حساسة للجهات الفاعلة السيئة المحتملة

8. أضف نهج validate-azure-ad-token التالي إلى التكوين الخاص بنا داخل العلامات الواردة وتحت العلامة الأساسية. تأكد من تحديث القالب بتفاصيل تطبيق Microsoft Entra ID المذكورة في المتطلبات الأساسية.

   <validate-azure-ad-token tenant-id="INSERT_TENANT_ID">
       <client-application-ids>
           <application-id>INSERT_APP_ID</application-id>
       </client-application-ids>
   </validate-azure-ad-token>
   

9. أسفل نهج validate-azure-ad-token، أضف نهج الحصة النسبية والحد من المعدل التالية. تحديث قيم تكوين النهج حسب الاقتضاء للمستهلكين.

   <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
   <quota calls="10000" bandwidth="40000" renewal-period="3600" />
   

10. إلى القسم الصادر من محرر النهج وضمن العلامة الأساسية، أضف نهج رأس المجموعة التالية.

    <set-header name="x-envoy-upstream-service-time" exists-action="delete" />
    <set-header name="x-internal-uri-pattern" exists-action="delete" />
    

11. حدد حفظ لتثبيت التغييرات التي قمت بإجرائها.

    

12. انتقل مرة أخرى إلى مورد APIM في مدخل Microsoft Azure. حدد عنصر القائمة Backends وحدد الزر + Add.

    

13. في نموذج الواجهة الخلفية، أدخل القيم الموضحة في الجدول التالي لإنشاء الخلفية.

    الإعداد	القيمة‬
    الاسم	"adme-backend"
    ‏‏الوصف	أدخل وصفا يشير إلى المطورين أن هذه الواجهة الخلفية مرتبطة ب Azure Data Manager لواجهات برمجة تطبيقات الطاقة
    نوع	عنوان URL مخصص
    عنوان URL لوقت التشغيل	أدخل Azure Data Manager ل Energy URI _ex. https://INSERT_ADME_NAME.energy.azure.com/
    التحقق من صحة سلسلة الشهادات	محدد
    التحقق من صحة اسم الشهادة	محدد

    

14. حدد إنشاء لإنشاء الخلفية. سيتم استخدام هذه الواجهة الخلفية التي تم إنشاؤها حديثا في القسم التالي عند نشر واجهات برمجة التطبيقات.

استيراد Azure Data Manager لواجهات برمجة تطبيقات الطاقة

استخدم الخطوات التالية لاستيراد وتكوين ونشر Azure Data Manager لواجهات برمجة تطبيقات الطاقة في بوابة إدارة واجهة برمجة تطبيقات Azure:

1. انتقل مرة أخرى إلى مثيل Azure API Management المستخدم في القسم الأخير.

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

3. حدد OpenAPI ضمن عنوان Create from definition .

   

4. في النافذة المشروطة إنشاء من مواصفات OpenAPI، حدد التبديل الكامل .

5. حدد موقع مواصفات OpenAPI التي قمت بتنزيلها كجزء من المتطلبات الأساسية وافتح مواصفات المخطط باستخدام محرر التعليمات البرمجية الذي تختاره. ابحث عن كلمة "الخادم" ولاحظ عنوان URL للخادم في الملف على سبيل المثال/api/schema-service/v1/.

6. حدد Select a file وحدد Schema API specification. عند اكتمال التحميل، تقوم النافذة المشروطة بتحميل بعض القيم من المواصفات.

7. بالنسبة للحول الأخرى، أدخل القيم الموضحة في الجدول التالي:

   الإعداد	القيمة‬
   تضمين معلمات الاستعلام المطلوبة في قوالب التشغيل	محدد
   ‏‫اسم العرض‬	أدخل اسم عرض منطقيا لمطوري التطبيقات على سبيل المثال، Azure Data Manager for Energy Schema Service
   الاسم	تقترح إدارة واجهة برمجة التطبيقات اسما لحالة الأحرف كباب. اختياريا، يمكن تغيير الاسم ولكن يجب أن يكون فريدا للمثيل
   ‏‏الوصف	قد تحدد مواصفات OpenAPI وصفا، إذا كان الأمر كذلك، يتم ملء الوصف تلقائيا. اختياريا، قم بتحديث الوصف لكل حالة استخدام.
   مخطط URL	حدد "كلاهما"
   لاحقة عنوان URL لواجهة برمجة التطبيقات	أدخل لاحقة لجميع واجهات برمجة تطبيقات Azure Data Manager for Energy (على سبيل المثال adme). ثم أدخل عنوان URL للخادم من الخطوة 5. يجب أن تبدو القيمة النهائية مثل /adme/api/schema-service/v1/. تسمح لنا اللاحقة بالتوافق مع العملاء الحاليين ومجموعات تطوير البرامج التي تتصل عادة ب Azure Data Manager لواجهات برمجة تطبيقات الطاقة مباشرة
   علامات	إدخال العلامات اختياريا
   المنتجات	حدد منتج "Azure Data Manager for Energy" الذي تم إنشاؤه في القسم السابق

   هام

   تحقق من صحة لاحقة عنوان URL لواجهة برمجة التطبيقات، وهذا سبب شائع للأخطاء في نشر Azure Data Manager لواجهات برمجة تطبيقات الطاقة

8. حدد Create لإنشاء واجهة API.

   

9. حدد واجهة واجهة برمجة تطبيقات المخطط التي تم إنشاؤها حديثا من قائمة واجهات برمجة التطبيقات وحدد جميع العمليات في قائمة العمليات. في جزء Inbound processing ، حدد الأيقونة </> لتحرير مستند النهج.

   

10. لتكوين واجهة برمجة التطبيقات، أضف مجموعتين من النهج:

    • تعيين Backend Service لتوجيه الطلبات إلى Azure Data Manager لمثيل الطاقة
    • أعد كتابة URI لإزالة بادئة adme وإنشاء الطلب إلى واجهة برمجة التطبيقات الخلفية. يستخدم بيان النهج هذا تعبيرات النهج لإضافة قيمة قالب Url الخاص بالعملية الحالية بشكل ديناميكي إلى عنوان URL الخاص بالخادم.

11. دون عنوان URL للخادم من الخطوة 5. أسفل العلامة الأساسية ، في القسم الوارد ، قم بإدراج عبارات النهج التالية.

    <set-backend-service backend-id="adme-backend" />
    

    <!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 -->
    <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />
    

12. حدد حفظ لتثبيت التغييرات التي قمت بإجرائها.

13. اختبر واجهة برمجة التطبيقات عن طريق تحديد عملية معلومات إصدار GET من قائمة العمليات. ثم حدد علامة التبويب Test للانتقال إلى Azure API Management Test Console.

14. أدخل القيم الموضحة في الجدول التالي. إنشاء رمز مصادقة ل Azure Data Manager for Energy. حدد إرسال لاختبار واجهة برمجة التطبيقات.

    الإعداد	القيمة‬
    معرف قسم البيانات	معرف قسم البيانات لمثيل Azure Data Manager for Energy
    المنتج	حدد Azure Data Manager لمنتج الطاقة الذي تم إنشاؤه مسبقا
    التصريح	"Bearer" ورمز المصادقة الذي أنشأته

    

15. إذا تم تكوين واجهة برمجة التطبيقات بشكل صحيح، يجب أن تشاهد استجابة HTTP 200 - OK التي تبدو مشابهة للقطة الشاشة. إذا لم يكن الأمر كما هو، فتحقق من قسم استكشاف الأخطاء وإصلاحها.

16. كرر الخطوات المذكورة أعلاه لكل Azure Data Manager لواجهة برمجة تطبيقات الطاقة والمواصفات المرتبطة بها.

استكشاف الأخطاء وإصلاحها

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

رمز	رسالة الخطأ	التفاصيل
HTTP 401 Unauthorized	Invalid Azure AD JWT	تحقق للتأكد من أن لديك عنوان مصادقة صالحا لمستأجر معرف Microsoft Entra و تطبيق العميل ل Azure Data Manager لمثيل الطاقة.
HTTP 401 Unauthorized	Azure AD JWT not present	تحقق للتأكد من إضافة عنوان المصادقة إلى طلب الاختبار.
HTTP 404 Not Found		يعني هذا الخطأ عادة أن الطلب إلى واجهة برمجة التطبيقات الخلفية يتم إجراؤه إلى عنوان URL غير صحيح. تتبع طلب واجهة برمجة التطبيقات في APIM لفهم عنوان URL الذي تم إنشاؤه لطلب الواجهة الخلفية والتأكد من أنه صالح. إذا لم يكن الأمر كما هو، فتحقق مرة أخرى من نهج إعادة كتابة url أو الخلفية.
HTTP 500 Internal Server Error	Internal server error	يعكس هذا الخطأ عادة مشكلة في تقديم الطلبات إلى واجهة برمجة التطبيقات الخلفية. عادة، في هذا السيناريو، المشكلة هي خدمات اسم المجال (DNS) ذات الصلة. تحقق للتأكد من وجود منطقة DNS خاصة تم تكوينها في الشبكات الظاهرية أو أن دقة DNS المخصصة تحتوي على معيدات التوجيه المناسبة. تتبع طلب واجهة برمجة التطبيقات في APIM لفهم ما هو طلب الواجهة الخلفية الذي تم إجراؤه والأخطاء التي تقوم APIM بالإبلاغ عنها عند محاولة إجراء الطلب.

اعتبارات أخرى

وضع الشبكات الظاهرية الداخلية لإدارة واجهة برمجة التطبيقات

يعزل الوضع الداخلي إدارة واجهة برمجة تطبيقات Azure تماما بدلا من الكشف عن نقاط النهاية عبر عنوان IP العام. في هذا التكوين، يمكن للمؤسسات التأكد من أن جميع Azure Data Manager for Energy داخلية. نظرا لأن Azure Data Manager for Energy هو حل تعاون للعمل مع الشركاء والعملاء، فقد لا يكون هذا السيناريو مفيدا كما هو.

بوابة التطبيق مع جدار حماية تطبيق الويب

بدلا من استخدام وضع الشبكة الظاهرية الداخلية وحدها، تختار العديد من المؤسسات تطبيق آلية وكيل عكسي آمنة لعرض الوضع الداخلي لمثيل Azure API Management للشركاء والعملاء الخارجيين. يظل مثيل الوضع الداخلي معزولا تماما مع دخول محكم التحكم يجب أن يمر عبر الوكيل.

Azure App Gateway هي خدمة شائعة لاستخدامها كوكيل عكسي. تحتوي Azure App Gateway أيضا على إمكانية جدار حماية تطبيق الويب (WAF)، والتي تكتشف بنشاط الهجمات المحتملة ضد الثغرات الأمنية في التطبيقات وواجهات برمجة التطبيقات.

تكوين إدارة واجهة برمجة تطبيقات Azure مع مجال مخصص

ميزة شائعة أخرى لهذه البنية هي تطبيق مجال مخصص على واجهات برمجة التطبيقات. على الرغم من أن Azure Data Manager for Energy لا يدعم هذه الميزة، يمكنك تكوين مجال مخصص على Azure API Management بدلا من ذلك.

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

المحتوى ذو الصلة

• أساس أمان Azure لإدارة واجهة برمجة التطبيقات

• أساس أمان Azure ل Azure Data Manager for Energy

• البرنامج التعليمي: إنشاء بوابة تطبيق باستخدام Web Application Firewall باستخدام مدخل Microsoft Azure