מדריך למשתמש

אפשר להריץ סימולציות באמצעות הדמו באינטרנט שמופיע כאן או על ידי קריאה ישירה ל-API בארכיטקטורת REST.

קלט ופלט

קבצי הקלט והפלט משתמשים בקטגוריה של 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 מוסבר איך להעניק את ההרשאות הנדרשות לחשבונות משתמשים, כמו התפקיד Cloud Functions Invoker ‏ (roles/cloudfunctions.invoker).

תהליך עבודת המשתמש

1. כניסה לחשבון: אתם נכנסים לחשבון Google שלכם, שעובר אימות באמצעות תהליך OAuth 2.0.
2. צפייה בסימולציות: בדף הראשי מופיעות כל הסימולציות הקודמות והנוכחיות. כדי להציג אותן, המערכת שולחת שאילתה למסד הנתונים של Firestore, שבו מאוחסן כל מידע ההפעלה.
3. יצירת סימולציה: כדי לתזמן סימולציה חדשה, עוברים לטופס ולוחצים על לחצן הפעולה + בפינה השמאלית התחתונה. צריך לספק כמה פרמטרים, כולל נתיב הקלט, מזהה ה-Build וסוג המופע. מידע נוסף זמין במאמר בנושא יצירת סימולציה.
4. מעקב אחר הסטטוס: רשימת הסימולציות מתעדכנת כדי להציג את הסטטוס של הסימולציה החדשה (PENDING, RUNNING, COMPLETED וכו').
5. צפייה בתוצאות: אחרי שהסימולציה מסתיימת, אפשר לראות את הדוחות והארטיפקטים שנוצרו. קבצי הקלט, דוחות הפלט, היומנים, Logcat ודוחות הבאגים מאוחסנים ב-Cloud Storage.
6. מחיקת סימולציה: אפשר לבטל סימולציה מתוזמנת או סימולציה שפועלת.

---

שימוש ב-API

כדי לבצע אוטומציה ולשלב עם מערכות אחרות, אפשר להשתמש ב-REST API.

הplaceholder‏ CLOUD_FUNCTION_URL שמשמש בקטע Authentication (אימות) ובהגדרות של נקודות קצה מתייחס לכתובת ה-URL הבסיסית של פונקציית Cloud Functions שמופעלת. אפשר למצוא כתובות URL של פונקציות במסוף Google Cloud בדף Cloud Functions. כתובת ה-URL של כל פונקציה מוצגת בכרטיסייה Trigger בדף Function details. אפשרות אחרת היא למצוא את כתובות ה-URL האלה בפלט של Terraform שמוצג אחרי שמריצים פקודת apply.

אימות

כל הבקשות ל-API צריכות להיות מאומתות באמצעות טוקן זהות שמוכיח את הזהות של מי ששולח את הבקשה. לזהות (משתמש או חשבון שירות) צריכות להיות הרשאות להפעלת Cloud Functions בפונקציית היעד.

• 1. הפעלה על ידי משתמש (מקומי ו-CLI) כשמפעילים את ה-API ממחשב מקומי או מסביבה שאינה Google Cloud, צריך להשתמש באסימון זהות שהונפק על ידי Google ומתקבל עבור חשבון משתמש.

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

• 2. הפעלת חשבון שירות (בתוך Google Cloud) כשמפעילים את ה-API ממשאב של 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-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). חשוב: הערך הזה צריך להיות זהה לתג שמוגדר במפת התמונות המותרות של התשתית (לדוגמה, latest או stable). המערכת דוחה תגים לא מוכרים אם מוגדרת מפת 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 OK):

  { "id": "sim-a1b2c3d4e5f6" }
  

מחיקת סימולציה

נקודת הקצה הזו מבטלת סימולציה בהמתנה או סימולציה שפועלת, ומוחקת את המשאבים שמשויכים אליה.

• נקודת קצה: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
• Headers:
  • Content-Type: application/json

• גוף הבקשה:

  { "id": "sim-a1b2c3d4e5f6" }
  

• תגובה להצלחה (200 OK): אובייקט JSON ריק {}.

קריאת נתוני סימולציה

כדי לקרוא נתוני סימולציה, אפשר ליצור אינטראקציה עם הפונקציה simulation-reader. נקודות הקצה האלה משתמשות בשיטת GET כדי לאחזר היסטוריה, סטטוס והגדרות מערכת.

1. הצגת רשימת הסימולציות

אחזור רשימה של סימולציות עם תמיכה בסינון ובמיון.

• נקודת קצה: 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 (string): כיוון המיון, 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"
  }
  

2. איך מקבלים סימולציה ספציפית

הסוכן מאחזר את הפרטים המלאים של סימולציה ספציפית לפי המזהה שלה.

• נקודת קצה:

  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
  }
  

3. קבלת מדדים ותצורה של המערכת

נקודות הקצה האלה מספקות תובנות לגבי העומס הנוכחי וההגדרה של תשתית הסימולציה.

• ‫Get Running Count: מחזירה את מספר הסימולציות הפעילות.

  • נקודת קצה:

    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
    }