คู่มือผู้ใช้

คุณสามารถเรียกใช้การจำลองโดยใช้เดโมบนเว็บที่ให้มาหรือเรียกใช้ REST API โดยตรง

อินพุตและเอาต์พุต

ไฟล์อินพุตและเอาต์พุตจะใช้บักเก็ต Cloud Storage จากการตั้งค่า Terraform

ไดเรกทอรีอินพุตต้องมีไฟล์ metrics_config.zip และ publisher_config.zip คุณสามารถกำหนดเส้นทางไปยังไฟล์ได้ตามต้องการ

ที่เก็บข้อมูลสำหรับเอาต์พุตจะมีไดเรกทอรี simulations ซึ่งจัดเก็บการจำลองแต่ละรายการตามรหัส ไดเรกทอรีการจำลองแต่ละรายการจะมีโฟลเดอร์ inputs ที่มีไฟล์อินพุตที่คัดลอกมาและโฟลเดอร์ outputs โฟลเดอร์ outputs มีรายงานข้อบกพร่อง ไฟล์ logcat และไฟล์จำลองที่สร้างขึ้น

ใช้การสาธิตบนเว็บ

แพลตฟอร์มนี้มีเว็บแอปพลิเคชันที่ใช้ Flutter เพื่อวัตถุประสงค์ในการสาธิต ซึ่งช่วยให้คุณดู สร้าง และจัดการการจำลองได้ เราขอแนะนำให้คุณสร้างอินเทอร์เฟซผู้ใช้ของคุณเองที่ปรับแต่งตามความต้องการ

แอปสาธิตจะติดตั้งใช้งานใน App Engine และกำหนดให้คุณต้องลงชื่อเข้าใช้ด้วยบัญชี Google ซึ่งได้รับการปกป้องโดยใช้รหัสไคลเอ็นต์ OAuth 2.0 ที่กำหนดค่าไว้ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google บัญชีที่ลงชื่อเข้าใช้ต้องมีสิทธิ์ IAM ในการเรียกใช้ Cloud Functions ที่ทำให้ใช้งานได้ ดูวิธีการให้สิทธิ์ที่จำเป็นแก่บัญชีผู้ใช้ เช่น บทบาทผู้เรียกใช้ Cloud Functions (roles/cloudfunctions.invoker) ได้ที่หัวข้อให้สิทธิ์เข้าถึงด้วย IAM

เวิร์กโฟลว์ของผู้ใช้

1. ลงชื่อเข้าใช้ด้วยบัญชี Google โดยตรวจสอบสิทธิ์โดยใช้กระบวนการ OAuth 2.0
2. ดูการจำลองในหน้าหลัก ซึ่งแสดงรายการการจำลองทั้งหมดโดยการค้นหาฐานข้อมูล Firestore ซึ่งเก็บข้อมูลการดำเนินการทั้งหมด
3. ไปที่แบบฟอร์มเพื่อกำหนดเวลาการจำลองใหม่โดยคลิกปุ่มดำเนินการ + ที่มุมขวาล่าง คุณระบุพารามิเตอร์หลายรายการ ซึ่งรวมถึงเส้นทางอินพุต รหัสบิลด์ และประเภทอินสแตนซ์ ดูข้อมูลเพิ่มเติมได้ที่สร้างการจำลอง
4. ตรวจสอบสถานะการตรวจสอบในการอัปเดตรายการการจำลอง ซึ่งจะแสดงสถานะของการจำลองใหม่ เช่น PENDING, RUNNING, COMPLETED
5. หลังจากจำลองเสร็จแล้ว ให้ดูรายงานและอาร์ติแฟกต์ที่สร้างขึ้น ไฟล์อินพุต รายงานเอาต์พุต บันทึก Logcat และรายงานข้อบกพร่องจะจัดเก็บไว้ใน Cloud Storage
6. ไม่บังคับ: ยกเลิกการจำลองที่กำหนดเวลาไว้หรือกำลังทำงานอยู่

การใช้ API

หากต้องการทำงานอัตโนมัติและผสานรวมกับระบบอื่นๆ คุณสามารถใช้ REST API ได้

ตัวยึดตำแหน่ง CLOUD_FUNCTION_URL ที่ใช้ในส่วนการตรวจสอบสิทธิ์และในคำจำกัดความของปลายทางหมายถึง URL ฐานของ Cloud Function ที่เรียกใช้ คุณดู URL ของฟังก์ชันได้ในคอนโซล Google Cloud ในหน้า Cloud Functions โดย URL ของแต่ละฟังก์ชันจะแสดงในแท็บทริกเกอร์ของหน้ารายละเอียดฟังก์ชัน หรือจะค้นหา 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 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

ปลายทาง

ปลายทางที่แสดงต่อผู้ใช้ของสแต็กการจำลองการส่งข้อมูลทางไกลในระบบคลาวด์ช่วยให้คุณสร้างและลบการจำลองหรืออ่านข้อมูลการจำลองจากฐานข้อมูลได้

สร้างแบบจำลอง

ปลายทางนี้จะสร้างคำขอการจำลองใหม่และกำหนดเวลาสำหรับการดำเนินการ

• ปลายทาง: 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 ของ Agent ที่จะใช้ เช่น 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 ได้ ปลายทางเหล่านี้ใช้เมธอด 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 https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count
    

  • การตอบกลับที่สำเร็จ (200 OK):

    {
      "count": 0
    }
    

• Get max concurrent VMs: แสดงผลจำนวนสูงสุดที่กำหนดค่าไว้ของ VM ที่ทำงานพร้อมกัน

  • ปลายทาง:

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

  • การตอบกลับที่สำเร็จ (200 OK):

    {
      "max_running_vms": 5
    }