راهنمای کاربر

شما می‌توانید شبیه‌سازی‌ها را با استفاده از نسخه آزمایشی وب ارائه شده یا با فراخوانی مستقیم REST API اجرا کنید.

ورودی و خروجی

فایل‌های ورودی و خروجی از فضای ذخیره‌سازی ابری (Cloud Storage bucket) موجود در تنظیمات Terraform استفاده می‌کنند.

دایرکتوری ورودی باید حاوی فایل‌های metrics_config.zip و publisher_config.zip باشد. می‌توانید مسیر آن را در صورت نیاز تعریف کنید.

سطل خروجی‌ها شامل یک دایرکتوری simulations است که هر شبیه‌سازی را بر اساس شناسه (ID) آن ذخیره می‌کند. هر دایرکتوری شبیه‌سازی شامل یک پوشه ورودی با فایل‌های ورودی کپی شده و یک پوشه خروجی است. پوشه خروجی شامل گزارش اشکال (bugreport)، فایل logcat و فایل‌های شبیه‌ساز تولید شده است.

از نسخه آزمایشی وب استفاده کنید

این پلتفرم شامل یک برنامه وب مبتنی بر Flutter برای اهداف نمایشی است که به شما امکان مشاهده، ایجاد و مدیریت شبیه‌سازی‌ها را می‌دهد. شما تشویق می‌شوید که رابط کاربری خود را متناسب با نیازهایتان بسازید.

برنامه آزمایشی در App Engine مستقر شده است و از شما می‌خواهد که با یک حساب Google وارد شوید. این حساب با استفاده از یک شناسه کلاینت OAuth 2.0 پیکربندی شده در پروژه Google Cloud شما محافظت می‌شود. حساب وارد شده باید مجوزهای IAM را برای فراخوانی توابع Cloud مستقر شده داشته باشد. برای دستورالعمل‌های مربوط به اعطای مجوزهای لازم به حساب‌های کاربری، مانند نقش فراخوانی‌کننده توابع Cloud ( roles/cloudfunctions.invoker )، به بخش «مجاز کردن دسترسی با IAM» مراجعه کنید.

گردش کار کاربر

1. با استفاده از فرآیند OAuth 2.0، با حساب Google خود وارد شوید.
2. شبیه‌سازی‌ها را در صفحه اصلی مشاهده کنید، که تمام شبیه‌سازی‌ها را با پرس‌وجو از پایگاه داده Firestore که تمام اطلاعات اجرا را در خود جای داده است، فهرست می‌کند.
3. با کلیک بر روی دکمه + action در گوشه پایین سمت راست، به یک فرم برای برنامه‌ریزی یک شبیه‌سازی جدید بروید. شما چندین پارامتر از جمله مسیر ورودی، شناسه ساخت و نوع نمونه را ارائه می‌دهید. برای اطلاعات بیشتر، به ایجاد یک شبیه‌سازی مراجعه کنید.
4. وضعیت مانیتور را در به‌روزرسانی‌های لیست شبیه‌سازی بررسی کنید، که وضعیت شبیه‌سازی جدید را نشان می‌دهد، برای مثال، PENDING ، RUNNING ، COMPLETED .
5. پس از اتمام شبیه‌سازی، گزارش‌ها و مصنوعات تولید شده را مشاهده کنید. فایل‌های ورودی، گزارش‌های خروجی، گزارش‌ها، Logcat و Bugreports در فضای ذخیره‌سازی ابری ذخیره می‌شوند.
6. اختیاری: لغو شبیه‌سازی برنامه‌ریزی‌شده یا در حال اجرا.

استفاده از API

برای اتوماسیون و ادغام با سایر سیستم‌ها، می‌توانید از REST API استفاده کنید.

عبارت CLOUD_FUNCTION_URL که در بخش احراز هویت و در تعاریف نقطه پایانی استفاده می‌شود، به URL پایه تابع ابری که فراخوانی می‌شود اشاره دارد. می‌توانید URLهای تابع را در کنسول Google Cloud در صفحه توابع ابری پیدا کنید؛ URL هر تابع در برگه Trigger از صفحه جزئیات تابع آن نشان داده شده است. همچنین، می‌توانید این URLها را در خروجی‌های Terraform که پس از اجرای یک دستور apply چاپ می‌شوند، پیدا کنید.

احراز هویت

تمام درخواست‌های API باید با یک توکن هویت که هویت فراخواننده را اثبات می‌کند، احراز هویت شوند. هویت (کاربر یا حساب سرویس) باید مجوزهای فراخوانی توابع ابری را روی تابع هدف داشته باشد.

1. فراخوانی کاربر (محلی و رابط خط فرمان): هنگام فراخوانی API از یک دستگاه محلی یا یک محیط غیر Google Cloud، باید از یک توکن هویت صادر شده توسط گوگل که برای یک حساب کاربری دریافت شده است، استفاده کنید.

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

2. فراخوانی حساب سرویس (درون Google Cloud): هنگام فراخوانی API از یک منبع 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")
   

توکن بازیابی شده را به عنوان توکن Bearer token) در سربرگ Authorization header) درخواست‌های خود قرار دهید.

نقاط پایانی

نقاط پایانی کاربرپسندِ پشته شبیه‌سازی تله‌متری ابری به شما امکان می‌دهند شبیه‌سازی‌ها را ایجاد و حذف کنید یا اطلاعات شبیه‌سازی را از پایگاه داده بخوانید.

ایجاد یک شبیه‌سازی

این نقطه پایانی یک درخواست شبیه‌سازی جدید ایجاد می‌کند و آن را برای اجرا زمان‌بندی می‌کند.

• نقطه پایانی: 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 (رشته): برچسب تصویر داکر عامل مورد استفاده، برای مثال، 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 تایید):

  { "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 (رشته): فیلتر بر اساس وضعیت شبیه‌سازی ( 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 تایید):

  • یک شیء 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 تایید):

    {
      "count": 0
    }
    

• دریافت حداکثر تعداد ماشین‌های مجازی همزمان: حداکثر تعداد پیکربندی‌شده‌ی ماشین‌های مجازی در حال اجرا همزمان را برمی‌گرداند.

  • نقطه پایانی:

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

  • پاسخ موفقیت (200 تایید):

    {
      "max_running_vms": 5
    }