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

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

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

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

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

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

ใช้เว็บเดโม

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

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

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

  1. ลงชื่อเข้าใช้: คุณลงชื่อเข้าใช้ด้วยบัญชี Google โดยตรวจสอบสิทธิ์โดยใช้กระบวนการ OAuth 2.0
  2. ดูการจำลอง: หน้าหลักจะแสดงรายการการจำลองทั้งหมดในอดีตและปัจจุบัน โดยการค้นหาฐานข้อมูล Firestore ซึ่งเก็บข้อมูลการดำเนินการทั้งหมด
  3. สร้างการจำลอง: คุณไปที่แบบฟอร์มเพื่อกำหนดเวลาการจำลองใหม่ โดยคลิกปุ่มการดำเนินการ + ที่มุมขวาล่าง คุณระบุพารามิเตอร์หลายรายการ รวมถึงเส้นทางอินพุต รหัสบิลด์ และประเภทอินสแตนซ์ ดูข้อมูลเพิ่มเติมได้ที่หัวข้อ สร้างการจำลอง
  4. ตรวจสอบสถานะ: รายการการจำลองจะอัปเดตเพื่อแสดงสถานะของการจำลอง ใหม่ (PENDING, RUNNING, COMPLETED, ฯลฯ)
  5. ดูผลลัพธ์: หลังจากที่การจำลองเสร็จสมบูรณ์แล้ว คุณจะดู รายงานและอาร์ติแฟกต์ที่สร้างขึ้นได้ ระบบจะจัดเก็บไฟล์อินพุต รายงานเอาต์พุต บันทึก Logcat และ Bugreport ไว้ใน 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 (เช่น VM ของ 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 (string): แท็กของอิมเมจ Docker ของเอเจนต์ที่จะใช้ (เช่น "ล่าสุด") สำคัญ: ค่านี้ต้องตรงกับแท็กที่กำหนดไว้ใน แผนที่อิมเมจที่อนุญาตของโครงสร้างพื้นฐาน (เช่น "ล่าสุด", "เสถียร") ระบบจะปฏิเสธแท็กที่ไม่รู้จักหากมีการกำหนดแผนที่ SHA256 ไว้ใน Terraform
    • file_path (string): เส้นทางภายใน Bucket ของ GCS ไปยังโฟลเดอร์ที่มี metrics_config.zip และ publisher_config.zip
    • instance_type (string): ประเภทเครื่อง Compute Engine ประเภทนี้ต้องรองรับการจำลองเสมือนแบบซ้อน เช่น ซีรีส์ n1, n2 หรือ t2d ดูข้อมูลเพิ่มเติมได้ที่ ภาพรวมการจำลองเสมือนแบบซ้อน
    • owner (string): อีเมลของผู้ใช้ที่เริ่มการจำลอง
    • max_simulation_time (integer): เวลาสูงสุดเป็นวินาที ที่การจำลองจะทำงาน
    • max_report_count (integer): จำนวนรายงานการวัดและส่งข้อมูลทางไกลหลังจากที่การจำลองเสร็จสิ้น

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

    { "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 เพื่อดึงข้อมูลประวัติ สถานะ และการกำหนดค่าระบบ

1. แสดงรายการการจำลอง

ดึงรายการการจำลองแบบแบ่งหน้าพร้อมการรองรับการกรองและการจัดเรียง

  • ปลายทาง: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • พารามิเตอร์การค้นหา (ไม่บังคับทั้งหมด)

    • status (string): กรองตามสถานะการจำลอง (running, Simulation request received, cancelled, หรือ completed)
    • owner (string): กรองตามอีเมลของเจ้าของ
    • sort_by (string): ช่องที่จะจัดเรียง (received_at, status_updated_at, started_at) ค่าเริ่มต้นคือ received_at
    • sort_order (string): ทิศทางการจัดเรียง asc หรือ desc ค่าเริ่มต้นคือ desc
    • page_size (integer): จำนวนผลลัพธ์ต่อหน้า ค่าเริ่มต้นคือ 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 https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count

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

      {
  "count": 0
}

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

    • ปลายทาง:

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

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

      {
  "max_running_vms": 5
}