מדריך למשתמש

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

קלט ופלט

קבצי הקלט והפלט משתמשים בקטגוריה של 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. במאמר הרשאת גישה באמצעות IAM מוסבר איך לתת את ההרשאות הנדרשות לחשבונות משתמשים, כמו התפקיד 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

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

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

אימות

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

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

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

2. הפעלה של חשבון שירות (בתוך Google Cloud): כשמפעילים את ה-API ממשאב של Google Cloud (לדוגמה, מכונה וירטואלית של Compute Engine, פונקציה אחרת של Cloud Functions או אשכול 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.

נקודות קצה (endpoints)

נקודות קצה (endpoints) שגלויות למשתמשים במערך 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 (מספר שלם): מספר דוחות הטלמטריה שאחריהם הסימולציה מסתיימת.

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

  { "id": "sim-a1b2c3d4e5f6" }
  

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

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

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

• גוף הבקשה:

  { "id": "sim-a1b2c3d4e5f6" }
  

• תגובת הצלחה (‎200 OK): הודעת טקסט פשוט (Request accepted and is being processed).

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

כדי לקרוא נתוני סימולציה, אתם יכולים להשתמש בפונקציה simulation-reader. נקודות הקצה האלה משתמשות ב-method‏ 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 (מספר שלם): מספר התוצאות בכל דף. ברירת המחדל היא 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 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 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
    }