Để phù hợp với mô hình phát triển ổn định của nhánh chính và đảm bảo tính ổn định của nền tảng cho hệ sinh thái, chúng tôi sẽ xuất bản mã nguồn lên AOSP vào quý 2 và quý 4 năm 2026. Để tạo và đóng góp cho AOSP, hãy sử dụng android-latest-release. Nhánh tệp kê khai android-latest-release sẽ luôn tham chiếu đến bản phát hành gần đây nhất được chuyển đến AOSP. Để biết thêm thông tin, hãy xem bài viết Các thay đổi đối với AOSP.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Hướng dẫn sử dụng

Bạn có thể chạy mô phỏng bằng bản minh hoạ web được cung cấp hoặc bằng cách gọi trực tiếp API REST.

Đầu vào và đầu ra

Tệp đầu vào và đầu ra sử dụng bộ chứa Cloud Storage từ chế độ thiết lập Terraform.

Thư mục đầu vào phải chứa các tệp metrics_config.zip và publisher_config.zip. Bạn có thể xác định đường dẫn đến tệp này nếu cần.

Thùng chứa các đầu ra có một thư mục simulations, lưu trữ từng mô phỏng theo mã nhận dạng. Mỗi thư mục mô phỏng đều chứa một thư mục đầu vào có các tệp đầu vào đã sao chép và một thư mục đầu ra. Thư mục đầu ra chứa bugreport, tệp logcat và các tệp trình mô phỏng đã tạo.

Sử dụng bản minh hoạ trên web

Nền tảng này bao gồm một ứng dụng web dựa trên Flutter cho mục đích minh hoạ, cho phép bạn xem, tạo và quản lý các mô phỏng. Bạn nên xây dựng giao diện người dùng của riêng mình cho phù hợp với nhu cầu.

Ứng dụng minh hoạ được triển khai cho App Engine và yêu cầu bạn đăng nhập bằng Tài khoản Google. API này được bảo vệ bằng Mã ứng dụng khách OAuth 2.0 được định cấu hình trong dự án trên đám mây của bạn. Tài khoản đã đăng nhập phải có quyền IAM để gọi Cloud Functions đã triển khai. Hãy xem phần Uỷ quyền truy cập bằng IAM để biết hướng dẫn về cách cấp các quyền cần thiết cho tài khoản người dùng, chẳng hạn như vai trò Trình gọi Cloud Functions (roles/cloudfunctions.invoker).

Lượng công việc của người sử dụng

Đăng nhập bằng Tài khoản Google của bạn, được xác thực bằng quy trình OAuth 2.0.
Xem các mô phỏng trên trang chính, trang này liệt kê tất cả các mô phỏng bằng cách truy vấn cơ sở dữ liệu Firestore (nơi lưu giữ mọi thông tin thực thi).
Chuyển đến một biểu mẫu để lên lịch cho một hoạt động mô phỏng mới bằng cách nhấp vào nút thao tác + ở góc dưới cùng bên phải. Bạn cung cấp một số thông số, bao gồm đường dẫn đầu vào, mã nhận dạng bản dựng và loại phiên bản. Để biết thêm thông tin, hãy xem phần Tạo mô phỏng.
Kiểm tra trạng thái của màn hình trong danh sách cập nhật mô phỏng. Danh sách này cho biết trạng thái của mô phỏng mới, ví dụ: PENDING, RUNNING, COMPLETED.
Sau khi quá trình mô phỏng hoàn tất, hãy xem các báo cáo và cấu phần phần mềm đã tạo. Các tệp đầu vào, báo cáo đầu ra, nhật ký, Logcat và Bugreport được lưu trữ trong Cloud Storage.
Không bắt buộc: Huỷ một hoạt động mô phỏng đang chạy hoặc đã lên lịch.

Sử dụng API

Để tự động hoá và tích hợp với các hệ thống khác, bạn có thể sử dụng API REST.

Phần giữ chỗ CLOUD_FUNCTION_URL được dùng trong phần Xác thực và trong các định nghĩa điểm cuối đề cập đến URL cơ sở của Cloud Function đang được gọi. Bạn có thể tìm thấy URL hàm trong bảng điều khiển Cloud trên trang Cloud Functions; URL của mỗi hàm sẽ xuất hiện trên thẻ Điều kiện kích hoạt của trang Thông tin chi tiết về hàm. Ngoài ra, bạn có thể tìm thấy các URL này trong đầu ra Terraform được in sau khi chạy lệnh apply.

Xác thực

Tất cả các yêu cầu API đều phải được xác thực bằng mã nhận dạng chứng minh danh tính của người gọi. Danh tính (người dùng hoặc tài khoản dịch vụ) phải có quyền Cloud Functions Invoker đối với hàm đích.

Lời gọi của người dùng (cục bộ và CLI): Khi gọi API từ một máy cục bộ hoặc một môi trường không phải Google Cloud, bạn phải sử dụng mã thông báo nhận dạng do Google phát hành cho một tài khoản người dùng.
```
TOKEN=$(gcloud auth print-identity-token)
```
Lệnh gọi tài khoản dịch vụ (trong Google Cloud): Khi gọi API từ một tài nguyên Google Cloud (ví dụ: một VM Compute Engine, một Cloud Function khác hoặc một cụm Kubernetes), hãy sử dụng danh tính của Tài khoản dịch vụ được đính kèm của tài nguyên. Bạn nên tìm nạp mã thông báo từ máy chủ siêu dữ liệu của tài nguyên.
```
TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")
```

Đưa mã thông báo đã truy xuất vào tiêu đề Authorization của các yêu cầu dưới dạng mã thông báo Bearer.

Điểm cuối

Các điểm cuối hướng đến người dùng của ngăn xếp Mô phỏng dữ liệu đo từ xa trên đám mây cho phép bạn tạo và xoá các hoạt động mô phỏng hoặc đọc thông tin mô phỏng từ cơ sở dữ liệu.

Tạo mô phỏng

Điểm cuối này tạo một yêu cầu mô phỏng mới và lên lịch để thực thi yêu cầu đó.

Điểm cuối: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request
Nội dung yêu cầu:
```
{
  "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 (chuỗi): Thẻ của hình ảnh Docker tác nhân cần sử dụng, ví dụ: latest.
  
  Quan trọng: Giá trị này phải khớp với một thẻ được xác định trong bản đồ hình ảnh được phép của cơ sở hạ tầng, ví dụ: latest, stable. Hệ thống sẽ từ chối các thẻ không xác định nếu bạn xác định một bản đồ SHA256 trong Terraform.
- file_path (chuỗi): Đường dẫn trong bộ chứa GCS đến thư mục chứa metrics_config.zip và publisher_config.zip.
- instance_type (chuỗi): Loại máy Compute Engine. Loại này phải hỗ trợ ảo hoá lồng nhau, chẳng hạn như dòng n1, n2 hoặc t2d. Để biết thêm thông tin, hãy xem bài viết tổng quan về tính năng ảo hoá lồng nhau.
- owner (chuỗi): Email của người dùng bắt đầu mô phỏng.
- max_simulation_time (số nguyên): Thời gian tối đa tính bằng giây mà quá trình mô phỏng chạy.
- max_report_count (số nguyên): Số lượng báo cáo đo từ xa sau khi quá trình mô phỏng kết thúc.
Phản hồi thành công (200 OK):
```
{ "id": "sim-a1b2c3d4e5f6" }
```

Xoá mô phỏng

Điểm cuối này huỷ một hoạt động mô phỏng đang chờ xử lý hoặc đang chạy và xoá các tài nguyên liên kết của hoạt động đó.

Điểm cuối: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
Tiêu đề:
- Content-Type: application/json
Nội dung yêu cầu:
```
{ "id": "sim-a1b2c3d4e5f6" }
```
Phản hồi thành công (200 OK): Một đối tượng JSON trống {}.

Đọc dữ liệu mô phỏng

Để đọc dữ liệu mô phỏng, bạn có thể tương tác với hàm simulation-reader. Các điểm cuối này sử dụng phương thức GET để truy xuất nhật ký, trạng thái và cấu hình hệ thống.

Liệt kê các mô phỏng

Truy xuất danh sách mô phỏng được phân trang có hỗ trợ lọc và sắp xếp.

Điểm cuối: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations
Tham số truy vấn (tất cả đều không bắt buộc):
- status (chuỗi): Lọc theo trạng thái mô phỏng (running, Simulation request received, cancelled hoặc completed).
- owner (chuỗi): Lọc theo email của chủ sở hữu.
- sort_by (chuỗi): Trường để sắp xếp (received_at, status_updated_at, started_at). Mặc định là received_at.
- sort_order (chuỗi): Chiều sắp xếp, asc hoặc desc. Giá trị mặc định là desc.
- page_size (số nguyên): Số kết quả trên mỗi trang. Giá trị mặc định là 20.
- page_token (chuỗi): Mã thông báo để tìm nạp trang kết quả tiếp theo.

Yêu cầu minh hoạ:

curl -H "Authorization: Bearer $TOKEN"
"https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"

Phản hồi thành công (200 OK):

Trả về một đối tượng JSON chứa một mảng các mô phỏng và một next_page_token không bắt buộc.

{
  "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"
}

Tải một bản mô phỏng cụ thể

Truy xuất thông tin chi tiết đầy đủ của một hoạt động mô phỏng cụ thể theo mã nhận dạng.

Điểm cuối:

GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]

Phản hồi thành công (200 OK): Trả về một đối tượng JSON chứa thông tin chi tiết về mô phỏng được yêu cầu.

{
  "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
}

Nhận chỉ số và cấu hình hệ thống

Các điểm cuối này cung cấp thông tin chi tiết về tải và cấu hình hiện tại của cơ sở hạ tầng mô phỏng.

Nhận số lượng đang chạy: Trả về số lượng mô phỏng đang chạy.
- Điểm cuối:
```
GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count
```
- Phản hồi thành công (200 OK):
```
{
  "count": 0
}
```
Nhận số lượng VM đồng thời tối đa: Trả về số lượng VM đang chạy đồng thời tối đa đã định cấu hình.
- Điểm cuối:
```
GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms
```
- Phản hồi thành công (200 OK):
```
{
  "max_running_vms": 5
}
```