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

يمكنك إجراء عمليات محاكاة باستخدام العرض التوضيحي على الويب المتوفّر أو من خلال طلب 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).

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

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

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

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

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

المصادقة

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

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

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

2. استدعاء حساب الخدمة (داخل Google Cloud): عند استدعاء واجهة برمجة التطبيقات من أحد موارد Google Cloud (على سبيل المثال، جهاز افتراضي على Compute Engine أو دالة Cloud أخرى أو مجموعة 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

  • ‫file_path (string): المسار داخل حزمة GCS إلى المجلد الذي يحتوي على metrics_config.zip وpublisher_config.zip.

  • ‫instance_type (string): نوع الجهاز Compute Engine. يجب أن يتيح هذا النوع المحاكاة الافتراضية المتداخلة، مثل السلسلة n1 أو n2 أو t2d. لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المحاكاة الافتراضية المتداخلة.

  • ‫owner (string): عنوان البريد الإلكتروني للمستخدم الذي يبدأ المحاكاة.

  • ‫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 لاسترداد السجلّ والحالة وإعدادات النظام.

محاكاة القوائم

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

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

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

  • status (string): فلترة حسب حالة المحاكاة (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 (string): رمز مميّز لجلب الصفحة التالية من النتائج.

• مثال على الطلب:

  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"
  }
  

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

تعرض هذه الطريقة التفاصيل الكاملة لمحاكاة معيّنة من خلال معرّفها.

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

  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
  }
  

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

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

• الحصول على عدد عمليات المحاكاة الجارية: تعرض هذه السمة عدد عمليات المحاكاة الجارية.

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

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

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

    {
      "count": 0
    }
    

• Get max concurrent VMs: تعرض هذه السمة الحد الأقصى لعدد الأجهزة الافتراضية المتزامنة التي تم ضبطها.

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

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

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

    {
      "max_running_vms": 5
    }