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

شما می‌توانید شبیه‌سازی‌ها را با استفاده از نسخه آزمایشی وب ارائه شده یا با فراخوانی مستقیم 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 ) ، به بخش مدیریت دسترسی به توابع Cloud مراجعه کنید.

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

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

کاربرد API

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

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

احراز هویت

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

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

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

  • ۲. فراخوانی حساب سرویس (درون 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 (رشته): برچسب تصویر داکر عامل مورد استفاده (مثلاً "آخرین"). مهم : این باید با برچسب تعریف شده در نقشه تصویر مجاز زیرساخت (مثلاً "آخرین"، "پایدار") مطابقت داشته باشد. اگر نقشه 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 تایید) :

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