التشغيل السريع: نشر تطبيق RESTful API إلى Azure Spring Apps
إشعار
سيتم إهمال الخطط الأساسية والقياسية والمؤسسة بدءا من منتصف مارس 2025، مع فترة تقاعد 3 سنوات. نوصي بالانتقال إلى Azure Container Apps. لمزيد من المعلومات، راجع إعلان إيقاف Azure Spring Apps.
سيتم إهمال الاستهلاك القياسي والخطة المخصصة بدءا من 30 سبتمبر 2024، مع إيقاف التشغيل الكامل بعد ستة أشهر. نوصي بالانتقال إلى Azure Container Apps. لمزيد من المعلومات، راجع ترحيل استهلاك Azure Spring Apps القياسي وخطة مخصصة إلى Azure Container Apps.
توضح هذه المقالة كيفية نشر تطبيق RESTful API محمي بواسطة معرف Microsoft Entra إلى Azure Spring Apps. نموذج المشروع هو إصدار مبسط يستند إلى تطبيق ويب Simple Todo ، والذي يوفر فقط خدمة الواجهة الخلفية ويستخدم معرف Microsoft Entra لحماية واجهات برمجة تطبيقات RESTful.
تتم حماية واجهات برمجة التطبيقات RESTful هذه من خلال تطبيق التحكم في الوصول استنادا إلى الدور (RBAC). لا يمكن للمستخدمين المجهولين الوصول إلى أي بيانات ولا يسمح لهم بالتحكم في الوصول لمستخدمين مختلفين. المستخدمين المجهولين لديهم الأذونات الثلاثة التالية فقط:
- اقرأ: باستخدام هذا الإذن، يمكن للمستخدم قراءة بيانات ToDo.
- الكتابة: باستخدام هذا الإذن، يمكن للمستخدم إضافة بيانات ToDo أو تحديثها.
- حذف: باستخدام هذا الإذن، يمكن للمستخدم حذف بيانات ToDo.
بعد نجاح النشر، يمكنك عرض واجهات برمجة التطبيقات واختبارها من خلال واجهة مستخدم Swagger.
يوضح الرسم التخطيطي التالي بنية النظام:
توضح هذه المقالة الخيارات التالية لإنشاء الموارد ونشرها في Azure Spring Apps:
- يوفر خيار المكون الإضافي لمدخل Azure + Maven طريقة أكثر تقليدية لإنشاء الموارد ونشر التطبيقات خطوة بخطوة. هذا الخيار مناسب لمطوري Spring الذين يستخدمون خدمات سحابة Azure لأول مرة.
- يعد خيار Azure Developer CLI طريقة أكثر كفاءة لإنشاء الموارد ونشر التطبيقات تلقائيا من خلال أوامر بسيطة. يستخدم Azure Developer CLI قالب لتوفير موارد Azure المطلوبة ونشر التعليمات البرمجية للتطبيق. هذا الخيار مناسب لمطوري Spring الذين هم على دراية بخدمات Azure السحابية.
توضح هذه المقالة الخيارات التالية لإنشاء الموارد ونشرها في Azure Spring Apps:
- يوفر خيار المكون الإضافي لمدخل Azure + Maven طريقة أكثر تقليدية لإنشاء الموارد ونشر التطبيقات خطوة بخطوة. هذا الخيار مناسب لمطوري Spring الذين يستخدمون خدمات سحابة Azure لأول مرة.
- يستخدم خيار Azure CLI أداة سطر أوامر قوية لإدارة موارد Azure. هذا الخيار مناسب لمطوري Spring الذين هم على دراية بخدمات Azure السحابية.
1. المتطلبات الأساسية
اشتراك Azure. إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.
أحد الأدوار التالية:
- المسؤول العام أو مسؤول الدور المتميز، لمنح الموافقة للتطبيقات التي تطلب أي إذن، لأي واجهة برمجة تطبيقات.
- مسؤول تطبيق السحابة أو مسؤول التطبيق، لمنح الموافقة للتطبيقات التي تطلب أي إذن لأي واجهة برمجة تطبيقات، باستثناء أدوار تطبيق Microsoft Graph (أذونات التطبيق).
- دور دليل مخصص يتضمن الإذن بمنح أذونات للتطبيقات، للأذونات التي يتطلبها التطبيق.
لمزيد من المعلومات، راجع منح موافقة المسؤول على مستوى المستأجر على أحد التطبيقات.
إذا كنت تقوم بنشر مثيل خطة Azure Spring Apps Enterprise للمرة الأولى في الاشتراك الهدف، فشاهد قسم المتطلبات في خطة المؤسسة في Azure Marketplace.
Git.
Java Development Kit (JDK)، الإصدار 17.
مستأجر Microsoft Entra. للحصول على إرشادات حول إنشاء مستأجر، راجع التشغيل السريع: إنشاء مستأجر جديد في معرف Microsoft Entra.
اشتراك Azure، إذا لم يكن لديك اشتراك Azure، فبادر بإنشاء حساب Azure مجاني قبل البدء.
أحد الأدوار التالية:
- المسؤول العام أو مسؤول الدور المتميز، لمنح الموافقة للتطبيقات التي تطلب أي إذن، لأي واجهة برمجة تطبيقات.
- مسؤول تطبيق السحابة أو مسؤول التطبيق، لمنح الموافقة للتطبيقات التي تطلب أي إذن لأي واجهة برمجة تطبيقات، باستثناء أدوار تطبيق Microsoft Graph (أذونات التطبيق).
- دور دليل مخصص يتضمن الإذن بمنح أذونات للتطبيقات، للأذونات التي يتطلبها التطبيق.
لمزيد من المعلومات، راجع منح موافقة المسؤول على مستوى المستأجر على أحد التطبيقات.
Git.
Java Development Kit (JDK)، الإصدار 17.
مستأجر Microsoft Entra. للحصول على إرشادات حول إنشاء مستأجر، راجع التشغيل السريع: إنشاء مستأجر جديد في معرف Microsoft Entra.
2. إعداد مشروع الربيع
لنشر تطبيق RESTful API، الخطوة الأولى هي إعداد مشروع Spring للتشغيل محليا.
استخدم الخطوات التالية لاستنساخ التطبيق وتشغيله محليا:
استخدم الأمر التالي لاستنساخ نموذج المشروع من GitHub:
git clone https://github.com/Azure-Samples/ASA-Samples-Restful-Application.git
إذا كنت ترغب في تشغيل التطبيق محليا، فأكمل الخطوات الموجودة في واجهات برمجة التطبيقات Expose RESTful وقم بتحديث أقسام تكوين التطبيق أولا، ثم استخدم الأمر التالي لتشغيل نموذج التطبيق مع Maven:
cd ASA-Samples-Restful-Application ./mvnw spring-boot:run
3. إعداد بيئة السحابة
الموارد الرئيسية المطلوبة لتشغيل نموذج التطبيق هذا هي مثيل Azure Spring Apps وقاعدة بيانات Azure لمثيل PostgreSQL. تصف الأقسام التالية كيفية إنشاء هذه الموارد.
3.1. سجِّل الدخول إلى مدخل Azure
انتقل إلى مدخل Microsoft Azure وأدخل بيانات الاعتماد لتسجيل الدخول إلى المدخل. طريقة العرض الافتراضية هي لوحة معلومات الخدمة.
3.2. إنشاء مثيل Azure Spring Apps
استخدم الخطوات التالية لإنشاء مثيل خدمة Azure Spring Apps:
حدد Create a resource في زاوية مدخل Microsoft Azure.
حدد حساب>Azure Spring Apps.
املأ نموذج «Basics» بالمعلومات التالية:
الإعدادات القيمة المقترحة الوصف الاشتراك اسم الاشتراك الخاص بك. اشتراك Azure الذي تريد استخدامه لخادمك. إذا كان لديك اشتراكات متعددة، فاختر الاشتراك الذي تود الدفع فيه مقابل المورد. مجموعة الموارد myresourcegroup اسم مجموعة موارد جديد أو اسم موجود من اشتراكك. الاسم myasa اسم فريد يعرف خدمة Azure Spring Apps. يجب أن يتراوح الاسم بين 4 أحرف و32 حرفاً، ويجب أن يحتوي على أحرف صغيرة وأرقام وواصلات فقط. يجب أن يكون الحرف الأول من اسم الخدمة حرفاً ويجب أن يكون الحرف الأخير إما حرفاً أو رقماً. تخطيط مؤسسة خطة التسعير التي تحدد المورد والتكلفة المرتبطة بالمثيل الخاص بك. المنطقة المنطقة الأقرب إلى المستخدمين. الموقع الأقرب إلى المستخدمين. المنطقة زائدة عن الحاجة غير محدد خيار إنشاء خدمة Azure Spring Apps في منطقة توفر Azure. هذه الميزة غير مدعومة حاليا في جميع المناطق. خطة IP للبرامج الدفع أولاً بأول خطة التسعير التي تتيح لك الدفع أثناء استخدام Azure Spring Apps. حيث المحدد خانة اختيار الاتفاقية المرتبطة بعرض Marketplace. مطلوب منك تحديد خانة الاختيار هذه. توزيع نموذج المشروع غير محدد خيار استخدام نموذج التطبيق المضمن. حدد مراجعة وإنشاء لمراجعة التحديدات. ثم حدد Create لتوفير مثيل Azure Spring Apps.
من شريط الأدوات، حدد رمز «Notifications» (جرس) لمراقبة عملية النشر. بعد انتهاء النشر، يمكنك تحديد تثبيت بلوحة المعلومات، والتي تنشئ تجانبا لهذه الخدمة على لوحة معلومات مدخل Microsoft Azure كاختصار لصفحة نظرة عامة على الخدمة.
حدد Go to resource للانتقال إلى صفحة نظرة عامة على Azure Spring Apps.
3.3. إعداد مثيل PostgreSQL
استخدم الخطوات التالية لإنشاء قاعدة بيانات Azure لخادم PostgreSQL:
انتقل إلى مدخل Microsoft Azure وحدد Create a resource.
حدد قواعد بيانات>Azure Database لـPostgreSQL.
حدد خيار النشر «Flexible server».
املأ علامة التبويب Basics بالمعلومات التالية:
- اسم الخادم: my-demo-pgsql
- المنطقة: شرق الولايات المتحدة
- إصدار PostgreSQL: 14
- نوع حمل العمل: التطوير
- تمكين قابلية الوصول العالية: غير محدد
- أسلوب المصادقة: مصادقة PostgreSQL فقط
- اسم مستخدم المسؤول: myadmin
- كلمة المرور وتأكيد كلمة المرور: أدخل كلمة مرور.
استخدم المعلومات التالية لتكوين علامة التبويب Networking :
- أسلوب الاتصال: الوصول العام (عناوين IP المسموح بها)
- السماح بالوصول العام من أي خدمة Azure داخل Azure إلى هذا الخادم: محدد
حدد Review + create لمراجعة التحديدات الخاصة بك، وحدد Create لتوفير الخادم. قد تستغرق هذه العملية بضع دقائق.
انتقل إلى خادم PostgreSQL في مدخل Microsoft Azure. في صفحة نظرة عامة ، ابحث عن قيمة اسم الخادم، ثم سجلها لاستخدامها لاحقا. تحتاج إليه لتكوين متغيرات البيئة للتطبيق في Azure Spring Apps.
حدد Databases من قائمة التنقل لإنشاء قاعدة بيانات - على سبيل المثال، todo.
3.4. توصيل مثيل التطبيق بمثيل PostgreSQL
استخدم الخطوات التالية لتوصيل مثيلات الخدمة:
انتقل إلى مثيل Azure Spring Apps في مدخل Azure.
من قائمة التنقل، افتح التطبيقات، ثم حدد إنشاء تطبيق.
في صفحة Create App ، املأ اسم التطبيق simple-todo-api، ثم حدد Java artifacts كنوع النشر.
حدد إنشاء لإنهاء إنشاء التطبيق ثم حدد التطبيق لعرض التفاصيل.
انتقل إلى التطبيق الذي أنشأته في مدخل Microsoft Azure. في صفحة Overview ، حدد Assign endpoint لعرض نقطة النهاية العامة للتطبيق. احفظ عنوان URL للوصول إلى التطبيق بعد النشر.
حدد Service Connector من جزء التنقل، ثم حدد Create لإنشاء اتصال خدمة جديد.
املأ علامة التبويب Basics بالمعلومات التالية:
- نوع الخدمة: DB لخادم PostgreSQL المرن
- اسم الاتصال: يتم ملء اسم تم إنشاؤه تلقائيا، والذي يمكن تعديله أيضا.
- Subscription: حدد اشتراكك.
- خادم PostgreSQL المرن: my-demo-pgsql
- قاعدة بيانات PostgreSQL: حدد قاعدة البيانات التي أنشأتها.
- نوع العميل: SpringBoot
قم بتكوين علامة التبويب Next: Authentication بالمعلومات التالية:
- حدد نوع المصادقة الذي تريد استخدامه بين خدمة الحوسبة والخدمة المستهدفة.: حدد سلسلة الاتصال.
- متابعة مع...: حدد بيانات اعتماد قاعدة البيانات
- اسم المستخدم: myadmin
- كلمة المرور: أدخل كلمة المرور الخاصة بك.
حدد Next: Networking. استخدم الخيار الافتراضي تكوين قواعد جدار الحماية لتمكين الوصول إلى الخدمة الهدف.
حدد Next: Review and Create لمراجعة التحديدات، ثم حدد Create لإنشاء الاتصال.
3.5. كشف واجهات برمجة التطبيقات RESTful
استخدم الخطوات التالية لعرض واجهات برمجة تطبيقات RESTful في معرف Microsoft Entra:
قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فاستخدم عامل تصفية الدليل + الاشتراك ( ) لتحديد المستأجر الذي تريد تسجيل تطبيق فيه.
ابحث عن Microsoft Entra ID وحدده.
ضمن Manage، حدد App registrationsتسجيل > جديد.
أدخل اسما لتطبيقك في حقل الاسم - على سبيل المثال، Todo. قد يرى مستخدمو التطبيق الخاص بك هذا الاسم، ويمكنك تغييره لاحقًا.
بالنسبة إلى أنواع الحسابات المدعومة، حدد الحسابات في أي دليل تنظيمي (أي دليل Microsoft Entra - متعدد المستأجرين) وحسابات Microsoft الشخصية.
حدد Register لإنشاء التطبيق.
في صفحة "Overview" للتطبيق، ابحث عن قيمة Application (client) ID وسجله للاستخدام لاحقاً. تحتاج إليه لتكوين ملف تكوين YAML لهذا المشروع.
ضمن إدارة، حدد كشف واجهة برمجة التطبيقات، وابحث عن معرف التطبيق URI في بداية الصفحة، ثم حدد إضافة.
في صفحة تحرير معرف التطبيق URI ، اقبل معرف التطبيق المقترح URI (
api://{client ID}
) أو استخدم اسما ذا معنى بدلا من معرف العميل، مثلapi://simple-todo
، ثم حدد حفظ.ضمن إدارة، حدد كشف واجهة برمجة التطبيقات>إضافة نطاق، ثم أدخل المعلومات التالية:
- بالنسبة إلى اسم النطاق، أدخل ToDo.Read.
- بالنسبة إلى من يمكنه الموافقة، حدد المسؤولون فقط.
- للحصول على اسم عرض موافقة المسؤول، أدخل قراءة بيانات ToDo.
- للحصول على وصف موافقة المسؤول، أدخل السماح للمستخدمين المصادق عليهم بقراءة بيانات ToDo.
- بالنسبة إلى State، احتفظ به ممكنا.
- حدد إضافة نطاق.
كرر الخطوات السابقة لإضافة النطاقين الآخرين: ToDo.Write و ToDo.Delete.
3.6. تحديث تكوين التطبيق
استخدم الخطوات التالية لتحديث ملف YAML لاستخدام معلومات التطبيق المسجلة في Microsoft Entra لإنشاء علاقة مع تطبيق واجهة برمجة تطبيقات RESTful:
حدد موقع ملف
simple-todo-api
src/main/resources/application.yml للتطبيق. قم بتحديث التكوين فيspring.cloud.azure.active-directory
القسم لمطابقة المثال التالي. تأكد من استبدال العناصر النائبة بالقيم التي قمت بإنشائها مسبقا.spring: cloud: azure: active-directory: profile: tenant-id: <tenant> credential: client-id: <your-application-ID-of-ToDo> app-id-uri: <your-application-ID-URI-of-ToDo>
إشعار
في الرموز المميزة v1.0، يتطلب التكوين معرف العميل لواجهة برمجة التطبيقات، بينما في الرموز المميزة v2.0، يمكنك استخدام معرف العميل أو معرف التطبيق URI في الطلب. يمكنك تكوين كليهما لإكمال التحقق من صحة الجمهور بشكل صحيح.
القيم المسموح بها
tenant-id
هي:common
أوorganizations
consumers
أو أو معرف المستأجر. لمزيد من المعلومات حول هذه القيم، راجع قسم استخدام نقطة النهاية الخاطئة (الحسابات الشخصية والمؤسسة) في AADSTS50020 الخطأ - حساب المستخدم من موفر الهوية غير موجود في المستأجر. للحصول على معلومات حول تحويل تطبيق المستأجر الفردي، راجع تحويل تطبيق المستأجر الفردي إلى متعدد المستأجرين على معرف Microsoft Entra.استخدم الأمر التالي لإعادة إنشاء نموذج المشروع:
./mvnw clean package
4. نشر التطبيق إلى Azure Spring Apps
يمكنك الآن نشر التطبيق إلى Azure Spring Apps.
استخدم الخطوات التالية للنشر باستخدام المكون الإضافي Maven ل Azure Spring Apps:
انتقل إلى الدليل الكامل ، ثم قم بتشغيل الأمر التالي لتكوين التطبيق في Azure Spring Apps:
./mvnw com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config
تصف القائمة التالية تفاعلات الأوامر:
- تسجيل الدخول إلى OAuth2: تحتاج إلى تخويل تسجيل الدخول إلى Azure استنادا إلى بروتوكول OAuth2.
- حدد subscription: حدد رقم قائمة الاشتراك لمثيل Azure Spring Apps الذي أنشأته، والذي يتم تعيينه افتراضيا إلى الاشتراك الأول في القائمة. إذا كنت تستخدم الرقم الافتراضي، فاضغط على مفتاح الإدخال Enter مباشرة.
- استخدام Azure Spring Apps الموجودة في Azure: اضغط على y لاستخدام مثيل Azure Spring Apps الحالي.
- حدد Azure Spring Apps للنشر: حدد عدد مثيل Azure Spring Apps الذي أنشأته. إذا كنت تستخدم الرقم الافتراضي، فاضغط على مفتاح الإدخال Enter مباشرة.
- استخدم التطبيق الموجود في Azure Spring Apps <your-instance-name>: اضغط y لاستخدام التطبيق الذي تم إنشاؤه.
- تأكد من حفظ جميع التكوينات أعلاه: اضغط على y. إذا قمت بالضغط على n، فلن يتم حفظ التكوين في ملفات POM.
استخدم الأمر التالي لنشر التطبيق:
./mvnw azure-spring-apps:deploy
تصف القائمة التالية تفاعل الأمر:
- تسجيل الدخول إلى OAuth2: تحتاج إلى تخويل تسجيل الدخول إلى Azure استنادا إلى بروتوكول OAuth2.
بعد تنفيذ الأمر، يمكنك أن ترى من رسائل السجل التالية أن النشر كان ناجحا:
[INFO] Deployment Status: Running
[INFO] InstanceName:simple-todo-api-default-15-xxxxxxxxx-xxxxx Status:Running Reason:null DiscoverStatus:N/A
[INFO] Getting public url of app(simple-todo-api)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-simple-todo-api.azuremicroservices.io
5. التحقق من صحة التطبيق
يمكنك الآن الوصول إلى واجهة برمجة تطبيقات RESTful لمعرفة ما إذا كانت تعمل.
5.1. طلب رمز مميز للوصول
تعمل واجهات برمجة تطبيقات RESTful كخادم موارد، وهو محمي بواسطة معرف Microsoft Entra. قبل الحصول على رمز مميز للوصول، يجب عليك تسجيل تطبيق آخر في معرف Microsoft Entra ومنح أذونات لتطبيق العميل، الذي يسمى ToDoWeb
.
تسجيل تطبيق العميل
استخدم الخطوات التالية لتسجيل تطبيق في معرف Microsoft Entra، والذي يستخدم لإضافة أذونات ToDo
التطبيق:
قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فاستخدم عامل تصفية الدليل + الاشتراك ( ) لتحديد المستأجر الذي تريد تسجيل تطبيق فيه.
ابحث عن Microsoft Entra ID وحدده.
ضمن Manage، حدد App registrationsتسجيل > جديد.
أدخل اسما للتطبيق الخاص بك في حقل الاسم - على سبيل المثال، ToDoWeb. قد يرى مستخدمو التطبيق الخاص بك هذا الاسم، ويمكنك تغييره لاحقًا.
بالنسبة إلى أنواع الحسابات المدعومة، استخدم القيمة الافتراضية حسابات في هذا الدليل التنظيمي فقط.
حدد Register لإنشاء التطبيق.
في صفحة "Overview" للتطبيق، ابحث عن قيمة Application (client) ID وسجله للاستخدام لاحقاً. تحتاج إليها للحصول على رمز مميز للوصول.
حدد أذونات واجهة برمجة التطبيقات> وأضف إذن >واجهات برمجة التطبيقات الخاصة بي.
ToDo
حدد التطبيق الذي قمت بتسجيله مسبقا، ثم حدد أذونات ToDo.Read و ToDo.Write و ToDo.Delete. حدد إضافة أذونات.حدد منح موافقة المسؤول لاسم <> المستأجر لمنح موافقة المسؤول على الأذونات التي أضفتها.
إضافة مستخدم للوصول إلى واجهات برمجة تطبيقات RESTful
استخدم الخطوات التالية لإنشاء مستخدم عضو في مستأجر Microsoft Entra. ثم، يمكن للمستخدم إدارة بيانات التطبيق من ToDo
خلال واجهات برمجة تطبيقات RESTful.
ضمن Manage، حدد Users>New user>Create new user.
في صفحة إنشاء مستخدم جديد، أدخل المعلومات التالية:
- اسم المستخدم الأساسي: أدخل اسما للمستخدم.
- اسم العرض: أدخل اسم عرض للمستخدم.
- كلمة المرور: انسخ كلمة المرور التي تم إنشاؤها تلقائيا والمتوفرة في المربع كلمة المرور .
إشعار
يجب على المستخدمين الجدد إكمال مصادقة تسجيل الدخول الأولى وتحديث كلمات المرور الخاصة بهم، وإلا فستتلقى خطأ
AADSTS50055: The password is expired
عند الحصول على رمز الوصول المميز.عندما يقوم مستخدم جديد بتسجيل الدخول، يتلقى مطالبة الإجراء المطلوب . يمكنهم اختيار طلب لاحقا لتخطي التحقق من الصحة.
حدد «Review + create» لمراجعة اختياراتك. حدد Create لإنشاء المستخدم.
تحديث تكوين OAuth2 لتخويل واجهة مستخدم Swagger
استخدم الخطوات التالية لتحديث تكوين OAuth2 لتخويل واجهة مستخدم Swagger. بعد ذلك، يمكنك تخويل المستخدمين للحصول على رموز الوصول المميزة ToDoWeb
من خلال التطبيق.
افتح مستأجر Microsoft Entra ID في مدخل Microsoft Azure، وانتقل إلى التطبيق المسجل
ToDoWeb
.ضمن Manage، حدد Authentication، وحدد Add a platform، ثم حدد Single-page application.
استخدم التنسيق
<your-app-exposed-application-URL-or-endpoint>/swagger-ui/oauth2-redirect.html
كعنون URL لإعادة توجيه OAuth2 في حقل Redirect URIs ، ثم حدد Configure.
2. إعداد مشروع الربيع
لنشر تطبيق RESTful API، الخطوة الأولى هي إعداد مشروع Spring للتشغيل محليا.
استخدم الخطوات التالية لاستنساخ التطبيق وتشغيله محليا:
استخدم الأمر التالي لاستنساخ نموذج المشروع من GitHub:
git clone https://github.com/Azure-Samples/ASA-Samples-Restful-Application.git
إذا كنت ترغب في تشغيل التطبيق محليا، فأكمل الخطوات الموجودة في واجهات برمجة التطبيقات Expose RESTful وقم بتحديث أقسام تكوين التطبيق أولا، ثم استخدم الأمر التالي لتشغيل نموذج التطبيق مع Maven:
cd ASA-Samples-Restful-Application ./mvnw spring-boot:run
3. إعداد بيئة السحابة
الموارد الرئيسية المطلوبة لتشغيل نموذج التطبيق هذا هي مثيل Azure Spring Apps وقاعدة بيانات Azure لمثيل PostgreSQL. تصف الأقسام التالية كيفية إنشاء هذه الموارد.
3.1. سجِّل الدخول إلى مدخل Azure
انتقل إلى مدخل Microsoft Azure وأدخل بيانات الاعتماد لتسجيل الدخول إلى المدخل. طريقة العرض الافتراضية هي لوحة معلومات الخدمة.
3.2. إنشاء مثيل Azure Spring Apps
استخدم الخطوات التالية لإنشاء مثيل خدمة:
حدد Create a resource في زاوية المدخل.
حدد حساب>Azure Spring Apps.
املأ نموذج Basics. استخدم الجدول التالي كدليل لإكمال النموذج. قيمة الخطة الموصى بها هي الاستهلاك القياسي والمخصصة (معاينة).
الإعدادات القيمة المقترحة الوصف الاشتراك اسم الاشتراك الخاص بك. اشتراك Azure الذي تريد استخدامه لخادمك. إذا كان لديك اشتراكات متعددة، فاختر الاشتراك الذي تود الدفع فيه مقابل المورد. مجموعة الموارد myresourcegroup اسم مجموعة موارد جديد أو اسم موجود من اشتراكك. الاسم myasa اسم فريد يعرف خدمة Azure Spring Apps. يجب أن يتراوح الاسم بين 4 أحرف و32 حرفاً، ويجب أن يحتوي على أحرف صغيرة وأرقام وواصلات فقط. يجب أن يكون الحرف الأول من اسم الخدمة حرفاً ويجب أن يكون الحرف الأخير إما حرفاً أو رقماً. تخطيط الاستهلاك القياسي والمخصص (معاينة) تحدد خطة التسعير الموارد والتكلفة المرتبطة بالمثيل الخاص بك. المنطقة المنطقة الأقرب إلى المستخدمين. الموقع الأقرب إلى المستخدمين. بيئة تطبيقات الحاوية myenvironment خيار تحديد مثيل بيئة Container Apps لمشاركة نفس الشبكة الظاهرية مع الخدمات والموارد الأخرى. استخدم الجدول التالي كدليل لإنشاء بيئة تطبيقات الحاوية:
الإعدادات القيمة المقترحة الوصف اسم البيئة myenvironment اسم فريد يعرف خدمة بيئة Azure Container Apps. تخطيط استهلاك تحدد خطة التسعير الموارد والتكلفة المرتبطة بالمثيل الخاص بك. المنطقة زائدة عن الحاجة مُعطل خيار إنشاء خدمة Container Apps Environment في منطقة توفر Azure. حدد مراجعة وإنشاء لمراجعة التحديدات. ثم حدد Create لتوفير مثيل Azure Spring Apps.
من شريط الأدوات، حدد رمز «Notifications» (جرس) لمراقبة عملية النشر. بعد انتهاء النشر، يمكنك تحديد تثبيت بلوحة المعلومات، والتي تنشئ تجانبا لهذه الخدمة على لوحة معلومات مدخل Microsoft Azure كاختصار لصفحة نظرة عامة على الخدمة.
حدد الانتقال إلى المورد لفتح صفحة نظرة عامة على الخدمة.
هام
يحتوي ملف تعريف حمل عمل الاستهلاك على نموذج فوترة الدفع أولا بأول، دون تكلفة بدء. تتم محاسبتك على ملف تعريف حمل العمل المخصص استنادا إلى الموارد المقدمة. لمزيد من المعلومات، راجع ملفات تعريف حمل العمل في Azure Container Apps وأسعار Azure Spring Apps.
3.3. إعداد مثيل PostgreSQL
استخدم الخطوات التالية لإنشاء قاعدة بيانات Azure لخادم PostgreSQL:
انتقل إلى مدخل Microsoft Azure وحدد Create a resource.
حدد قواعد بيانات>Azure Database لـPostgreSQL.
حدد خيار النشر «Flexible server».
املأ علامة التبويب Basics بالمعلومات التالية:
- اسم الخادم: my-demo-pgsql
- المنطقة: شرق الولايات المتحدة
- إصدار PostgreSQL: 14
- نوع حمل العمل: التطوير
- تمكين قابلية الوصول العالية: غير محدد
- أسلوب المصادقة: مصادقة PostgreSQL فقط
- اسم مستخدم المسؤول: myadmin
- كلمة المرور وتأكيد كلمة المرور: أدخل كلمة مرور.
استخدم المعلومات التالية لتكوين علامة التبويب Networking :
- أسلوب الاتصال: الوصول العام (عناوين IP المسموح بها)
- السماح بالوصول العام من أي خدمة Azure داخل Azure إلى هذا الخادم: محدد
حدد Review + create لمراجعة التحديدات الخاصة بك، وحدد Create لتوفير الخادم. قد تستغرق هذه العملية بضع دقائق.
انتقل إلى خادم PostgreSQL في مدخل Microsoft Azure. في صفحة نظرة عامة ، ابحث عن قيمة اسم الخادم، ثم سجلها لاستخدامها لاحقا. تحتاج إليه لتكوين متغيرات البيئة للتطبيق في Azure Spring Apps.
حدد Databases من قائمة التنقل لإنشاء قاعدة بيانات - على سبيل المثال، todo.
3.4. توصيل مثيل التطبيق بمثيل PostgreSQL
استخدم الخطوات التالية لتوصيل مثيلات الخدمة:
انتقل إلى مثيل Azure Spring Apps في مدخل Azure.
من قائمة التنقل، افتح التطبيقات، ثم حدد إنشاء تطبيق.
في صفحة Create App ، املأ اسم التطبيق simple-todo-api وحدد Java artifacts كنوع النشر.
حدد Create لإنهاء إنشاء التطبيق وحدد التطبيق لعرض التفاصيل.
انتقل إلى التطبيق الذي أنشأته في مدخل Microsoft Azure. في صفحة Overview ، حدد Assign endpoint لعرض نقطة النهاية العامة للتطبيق. احفظ عنوان URL للوصول إلى التطبيق بعد النشر.
انتقل إلى التطبيق الذي أنشأته، وقم بتوسيع الإعدادات وحدد التكوين من قائمة التنقل، ثم حدد متغيرات البيئة لتعيين متغيرات البيئة.
أضف متغيرات البيئة التالية لاتصال PostgreSQL، ثم حدد حفظ لإنهاء تحديث تكوين التطبيق. تأكد من استبدال العناصر النائبة بالقيم الخاصة بك التي قمت بإنشائها مسبقا.
متغير البيئة القيمة SPRING_DATASOURCE_URL
jdbc:postgresql://<your-PostgreSQL-server-name>:5432/<your-PostgreSQL-database-name>
SPRING_DATASOURCE_USERNAME
<your-PostgreSQL-admin-user>
SPRING_DATASOURCE_PASSWORD
<your-PostgreSQL-admin-password>
3.5. كشف واجهات برمجة التطبيقات RESTful
استخدم الخطوات التالية لعرض واجهات برمجة تطبيقات RESTful في معرف Microsoft Entra:
قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فاستخدم عامل تصفية الدليل + الاشتراك ( ) لتحديد المستأجر الذي تريد تسجيل تطبيق فيه.
ابحث عن Microsoft Entra ID وحدده.
ضمن Manage، حدد App registrationsتسجيل > جديد.
أدخل اسما لتطبيقك في حقل الاسم - على سبيل المثال، Todo. قد يرى مستخدمو التطبيق الخاص بك هذا الاسم، ويمكنك تغييره لاحقًا.
بالنسبة إلى أنواع الحسابات المدعومة، حدد الحسابات في أي دليل تنظيمي (أي دليل Microsoft Entra - متعدد المستأجرين) وحسابات Microsoft الشخصية.
حدد Register لإنشاء التطبيق.
في صفحة "Overview" للتطبيق، ابحث عن قيمة Application (client) ID وسجله للاستخدام لاحقاً. تحتاج إليه لتكوين ملف تكوين YAML لهذا المشروع.
ضمن إدارة، حدد كشف واجهة برمجة التطبيقات، وابحث عن معرف التطبيق URI في بداية الصفحة، ثم حدد إضافة.
في صفحة تحرير معرف التطبيق URI ، اقبل معرف التطبيق المقترح URI (
api://{client ID}
) أو استخدم اسما ذا معنى بدلا من معرف العميل، مثلapi://simple-todo
، ثم حدد حفظ.ضمن إدارة، حدد كشف واجهة برمجة التطبيقات>إضافة نطاق، ثم أدخل المعلومات التالية:
- بالنسبة إلى اسم النطاق، أدخل ToDo.Read.
- بالنسبة إلى من يمكنه الموافقة، حدد المسؤولون فقط.
- للحصول على اسم عرض موافقة المسؤول، أدخل قراءة بيانات ToDo.
- للحصول على وصف موافقة المسؤول، أدخل السماح للمستخدمين المصادق عليهم بقراءة بيانات ToDo.
- بالنسبة إلى State، احتفظ به ممكنا.
- حدد إضافة نطاق.
كرر الخطوات السابقة لإضافة النطاقين الآخرين: ToDo.Write و ToDo.Delete.
3.6. تحديث تكوين التطبيق
استخدم الخطوات التالية لتحديث ملف YAML لاستخدام معلومات التطبيق المسجلة في Microsoft Entra لإنشاء علاقة مع تطبيق واجهة برمجة تطبيقات RESTful:
حدد موقع ملف
simple-todo-api
src/main/resources/application.yml للتطبيق. قم بتحديث التكوين فيspring.cloud.azure.active-directory
القسم لمطابقة المثال التالي. تأكد من استبدال العناصر النائبة بالقيم التي قمت بإنشائها مسبقا.spring: cloud: azure: active-directory: profile: tenant-id: <tenant> credential: client-id: <your-application-ID-of-ToDo> app-id-uri: <your-application-ID-URI-of-ToDo>
إشعار
في الرموز المميزة v1.0، يتطلب التكوين معرف العميل لواجهة برمجة التطبيقات، بينما في الرموز المميزة v2.0، يمكنك استخدام معرف العميل أو معرف التطبيق URI في الطلب. يمكنك تكوين كليهما لإكمال التحقق من صحة الجمهور بشكل صحيح.
القيم المسموح بها
tenant-id
هي:common
أوorganizations
consumers
أو أو معرف المستأجر. لمزيد من المعلومات حول هذه القيم، راجع قسم استخدام نقطة النهاية الخاطئة (الحسابات الشخصية والمؤسسة) في AADSTS50020 الخطأ - حساب المستخدم من موفر الهوية غير موجود في المستأجر. للحصول على معلومات حول تحويل تطبيق المستأجر الفردي، راجع تحويل تطبيق المستأجر الفردي إلى متعدد المستأجرين على معرف Microsoft Entra.استخدم الأمر التالي لإعادة إنشاء نموذج المشروع:
./mvnw clean package
4. نشر التطبيق إلى Azure Spring Apps
يمكنك الآن نشر التطبيق إلى Azure Spring Apps.
استخدم الخطوات التالية للنشر باستخدام المكون الإضافي Maven ل Azure Spring Apps:
انتقل إلى الدليل الكامل ، ثم قم بتشغيل الأمر التالي لتكوين التطبيق في Azure Spring Apps:
./mvnw com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config
تصف القائمة التالية تفاعلات الأوامر:
- تسجيل الدخول إلى OAuth2: تحتاج إلى تخويل تسجيل الدخول إلى Azure استنادا إلى بروتوكول OAuth2.
- حدد subscription: حدد رقم قائمة الاشتراك لمثيل Azure Spring Apps الذي أنشأته، والذي يتم تعيينه افتراضيا إلى الاشتراك الأول في القائمة. إذا كنت تستخدم الرقم الافتراضي، فاضغط على مفتاح الإدخال Enter مباشرة.
- استخدام Azure Spring Apps الموجودة في Azure: اضغط على y لاستخدام مثيل Azure Spring Apps الحالي.
- حدد Azure Spring Apps للنشر: حدد عدد مثيل Azure Spring Apps الذي أنشأته. إذا كنت تستخدم الرقم الافتراضي، فاضغط على مفتاح الإدخال Enter مباشرة.
- استخدم التطبيق الموجود في Azure Spring Apps <your-instance-name>: اضغط y لاستخدام التطبيق الذي تم إنشاؤه.
- تأكد من حفظ جميع التكوينات أعلاه: اضغط على y. إذا قمت بالضغط على n، فلن يتم حفظ التكوين في ملفات POM.
استخدم الأمر التالي لنشر التطبيق:
./mvnw azure-spring-apps:deploy
تصف القائمة التالية تفاعل الأمر:
- تسجيل الدخول إلى OAuth2: تحتاج إلى تخويل تسجيل الدخول إلى Azure استنادا إلى بروتوكول OAuth2.
بعد تنفيذ الأمر، يمكنك أن ترى من رسائل السجل التالية أن النشر كان ناجحا:
[INFO] Deployment(default) is successfully created
[INFO] Starting Spring App after deploying artifacts...
[INFO] Deployment Status: Running
[INFO] InstanceName:demo--default-xxxxxxx-xxxxxxxxx-xxxxx Status:Running Reason:null DiscoverStatus:NONE
[INFO] Getting public url of app(demo)...
[INFO] Application url: https://demo.<unique-identifier>.<region-name>.azurecontainerapps.io
5. التحقق من صحة التطبيق
يمكنك الآن الوصول إلى واجهة برمجة تطبيقات RESTful لمعرفة ما إذا كانت تعمل.
5.1. طلب رمز مميز للوصول
تعمل واجهات برمجة تطبيقات RESTful كخادم موارد، وهو محمي بواسطة معرف Microsoft Entra. قبل الحصول على رمز مميز للوصول، يجب عليك تسجيل تطبيق آخر في معرف Microsoft Entra ومنح أذونات لتطبيق العميل، الذي يسمى ToDoWeb
.
تسجيل تطبيق العميل
استخدم الخطوات التالية لتسجيل تطبيق في معرف Microsoft Entra، والذي يستخدم لإضافة أذونات ToDo
التطبيق:
قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فاستخدم عامل تصفية الدليل + الاشتراك ( ) لتحديد المستأجر الذي تريد تسجيل تطبيق فيه.
ابحث عن Microsoft Entra ID وحدده.
ضمن Manage، حدد App registrationsتسجيل > جديد.
أدخل اسما للتطبيق الخاص بك في حقل الاسم - على سبيل المثال، ToDoWeb. قد يرى مستخدمو التطبيق الخاص بك هذا الاسم، ويمكنك تغييره لاحقًا.
بالنسبة إلى أنواع الحسابات المدعومة، استخدم القيمة الافتراضية حسابات في هذا الدليل التنظيمي فقط.
حدد Register لإنشاء التطبيق.
في صفحة "Overview" للتطبيق، ابحث عن قيمة Application (client) ID وسجله للاستخدام لاحقاً. تحتاج إليها للحصول على رمز مميز للوصول.
حدد أذونات واجهة برمجة التطبيقات> وأضف إذن >واجهات برمجة التطبيقات الخاصة بي.
ToDo
حدد التطبيق الذي قمت بتسجيله مسبقا، ثم حدد أذونات ToDo.Read و ToDo.Write و ToDo.Delete. حدد إضافة أذونات.حدد منح موافقة المسؤول لاسم <> المستأجر لمنح موافقة المسؤول على الأذونات التي أضفتها.
إضافة مستخدم للوصول إلى واجهات برمجة تطبيقات RESTful
استخدم الخطوات التالية لإنشاء مستخدم عضو في مستأجر Microsoft Entra. ثم، يمكن للمستخدم إدارة بيانات التطبيق من ToDo
خلال واجهات برمجة تطبيقات RESTful.
ضمن Manage، حدد Users>New user>Create new user.
في صفحة إنشاء مستخدم جديد، أدخل المعلومات التالية:
- اسم المستخدم الأساسي: أدخل اسما للمستخدم.
- اسم العرض: أدخل اسم عرض للمستخدم.
- كلمة المرور: انسخ كلمة المرور التي تم إنشاؤها تلقائيا والمتوفرة في المربع كلمة المرور .
إشعار
يجب على المستخدمين الجدد إكمال مصادقة تسجيل الدخول الأولى وتحديث كلمات المرور الخاصة بهم، وإلا فستتلقى خطأ
AADSTS50055: The password is expired
عند الحصول على رمز الوصول المميز.عندما يقوم مستخدم جديد بتسجيل الدخول، يتلقى مطالبة الإجراء المطلوب . يمكنهم اختيار طلب لاحقا لتخطي التحقق من الصحة.
حدد «Review + create» لمراجعة اختياراتك. حدد Create لإنشاء المستخدم.
تحديث تكوين OAuth2 لتخويل واجهة مستخدم Swagger
استخدم الخطوات التالية لتحديث تكوين OAuth2 لتخويل واجهة مستخدم Swagger. بعد ذلك، يمكنك تخويل المستخدمين للحصول على رموز الوصول المميزة ToDoWeb
من خلال التطبيق.
افتح مستأجر Microsoft Entra ID في مدخل Microsoft Azure، وانتقل إلى التطبيق المسجل
ToDoWeb
.ضمن Manage، حدد Authentication، وحدد Add a platform، ثم حدد Single-page application.
استخدم التنسيق
<your-app-exposed-application-URL-or-endpoint>/swagger-ui/oauth2-redirect.html
كعنون URL لإعادة توجيه OAuth2 في حقل Redirect URIs ، ثم حدد Configure.
الحصول على الرمز المميز للوصول
استخدم الخطوات التالية لاستخدام أسلوب تدفق رمز التخويل OAuth 2.0 للحصول على رمز وصول باستخدام معرف Microsoft Entra، ثم الوصول إلى واجهات برمجة تطبيقات ToDo
RESTful للتطبيق:
افتح عنوان URL الذي يعرضه التطبيق، ثم حدد تخويل لإعداد مصادقة OAuth2.
في نافذة التخويلات المتوفرة، أدخل معرف
ToDoWeb
العميل للتطبيق في حقل client_id، وحدد جميع النطاقات لحقل النطاقات، وتجاهل حقل client_secret، ثم حدد تخويل لإعادة التوجيه إلى صفحة تسجيل الدخول إلى Microsoft Entra.
بعد إكمال تسجيل الدخول مع المستخدم السابق، يتم إرجاعك إلى نافذة التخويلات المتوفرة .
5.2. الوصول إلى واجهات برمجة تطبيقات RESTful
استخدم الخطوات التالية للوصول إلى واجهات برمجة تطبيقات ToDo
RESTful للتطبيق في واجهة مستخدم Swagger:
حدد API POST /api/simple-todo/lists ثم حدد Try it out. أدخل نص الطلب التالي، ثم حدد Execute لإنشاء قائمة ToDo.
{ "name": "My List" }
بعد اكتمال التنفيذ، سترى نص الاستجابة التالي:
{ "id": "<ID-of-the-ToDo-list>", "name": "My List", "description": null }
حدد API POST /api/simple-todo/lists/{listId}/items ثم حدد Try it out. بالنسبة إلى listId، أدخل معرف قائمة ToDo الذي قمت بإنشائه مسبقا، وأدخل نص الطلب التالي، ثم حدد Execute لإنشاء عنصر ToDo.
{ "name": "My first ToDo item", "listId": "<ID-of-the-ToDo-list>", "state": "todo" }
يقوم هذا الإجراء بإرجاع عنصر ToDo التالي:
{ "id": "<ID-of-the-ToDo-item>", "listId": "<ID-of-the-ToDo-list>", "name": "My first ToDo item", "description": null, "state": "todo", "dueDate": "2023-07-11T13:59:24.9033069+08:00", "completedDate": null }
حدد API GET /api/simple-todo/lists ثم حدد Execute للاستعلام عن قوائم ToDo. يقوم هذا الإجراء بإرجاع قوائم ToDo التالية:
[ { "id": "<ID-of-the-ToDo-list>", "name": "My List", "description": null } ]
حدد واجهة برمجة التطبيقات GET /api/simple-todo/lists/{listId}/items ثم حدد Try it out. بالنسبة إلى listId، أدخل معرف قائمة ToDo الذي أنشأته مسبقا، ثم حدد Execute للاستعلام عن عناصر ToDo. يقوم هذا الإجراء بإرجاع عنصر ToDo التالي:
[ { "id": "<ID-of-the-ToDo-item>", "listId": "<ID-of-the-ToDo-list>", "name": "My first ToDo item", "description": null, "state": "todo", "dueDate": "2023-07-11T13:59:24.903307+08:00", "completedDate": null } ]
حدد واجهة برمجة التطبيقات PUT /api/simple-todo/lists/{listId}/items/{itemId} ثم حدد Try it out. بالنسبة إلى listId، أدخل معرف قائمة ToDo. بالنسبة إلى itemId، أدخل معرف عنصر ToDo، وأدخل نص الطلب التالي، ثم حدد Execute لتحديث عنصر ToDo.
{ "id": "<ID-of-the-ToDo-item>", "listId": "<ID-of-the-ToDo-list>", "name": "My first ToDo item", "description": "Updated description.", "dueDate": "2023-07-11T13:59:24.903307+08:00", "state": "inprogress" }
يقوم هذا الإجراء بإرجاع عنصر ToDo المحدث التالي:
{ "id": "<ID-of-the-ToDo-item>", "listId": "<ID-of-the-ToDo-list>", "name": "My first ToDo item", "description": "Updated description.", "state": "inprogress", "dueDate": "2023-07-11T05:59:24.903307Z", "completedDate": null }
حدد API DELETE /api/simple-todo/lists/{listId}/items/{itemId} ثم حدد Try it out. بالنسبة إلى listId، أدخل معرف قائمة ToDo. بالنسبة إلى itemId، أدخل معرف عنصر ToDo، ثم حدد Execute لحذف عنصر ToDo. يجب أن ترى أن رمز استجابة الخادم هو
204
.
6. حذف الموارد
يمكنك حذف مجموعة موارد Azure، التي تتضمن كافة الموارد الموجودة في مجموعة الموارد.
استخدم الخطوات التالية لحذف مجموعة الموارد بأكملها، بما في ذلك الخدمة التي تم إنشاؤها حديثا:
حدد موقع مجموعة الموارد الخاصة بك في مدخل Microsoft Azure.
في قائمة التنقل، حدد Resource groups. ثم حدد اسم مجموعة الموارد الخاصة بك - على سبيل المثال، myresourcegroup.
في صفحة مجموعة الموارد الخاصة بك، حدد حذف. أدخل اسم مجموعة الموارد في مربع النص لتأكيد الحذف - على سبيل المثال، myresourcegroup. ثم حدد Delete.
استخدم الخطوات التالية لحذف مجموعة الموارد بأكملها، بما في ذلك الخدمة التي تم إنشاؤها حديثا:
حدد موقع مجموعة الموارد الخاصة بك في مدخل Microsoft Azure.
في قائمة التنقل، حدد Resource groups. ثم حدد اسم مجموعة الموارد الخاصة بك - على سبيل المثال، myresourcegroup.
في صفحة مجموعة الموارد الخاصة بك، حدد حذف. أدخل اسم مجموعة الموارد في مربع النص لتأكيد الحذف - على سبيل المثال، myresourcegroup. ثم حدد Delete.
7. الخطوات التالية
لمزيد من المعلومات، راجع المقالات التالية:
- نماذج Azure Spring Apps.
- Spring on Azure
- Spring Cloud Azure