تفعيل التطبيقات بسرعة باستخدام "مركز تصميم التطبيقات"

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية نشر تطبيق يتضمّن حزمة كاملة باستخدام مركز تصميم التطبيقات (ADC) من Google Cloud. ستنشئ تطبيق "The Cymbal London Concierge" الذي يتضمّن واجهة مستخدم أمامية Vue 3 وواجهة خلفية FastAPI وخادم MCP يحتوي على بيانات التطبيق.

تتيح لك ميزة "تصميم التطبيق" تحديد بنية تطبيقك بشكل مرئي ونشره كوحدة واحدة، وإدارة التبعيات والروابط تلقائيًا.

الإجراءات التي ستنفذّها

• إعداد "مركز تصميم التطبيقات"
• تجميع مكوّنات التطبيق بشكل مرئي
• نشر بنية التطبيق
• تحقَّق من التطبيق الذي يتم تشغيله.
• تأكَّد من تسجيل التطبيق في "مركز التطبيقات".
• تحقَّق من مقاييس التطبيق وعمليات التتبُّع والسجلات في "مراقبة التطبيق".

المتطلبات

• متصفّح ويب، مثل Chrome
• مشروع Google Cloud تم تفعيل الفوترة فيه

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين من جميع المستويات، بما في ذلك المبتدئين.

المدة المقدَّرة: 45 دقيقة التكلفة المقدَّرة: أقل من 2.00 دولار أمريكي

2. الإعداد

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

إنشاء مشروع على Google Cloud

1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell

Cloud Shell هي بيئة سطر أوامر تعمل في Google Cloud ومحمّلة مسبقًا بالأدوات اللازمة.

1. انقر على تفعيل Cloud Shell في أعلى "وحدة تحكّم Google Cloud".
2. بعد الاتصال بـ Cloud Shell، تحقَّق من مصادقتك باتّباع الخطوات التالية:

   gcloud auth list
   

3. تأكَّد من إعداد مشروعك باتّباع الخطوات التالية:

   gcloud config get project
   

4. إذا لم يتم ضبط مشروعك على النحو المتوقّع، اضبطه باتّباع الخطوات التالية:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

3- إعداد "مركز تصميم التطبيقات"

قبل أن تتمكّن من تجميع تطبيقك، عليك إعداد مساحة العمل في "مركز مطوّري تطبيقات Android".

1. في Google Cloud Console، ابحث عن مركز تصميم التطبيقات وانتقِل إليه.
2. إذا كانت هذه هي المرة الأولى التي تستخدم فيها "إعلانات Google للعملاء" في هذا المشروع، ستظهر لك شاشة إعداد.
3. انقر على الانتقال إلى الإعداد.

4. سيُطلب منك تفعيل واجهات برمجة التطبيقات المطلوبة إذا لم يسبق لك تفعيلها. انقر على تفعيل للمتابعة.

4. استكشاف ميزات "إعلانات التطبيقات أثناء المشاهدة"

في هذه المهمة، ستتعرّف على المكوّنات الأساسية في ADC، وهي المساحات والفهارس والنماذج.

مساحات ADC

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

لعرض مساحاتك من خلال نافذة الأوامر، اتّبِع الخطوات التالية:

1. انقر على فتح المحرّر في شريط أدوات Cloud Shell أو استخدِم الوحدة الطرفية.
2. نفِّذ الأمر التالي:

gcloud alpha design-center spaces list \
--project="your PROJECT ID" \
--location=us-central1

من المفترَض أن تظهر لك نتيجة مشابهة لما يلي تشير إلى أنّ المساحة التلقائية متوفّرة في المنطقة.

createTime: '20XXXX-XX-XXT09:19:29.456016967Z'
displayName: default-space
enableGcpSharedTemplates: true
name: projects/your-project-id/locations/us-central1/spaces/default-space

5- تجميع النموذج

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

1. إنشاء تصميم جديد

1. في وحدة تحكّم ADC، انقر على النماذج > إنشاء نموذج.
2. أضِف اسمًا للنموذج simple-3-tier-agentic-app، لأنّ هذا النموذج سيُستخدَم لنشر تطبيق Cymbal London Concierge والتطبيقات الأخرى المشابهة.

2. إضافة خادم Data MCP

يتعامل هذا المكوّن مع تفاعلات قاعدة البيانات والبحث المتّجه.

1. انقر على إضافة مكون (Add Component) > Cloud Run (الخدمة). إذا نقرت على هذا المكوّن، سيظهر لك معرّف المكوّن في أعلى يسار الصفحة. سيكون بالتنسيق cloud-run-1. يمكننا تغييرها إلى data-mcp-server من خلال تعديلها في طريقة عرض الرمز (سيتم توضيح ذلك لاحقًا)، ولكن لنتركها كما هي.
2. أدخِل اسم الخدمة: data-mcp-server.
3. ضمن عرض الإعدادات المتقدّمة، اضبط الأعضاء على: allUsers. (ملاحظة: في بيئة الإنتاج، من المحتمل أن يتم تقييد ذلك، ولكننا نستخدمه هنا لتبسيط الدروس التطبيقية.)
4. ضمن عرض الإعدادات المتقدّمة، اضبط الوصول إلى شبكة VPC، واضبط الخروج على: PRIVATE_RANGES_ONLY.
5. يمكنك اختياريًا إزالة العلامة من المربّع تفعيل Prometheus Sidecar ضمن عرض الإعدادات المتقدّمة.
6. انقر على حفظ.

3- إضافة Agent Backend

هذا هو تطبيق FastAPI الذي ينسّق سلوك الذكاء الاصطناعي الوكيل.

1. انقر على إضافة مكون (Add Component) > Cloud Run (الخدمة).
2. أطلِق عليها الاسم agent-backend.
3. ضمن عرض الحقول المتقدّمة، ضَع علامة في المربّع بجانب إنشاء حساب خدمة وأضِف الأدوار التالية ضمن أدوار حساب الخدمة في المشروع واحدًا تلو الآخر:
   • roles/monitoring.metricWriter
   • roles/logging.logWriter
   • roles/cloudtrace.agent
   • roles/telemetry.writer
   • roles/serviceusage.serviceUsageConsumer. ستسمح هذه الأدوار للوكيل باستخدام Cloud Monitoring وCloud Logging وCloud Trace. إعدادات التوافق: يفرض فريق المنصة مبدأ الحدّ الأدنى من الامتيازات من خلال إدراج الأدوار المطلوبة بشكلٍ صريح.
   
4. ضمن عرض الإعدادات المتقدّمة، اضبط الأعضاء على: allUsers.
5. ضمن عرض الإعدادات المتقدّمة، اضبط الوصول إلى شبكة VPC، واضبط الخروج على: PRIVATE_RANGES_ONLY.
6. يمكنك اختياريًا إزالة العلامة من المربّع تفعيل Prometheus Sidecar ضمن عرض الإعدادات المتقدّمة.
7. اربط بين agent-backend وdata-mcp-server عن طريق سحب خط ربط من agent-backend إلى data-mcp-server.
8. انقر على حفظ.

4. إضافة الواجهة الأمامية

واجهة المستخدم الأمامية

1. انقر على إضافة مكون (Add Component) > Cloud Run (الخدمة).
2. أدخِل اسم الخدمة: frontend.
3. ضمن عرض الإعدادات المتقدّمة، أزِل العلامة من المربّع بجانب إنشاء حساب خدمة.
4. ضمن عرض الإعدادات المتقدّمة، اضبط Ingress على: INGRESS_TRAFFIC_INTERNAL_LOADBALANCER. إعدادات التوافق: يتم حظر الوصول المباشر إلى حاوية الواجهة الأمامية، ما يفرض توجيه الزيارات من خلال موازن التحميل.
5. ضمن عرض الإعدادات المتقدّمة، اضبط الأعضاء على: allUsers.
6. يمكنك اختياريًا إزالة العلامة من المربّع تفعيل Prometheus Sidecar ضمن عرض الإعدادات المتقدّمة.
7. انقر على حفظ.
8. اربط بين frontend وagent-backend عن طريق سحب خط ربط من frontend إلى agent-backend.

5- إضافة مكوّن Vertex AI

1. انقر على إضافة مكوّن > Vertex AI.
2. أطلِق عليها الاسم vertex-ai.
3. اربطه بالجهاز agent-backend والجهاز data-mcp-server عن طريق سحب وصلتَين من vertex-ai إلى agent-backend وdata-mcp-server على التوالي. سيتم تلقائيًا تعيين الأدوار aiplatform.user إلى حسابات الخدمة الخاصة بـ agent-backend وdata-mcp-server لأنّها مرتبطة بمكوّن Vertex AI.

6. إضافة موازن الحمل العام

تعرض خدمة "موازنة التحميل" الواجهة الأمامية على شبكة الإنترنت العامة. في ADC، يتم تقسيم ذلك إلى مكوّن خلفي ومكوّن أمامي.

أ. إضافة الخلفية الخاصة بموازن الحمل

1. انقر على **إضافة مكون > Global Cloud Load Balancing (الخادم الخلفي).
2. أطلِق عليها الاسم galb-backend.
3. انقر على إضافة اتصال واربطه بـ frontend.

ب. إضافة الواجهة الأمامية لجهاز موازنة الحمل

1. انقر على **إضافة مكون > Cloud Load Balancing (الواجهة الأمامية).
2. أطلِق عليها الاسم galb-frontend.
3. انقر على إضافة اتصال واربطه بـ galb-backend.
4. اربط بين galb-frontend وgalb-backend عن طريق سحب خط ربط من galb-frontend إلى galb-backend.

مشاركة النموذج في الكتالوج

يتيح لك الكتالوج مشاركة نماذج التطبيقات على مستوى مساحات مختلفة، ما يتيح إدارة بنية التطبيق. يعمل الكتالوج كمستودع مركزي للنماذج التي أنشأها فريق المنصة ووافق عليها لمشاركتها. تجنُّب تكرار الجهد في المشاريع الشائعة وتبسيط أوقات بدء التشغيل من خلال مشاركة الفهارس بين المساحات

الآن، أضِف النموذج إلى الكتالوج:

1. انقر على علامة التبويب الفهارس.
2. انقر على إضافة نماذج واختَر النموذج simple-3-tier-agentic-app.
3. انقر على إضافة إلى الكتالوج.

يمكنك العثور على النماذج في ثلاثة مواقع: نماذج Google (أنماط محدّدة مسبقًا) والنماذج المشترَكة (المشارَكة على مستوى مؤسستك) والنماذج (مخططات مخصّصة في مساحتك).

6. نشر التطبيق

حان الوقت الآن لتولّي دور مطوّر تطبيقات يريد استخدام هذا النموذج لنشر تطبيق cymbal-london-concierge.

1. في وحدة تحكّم ADC، أعِد فتح النموذج في علامة التبويب النماذج، وانقر على الزر إعداد التطبيق.
2. انقر على إنشاء تطبيق جديد.
3. ضبط التطبيق:
   • اسم التطبيق: cymbal-london-concierge
   • مشروع النشر: رقم تعريف مشروعك
   • المنطقة: us-central1
   • سمات الإدخال>البيئة: Development
   • سمات الإدخال>الأهمية: Low
4. انقر على إنشاء تطبيق.بالنسبة إلى عملية نشر في بيئة الإنتاج، عليك اختيار "بيئة الإنتاج" في حقل "البيئة" و"عالية" في حقل "الأهمية". هذه هي العلامات التي ستساعد مهندسي موثوقية الموقع وفريق العمليات في ترتيب وتحديد أولويات العمل على أي مشاكل تحدث.
5. من المفترض أن يؤدي ذلك إلى فتح صفحة تفاصيل النشر التي تتضمّن نموذج التطبيق. بما أنّ هذا مجرّد نموذج، ما زلنا بحاجة إلى إضافة إعدادات خاصة بتطبيقنا.
6. لنضبط الواجهة الأمامية. انقر على مكوّن واجهة المستخدم.
   1. انقر على الحاويات > تعديل الحاوية.
   2. علينا استبدال صورة الحاوية العامة بالصورة التي نريد استخدامها لتطبيقنا.
   3. اضبط صورة الحاوية على: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/frontend:codelab-c2c6-v1
   4. اضبط المنفذ http1 على 80.
   5. اضبط متغيّرات البيئة التالية:
      • ‫API_BASE_URL: module.cloud-run-2.service_uri (تأكَّد من أنّ cloud-run-2 هو اسم الخلفية الخاصة بمكوّن الوكيل، وإذا لم يكن كذلك، استبدِله بالاسم الفعلي للمكوّن)
   6. انقر على حفظ.
7. لنبدأ بضبط إعدادات الواجهة الخلفية للوكيل. انقر على مكوّن agent-backend.
   1. انقر على الحاويات > تعديل الحاوية.
   2. علينا استبدال صورة الحاوية العامة بالصورة التي نريد استخدامها لتطبيقنا.
   3. اضبط صورة الحاوية على: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/agent:codelab-c2c6-v1
   4. اضبط متغيرات البيئة التالية:
   5. GOOGLE_CLOUD_PROJECT:
   6. GOOGLE_CLOUD_LOCATION: us-central1
   7. DATA_BACKEND_URL: module.cloud-run-1.service_uri (تأكَّد من أنّ cloud-run-1 هو اسم مكوّن خادم mcp للبيانات، وإذا لم يكن كذلك، استبدِله بالاسم الفعلي للمكوّن)
   8. اضبط المنفذ http1 على 8000.
   9. انقر على حفظ.
8. لنبدأ الآن ضبط خادم MCP للبيانات. انقر على مكوّن data-mcp-server.
   1. انقر على الحاويات > تعديل الحاوية.
   2. علينا استبدال صورة الحاوية العامة بالصورة التي نريد استخدامها لتطبيقنا.
   3. اضبط صورة الحاوية على: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/data_mcp:codelab-c2c6-v1
   4. اضبط متغيرات البيئة التالية:
   5. GOOGLE_CLOUD_PROJECT:
   6. GOOGLE_CLOUD_LOCATION: us-central1
   7. DB_TYPE: sqlite
   8. EMBEDDING_MODEL: text-embedding-005
   9. اضبط المنفذ http1 على 8002.
   10. انقر على حفظ.
   في سيناريو إنتاج حقيقي، عليك أيضًا ضبط قاعدة بيانات مثل CloudSQL أو AlloyDB وتقديم سلسلة ربط قاعدة البيانات لخادم mcp للبيانات. ولكن في هذا المختبر، سنستخدم قاعدة بيانات داخل الذاكرة. يمكنك أيضًا جعل خادم mcp وقاعدة البيانات خاصَّين ولا يمكن الوصول إليهما إلا من الخلفية البرمجية للوكيل أو من داخل الشبكة.
9. انقر على الزر الرمز في أعلى الصفحة لعرض رمز Terraform الخاص بالتطبيق. يمكنك أيضًا تنزيل رمز Terraform للتطبيق من خلال النقر على الزر الحصول على الرمز لتخزينه في قاعدة الرموز.
10. انقر على الزر نشر (Deploy) في أعلى يسار الصفحة لنشر التطبيق.
11. ستطلب منك صفحة النشر إنشاء حساب خدمة لخطوات النشر أو اختيار حساب حالي. انقر على إنشاء حساب خدمة (سيتم ملء الاسم تلقائيًا)، ثم انقر على متابعة. سيستغرق إنشاء حساب خدمة جديد بضع ثوانٍ.

12. بعد إنشاء حساب الخدمة، سيتم تحديث الصفحة وسيظهر لك خيار "اختيار حساب الخدمة" (Select Service Account) مع علامة اختيار بجانبه.

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

![Deployment Logs](./img/10b_logs.png)

15. يمكنك الاطّلاع على سجلّات الإنشاء على السحابة الإلكترونية لمعرفة حالة النشر أو ما إذا كانت هناك أي أخطاء قد تحدث أثناء نشر التطبيق. يمكنك أيضًا الانتقال مباشرةً إلى سجلّات Cloud Build من خلال البحث عن Cloud Build في وحدة تحكّم Google Cloud والنقر على السجلّ. سيستغرق نشر التطبيق من 5 إلى 8 دقائق تقريبًا.

![Cloud Build](./img/10c_cloudbuild.png)

16. بعد اكتمال عملية النشر، ستظهر علامة اختيار خضراء بجانب حقل حالة النشر.

![Deployment Complete](./img/11_deployed.png)

7. التحقّق من التطبيق

لنختبر ما إذا كان الوكيل نشطًا. في قسم عمليات الإخراج ضمن صفحة تفاصيل النشر، سيظهر لك عنوان URL الخاص بمكوّن الواجهة الأمامية. انسخ عنوان URL هذا والصقه في المتصفّح. تأكَّد من استخدام http وليس https. يجب أيضًا قبول أي تحذيرات قد تظهر لك في المتصفّح لأنّ الواجهة الأمامية تستخدم http.

تحدّث مع التطبيق واطلب منه إنشاء برنامج رحلة إلى لندن.

8. مركز التطبيقات ومراقبة التطبيقات

1. في "وحدة تحكّم ADC"، انقر على الزر عرض التطبيق في "مركز التطبيقات" في أعلى يسار الصفحة.

2. سيؤدي ذلك إلى فتح التطبيق في "مركز التطبيقات". "مركز التطبيقات" هو مكان مركزي لعرض جميع تطبيقاتك وإدارتها، ما يتيح لك الانتقال من عرض يركّز على الموارد إلى عرض يركّز على التطبيقات. يؤدي إنشاء تطبيق باستخدام "ميزة إنشاء التطبيقات بدون كتابة أي رمز برمجي" إلى إنشاء تطبيق تلقائيًا في App Hub. من المفترض أن تظهر هنا جميع أحمال العمل والخدمات التي يتألف منها التطبيق. بدلاً من عرض الموارد في السحابة كموارد فردية، يمكنك عرضها كجزء من تطبيق واحد، ما يسهّل الإدارة والحوكمة.

3. انقر على الزر عرض في Observability. من المفترض أن يؤدي ذلك إلى فتح التطبيق في وحدة تحكّم Observability.
4. افتح عرض لوحة البيانات. تمنحك لوحة البيانات نظرة عامة على أداء التطبيق وحالته من خلال توفير مقاييس مثل الإشارات الذهبية الأربع: معدّل الطلبات ومعدّل الأخطاء ووقت الاستجابة والاستخدام. وتُعدّ المراقبة التي تركّز على التطبيقات ضرورية للحفاظ على الموثوقية. يمكنك أيضًا عرض السجلات وعمليات التتبُّع للتطبيق، ما يتيح لك ربط الإشارات وتحديد المشاكل. ويُعدّ ذلك مهمًا بشكل خاص في تطبيق معقّد مثل هذا، حيث يمكن أن تؤدي الاستجابات البطيئة من Vertex AI أو خادم Data MCP إلى تدهور تجربة المستخدم.

5. الاستكشاف الموجّه: اطرح على الوكيل سؤالاً محدّدًا في التطبيق (مثلاً، "ما هي أفضل الأماكن التي يمكن زيارتها في لندن؟"). بعد ذلك، ارجِع إلى وحدة تحكّم Observability واطّلِع على قائمة عمليات التتبُّع. ابحث عن التتبُّع الذي يتوافق مع طلبك. انقر على هذا القسم للاطّلاع على العرض التفصيلي للرسم البياني المتتالي. لاحظ كيف يمكنك الاطّلاع على الوقت المستغرَق في الواجهة الأمامية وخلفية الوكيل والمكالمات إلى Vertex AI. يتيح لك ذلك تحديد المكان الذي يحدث فيه وقت الاستجابة فيه بالضبط.

9- تهانينا

تهانينا! لقد نشرت بنية تطبيق من 3 طبقات باستخدام ADC.

ما تعلّمته

• كيفية تجميع بنية سحابية بشكل مرئي باستخدام ADC
• كيفية إعداد ADC وتفعيل واجهات برمجة التطبيقات من خلال واجهة المستخدم
• كيفية نشر التطبيقات باستخدام ADC
• كيفية استخدام مركز التطبيقات للحصول على عرض مركّز على التطبيقات لمواردك
• كيفية رصد حالة التطبيق باستخدام لوحة بيانات إمكانية تتبّع البيانات

المستندات المرجعية

• مستندات ADC
• مستندات "مركز التطبيقات"
• مراقبة التطبيقات