מדריך למשתמש

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

קלט ופלט

קבצי הקלט והפלט משתמשים בקטגוריה של Cloud Storage מההגדרה של Terraform.

ספריית הקלט חייבת להכיל metrics_config.zip ו-publisher_config.zip קבצים. אפשר להגדיר את הנתיב לפי הצורך.

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

שימוש בהדגמה באינטרנט

הפלטפורמה כוללת אפליקציית אינטרנט מבוססת-Flutter למטרות הדגמה, שמאפשרת לכם לצפות בסימולציות, ליצור אותן ולנהל אותן. מומלץ לבנות ממשק משתמש משלכם שמותאם לצרכים שלכם.

אפליקציית ההדגמה נפרסת ב-App Engine ונדרשת כניסה באמצעות חשבון Google. הגישה מוגנת באמצעות מזהה לקוח OAuth 2.0 שהוגדר בפרויקט בענן של Google. לחשבון שדרכו נכנסתם צריכות להיות הרשאות IAM להפעלת פונקציות ב-Cloud Functions שפרסתם. הוראות להקצאת ההרשאות הנדרשות לחשבונות משתמשים, כמו התפקיד Cloud Functions Invoker‏ (roles/cloudfunctions.invoker), מופיעות במאמר איך מאשרים גישה באמצעות IAM.

זרימת עבודה של משתמש

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 מאפשרות ליצור ולמחוק סימולציות או לקרוא מידע על סימולציות ממסד הנתונים.

יצירת סימולציה

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

• נקודת קצה (endpoint): 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.

  • ‫file_path (מחרוזת): הנתיב בתוך קטגוריית GCS לתיקייה שמכילה את metrics_config.zip ואת publisher_config.zip.

  • ‫instance_type (string): סוג המכונה של Compute Engine. הסוג הזה צריך לתמוך בווירטואליזציה מקוננת, כמו סדרות n1, n2 או t2d. מידע נוסף זמין במאמר בנושא סקירה כללית על וירטואליזציה מקוננת.

  • ‫owner (מחרוזת): כתובת האימייל של המשתמש שהפעיל את הסימולציה.

  • ‫max_simulation_time (מספר שלם): הזמן המקסימלי בשניות שהסימולציה פועלת.

  • ‫max_report_count (מספר שלם): מספר דוחות הטלמטריה שאחריהם הסימולציה מסתיימת.

• תשובה על הצלחה (200 OK):

  { "id": "sim-a1b2c3d4e5f6" }
  

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

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

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

• גוף הבקשה:

  { "id": "sim-a1b2c3d4e5f6" }
  

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

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

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

רשימת סימולציות

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

• נקודת קצה (endpoint): 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"
  }
  

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

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

• נקודת קצה (endpoint):

  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
  }
  

קבלת מדדים והגדרות של המערכת

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

• קבלת מספר הסימולציות הפעילות: מחזירה את מספר הסימולציות הפעילות.

  • נקודת קצה (endpoint):

    GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count
    

  • תשובה על הצלחה (200 OK):

    {
      "count": 0
    }
    

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

  • נקודת קצה (endpoint):

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

  • תשובה על הצלחה (200 OK):

    {
      "max_running_vms": 5
    }