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

می‌توانید بااستفاده از نسخه نمایشی وب ارائه‌شده یا با فراخوانی مستقیم 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 Invoker (roles/cloudfunctions.invoker)، به مجاز کردن دسترسی با IAM مراجعه کنید.

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

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

استفاده از میانای برنامه‌سازی کاربردی

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

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

اصالت‌سنجی

همه درخواست‌های میانای برنامه‌سازی کاربردی باید با یک کد هویتی که هویت تماس‌گیرنده را اثبات می‌کند اصالت‌سنجی شوند. هویت (کاربر یا حساب سرویس) باید اجازه‌های Cloud Functions Invoker را در تابع هدف داشته باشد.

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

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

2. فراخوانی حساب سرویس (در Google Cloud): هنگام فراخوانی میانای برنامه‌سازی کاربردی از منبع Google Cloud (برای مثال، Compute Engine VM، 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 (عدد صحیح): تعداد گزارش‌های دورسنجی که پس‌از آن شبیه‌سازی به‌پایان می‌رسد.

• پاسخ موفقیت (۲۰۰ OK):

  { "id": "sim-a1b2c3d4e5f6" }
  

حذف شبیه‌سازی

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

• نقطه پایانی: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
• سرایندها:
  • Content-Type: application/json

• بدنه درخواست:

  { "id": "sim-a1b2c3d4e5f6" }
  

• پاسخ موفقیت (۲۰۰ 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 (عدد صحیح): تعداد نتایج در هر صفحه. پیش‌فرض ۲۰ است.
  • ‫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"
  

• پاسخ موفقیت (۲۰۰ 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
    

  • پاسخ موفقیت (۲۰۰ OK):

    {
      "count": 0
    }
    

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

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

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

  • پاسخ موفقیت (۲۰۰ OK):

    {
      "max_running_vms": 5
    }