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

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

الإدخال والناتج

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

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

يحتوي المستودع المخصّص للمخرجات على دليل simulations، والذي يخزّن كل محاكاة حسب معرّفها. يحتوي كل دليل محاكاة على مجلد inputs يتضمّن ملفات الإدخال المنسوخة ومجلد outputs. يحتوي المجلد outputs على تقرير الخطأ وملف 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 وتقارير الأخطاء في Cloud Storage.
6. اختياري: إلغاء محاكاة مجدوَلة أو جارية

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

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

يشير العنصر النائب CLOUD_FUNCTION_URL المستخدَم في قسم "المصادقة" وفي تعريفات نقاط النهاية إلى الجزء الأساسي من عنوان URL الخاص بدالة Cloud التي يتم استدعاؤها. يمكنك العثور على عناوين 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 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-requests

• نص الطلب:

  {
    "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 (سلسلة): المسار داخل حزمة 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): رسالة نصية عادية (Request accepted and is being processed).

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

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

عرض قائمة المحاكاة

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

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

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

  • ‫status (سلسلة): الفلترة حسب حالة المحاكاة (running أو Simulation request received أو cancelled أو completed أو failed).
  • ‫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"
  }
  

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

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

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

  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 https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms
    

  • استجابة ناجحة (200 OK):

    {
      "max_running_vms": 5
    }