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

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، في صفحة اختيار المشروع، اختَر مشروعًا على السحابة الإلكترونية أو أنشِئ مشروعًا على السحابة الإلكترونية.
2. تأكَّد من تفعيل الفوترة لمشروعك على Cloud. كيفية التحقّق من تفعيل الفوترة في مشروع

بدء 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. انقر على **إضافة مكون > موازنة التحميل على السحابة الإلكترونية على مستوى العالم (الواجهة الأمامية).
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. سيؤدي ذلك إلى فتح التطبيق في "مركز التطبيقات". "مركز التطبيقات" هو مكان مركزي لعرض جميع تطبيقاتك وإدارتها، ما يتيح لك الانتقال من عرض يركّز على الموارد إلى عرض يركّز على التطبيقات. يؤدي إنشاء تطبيق باستخدام ميزة إنشاء التطبيقات بدون كتابة أي رمز برمجي إلى إنشاء تطبيق تلقائيًا في مركز التطبيقات. من المفترض أن تظهر هنا جميع أحمال العمل والخدمات التي يتكوّن منها التطبيق. بدلاً من عرض الموارد في السحابة الإلكترونية كموارد فردية، يمكنك عرضها كجزء من تطبيق واحد، ما يسهّل الإدارة والحوكمة.

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

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

9. تهانينا

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

ما تعلّمته

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

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

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