دليل المستخدم

يمكنك إجراء عمليات المحاكاة باستخدام "العرض التوضيحي على الويب" المقدَّم أو من خلال استدعاء REST API مباشرةً.

الإدخال والإخراج

تستخدِم ملفات الإدخال والإخراج حزمة Cloud Storage من إعداد Terraform.

يجب أن يحتوي دليل الإدخال على الملفَين metrics_config.zip وpublisher_config.zip. يمكنك تحديد مساره حسب الحاجة.

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

استخدام "العرض التوضيحي على الويب"

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

يتم نشر التطبيق التجريبي على App Engine ويطلب من المستخدمين تسجيل الدخول باستخدام حساب Google. يتم حماية التطبيق باستخدام معرّف عميل OAuth 2.0 تم إعداده في مشروعك على Google Cloud. يجب أن يكون للحساب الذي تم تسجيل الدخول به أذونات IAM لاستدعاء وظائف Cloud Functions التي تم نشرها. للحصول على تعليمات حول منح الأذونات اللازمة لحسابات المستخدمين، مثل دور مستدعي وظائف Cloud Functions ‏ (roles/cloudfunctions.invoker)، يُرجى الاطّلاع على مقالة إدارة إمكانية الوصول إلى Cloud Functions.

سير عمل المستخدم

1. تسجيل الدخول: يمكنك تسجيل الدخول باستخدام حساب Google، الذي تتم المصادقة عليه باستخدام عملية OAuth 2.0.
2. عرض عمليات المحاكاة: تعرض الصفحة الرئيسية جميع عمليات المحاكاة السابقة والحالية من خلال طلب البحث في قاعدة بيانات Firestore التي تحتوي على جميع معلومات التنفيذ.
3. إنشاء عملية محاكاة: يمكنك الانتقال إلى نموذج لجدولة عملية محاكاة جديدة من خلال النقر على زر الإجراء + في أسفل يمين الشاشة. عليك تقديم عدة مَعلمات، بما في ذلك مسار الإدخال ورقم تعريف الإصدار ونوع المثيل. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء عملية محاكاة.
4. مراقبة الحالة: يتم تعديل قائمة عمليات المحاكاة لعرض حالة عملية المحاكاة الجديدة (PENDING أو RUNNING أو COMPLETED وما إلى ذلك).
5. عرض النتائج: بعد اكتمال عملية المحاكاة، يمكنك عرض التقارير والبيانات التي تم إنشاؤها. يتم تخزين ملفات الإدخال وتقارير الإخراج والسجلّات وLogcat وتقارير الأخطاء في Cloud Storage.
6. حذف عملية محاكاة: يمكنك إلغاء عملية محاكاة مجدولة أو قيد التشغيل.

---

استخدام واجهة برمجة التطبيقات

لأغراض التشغيل الآلي والتكامل مع الأنظمة الأخرى، يمكنك استخدام REST API.

يشير العنصر النائب CLOUD_FUNCTION_URL المستخدَم في قسم "المصادقة" وفي تعريفات نقاط النهاية إلى الـ عنوان URL الأساسي لوظيفة Cloud Function التي يتم استدعاؤها. يمكنك العثور على عناوين URL للوظائف في Google Cloud Console في صفحة Cloud Functions، ويظهر عنوان URL لكل وظيفة في علامة التبويب المشغِّل في صفحة تفاصيل الوظيفة. بدلاً من ذلك، يمكنك العثور على عناوين URL هذه في مخرجات Terraform التي تتم طباعتها بعد تشغيل أمر apply.

المصادقة

يجب المصادقة على جميع طلبات واجهة برمجة التطبيقات باستخدام رمز تعريف يثبت هوية المتصل. يجب أن يكون للهوية (المستخدم أو حساب الخدمة) أذونات مستدعي وظائف Cloud Functions على الوظيفة المستهدَفة.

• 1. استدعاء المستخدم (محليًا ومن سطر الأوامر) عند استدعاء واجهة برمجة التطبيقات من جهاز محلي أو بيئة غير Google Cloud، يجب استخدام رمز تعريف صادر عن Google تم الحصول عليه لحساب مستخدم.

  TOKEN=$(gcloud auth print-identity-token)
  

• 2. استدعاء حساب الخدمة (ضمن Google Cloud) عند استدعاء واجهة برمجة التطبيقات من أحد موارد Google Cloud (مثل جهاز افتراضي على Compute Engine أو وظيفة Cloud Function أخرى أو مجموعة Kubernetes)، يجب استخدام هوية حساب الخدمة المرفق بالمرجع. يجب جلب الرمز المميز من خادم البيانات الوصفية للمرجع.

  TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")
  

أدرِج الرمز المميز الذي تم استرداده في عنوان Authorization لطلباتك كرمز Bearer مميز.

نقاط النهاية

تتيح لك نقاط نهاية واجهة المستخدم في حزمة Cloud Telemetry Simulation إنشاء عمليات محاكاة وحذفها أو قراءة معلومات المحاكاة من قاعدة البيانات.

إنشاء عملية محاكاة

تنشئ نقطة النهاية هذه طلب محاكاة جديدًا وتجدوله للتنفيذ.

• نقطة النهاية: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request

• نص الطلب:

  {
    "build_id": "latest",
    "file_path": "inputs/my-test-case/",
    "instance_type": "n1-standard-8",
    "owner": "user@example.com",
    "max_simulation_time": 300,
    "max_report_count": 5
  }
  

  • build_id (سلسلة): علامة صورة Docker الخاصة بالوكيل التي سيتم استخدامها (مثل "latest"). ملاحظة مهمة: يجب أن تتطابق هذه العلامة مع علامة محدّدة في خريطة الصور المسموح بها للبنية الأساسية (مثل "latest" أو "stable"). يرفض النظام العلامات غير المعروفة إذا تم تحديد خريطة SHA256 في Terraform.
  • file_path (سلسلة): المسار ضمن حزمة GCS إلى المجلد الذي يحتوي على metrics_config.zip وpublisher_config.zip.
  • instance_type (سلسلة): نوع جهاز Compute Engine. يجب أن يتيح هذا النوع المحاكاة الافتراضية المتداخلة، مثل سلسلة n1 أو n2 أو t2d. لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المحاكاة الافتراضية المتداخلة.
  • owner (سلسلة): البريد الإلكتروني للمستخدم الذي بدأ عملية المحاكاة.
  • max_simulation_time (عدد صحيح): الحد الأقصى للوقت بالثواني الذي تستغرقه عملية المحاكاة.
  • max_report_count (عدد صحيح): عدد تقارير القياس عن بُعد التي يتم بعدها إنهاء عملية المحاكاة.

• الردّ الناجح (200 OK):

  { "id": "sim-a1b2c3d4e5f6" }
  

حذف عملية محاكاة

تؤدي نقطة النهاية هذه إلى إلغاء عملية محاكاة معلّقة أو قيد التشغيل وحذف الموارد المرتبطة بها.

• نقطة النهاية: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
• العناوين:
  • Content-Type: application/json

• نص الطلب:

  { "id": "sim-a1b2c3d4e5f6" }
  

• الردّ الناجح (200 OK): عنصر JSON فارغ {}.

قراءة بيانات المحاكاة

لقراءة بيانات المحاكاة، يمكنك التفاعل مع وظيفة simulation-reader. تستخدِم نقاط النهاية هذه طريقة GET لاسترداد السجلّ والحالة وإعدادات النظام.

1. إدراج عمليات المحاكاة

يستردّ هذا الإجراء قائمة مقسَّمة على صفحات بعمليات المحاكاة مع إمكانية الفلترة والترتيب.

• نقطة النهاية: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

• مَعلمات طلب البحث (كلها اختيارية):

  • status (سلسلة): الفلترة حسب حالة المحاكاة (running أو Simulation request received أو cancelled أو completed).
  • owner (سلسلة): الفلترة حسب البريد الإلكتروني للمالك.
  • sort_by (سلسلة): الحقل الذي سيتم الترتيب حسبه (received_at أو status_updated_at أو started_at). يكون الإعداد التلقائي received_at.
  • sort_order (سلسلة): اتجاه الترتيب، asc أو desc. يكون الإعداد التلقائي desc.
  • page_size (عدد صحيح): عدد النتائج في كل صفحة. يكون الإعداد التلقائي 20.
  • page_token (سلسلة): رمز مميز لجلب الصفحة التالية من النتائج.

• نموذج طلب:

  curl -H "Authorization: Bearer $TOKEN"
  "https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"
  

• الردّ الناجح (200 OK):

  • يعرض هذا الإجراء عنصر JSON يحتوي على مصفوفة من عمليات المحاكاة وnext_page_token اختياري.

  {
    "simulations": [
      {
        "id": "1234-abcd",
        "owner": "some@email.com",
        "status": "completed",
        "status_updated_at": "2025-12-05T14:50:00.952Z",
        "received_at": "2025-12-05T14:46:43.106Z",
        "started_at": "2025-12-05T14:47:05.848Z",
        "ended_at": "0001-01-01T00:00:00Z",
        "instance_id": "sim-1234-abcd",
        "ip": "10.156.15.230",
        "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
        "instance_type": "n1-standard-8",
        "file_path": "gs://your-project-simulation_files/path/",
        "max_simulation_time": 60,
        "max_report_count": 1
      },
      {
        "id": "5678-efgh",
        "owner": "some@email.com",
        "status": "completed",
        "status_updated_at": "2025-11-07T14:49:54.25Z",
        "received_at": "2025-11-07T14:46:54.959Z",
        "started_at": "2025-11-07T14:47:13.714Z",
        "ended_at": "0001-01-01T00:00:00Z",
        "instance_id": "sim-5678-efgh",
        "ip": "10.156.15.221",
        "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
        "instance_type": "n1-standard-8",
        "file_path": "gs://your-project-simulation_files/path/",
        "max_simulation_time": 60,
        "max_report_count": 1
      }
    ],
    "next_page_token": "M7bydGsAptLncj8SOCb1"
  }
  

2. الحصول على عملية محاكاة محدّدة

يستردّ هذا الإجراء التفاصيل الكاملة لعملية محاكاة محدّدة حسب رقم تعريفها.

• نقطة النهاية:

  GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]
  

• الردّ الناجح (200 OK): يعرض هذا الإجراء عنصر JSON يحتوي على تفاصيل عملية المحاكاة المطلوبة.

  {
    "id": "1234-abcd",
    "owner": "some@email.com",
    "status": "completed",
    "status_updated_at": "2025-12-05T14:50:00.952Z",
    "received_at": "2025-12-05T14:46:43.106Z",
    "started_at": "2025-12-05T14:47:05.848Z",
    "ended_at": "0001-01-01T00:00:00Z",
    "instance_id": "sim-1234-abcd",
    "ip": "10.156.15.230",
    "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
    "instance_type": "n1-standard-8",
    "file_path": "gs://your-project-simulation_files/path/",
    "max_simulation_time": 60,
    "max_report_count": 1
  }
  

3. الحصول على مقاييس النظام وإعداداته

توفّر نقاط النهاية هذه إحصاءات حول الحمل والإعدادات الحالية للبنية الأساسية للمحاكاة.

• الحصول على عدد عمليات المحاكاة قيد التشغيل: يعرض هذا الإجراء عدد عمليات المحاكاة قيد التشغيل.

  • نقطة النهاية:

    GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count
    

  • الردّ الناجح (200 OK):

    {
      "count": 0
    }
    

• الحصول على الحد الأقصى لعدد الأجهزة الافتراضية المتزامنة: يعرض هذا الإجراء الحد الأقصى لعدد الأجهزة الافتراضية المتزامنة قيد التشغيل الذي تم ضبطه.

  • نقطة النهاية:

    GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms
    

  • الردّ الناجح (200 OK):

    {
      "max_running_vms": 5
    }