Kể từ năm 2026, để 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. Để tạo và đóng góp cho AOSP, bạn nên sử dụng android-latest-release thay vì aosp-main. 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 Người dùng

Bạn có thể chạy mô phỏng bằng cách sử dụng Bản minh hoạ trên 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 đầ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 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 báo cáo lỗi, 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 trên App Engine và yêu cầu người dùng đăng nhập bằng Tài khoản Google. Thao tác này được bảo vệ bằng Mã ứng dụng OAuth 2.0 được định cấu hình trong dự án trên đám mây của Google. 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 Quản lý quyền truy cập vào Cloud Functions để 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ò Cloud Functions Invoker (roles/cloudfunctions.invoker).

Luồng công việc của người dùng

Đăng nhập: Bạn đăng nhập bằng Tài khoản Google của mình, được xác thực bằng quy trình OAuth 2.0.
Xem các hoạt động mô phỏng: Trang chính liệt kê tất cả các hoạt động mô phỏng trước đây và hiện tại bằng cách truy vấn cơ sở dữ liệu Firestore. Cơ sở dữ liệu này lưu giữ tất cả thông tin thực thi.
Tạo một hoạt động mô phỏng: Bạn 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ột hoạt động mô phỏng.
Theo dõi trạng thái: Danh sách mô phỏng sẽ cập nhật để cho biết trạng thái của mô phỏng mới (PENDING, RUNNING, COMPLETED, v.v.).
Xem kết quả: Sau khi quá trình mô phỏng hoàn tất, bạn có thể xem các báo cáo và dữ liệu được tạo. Các tệp đầu vào, báo cáo đầu ra, nhật ký, Logcat và Bugreports được lưu trữ trong Cloud Storage.
Xoá một hoạt động mô phỏng: Bạn có thể huỷ một hoạt động mô phỏng đã lên lịch hoặc đang chạy.

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 Functions đ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 cho 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 mục tiêu.

1. 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ôi trường không phải Google Cloud, bạn phải sử dụng Mã nhận dạng do Google phát hành được lấy cho một tài khoản người dùng.
```
TOKEN=$(gcloud auth print-identity-token)
```
2. 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ụ: VM Compute Engine, một Cloud Function khác hoặc một cụm Kubernetes), bạn nên 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ột 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 mà tác nhân sẽ 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.

1. Liệt kê các hoạt động 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ố lượng 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 mẫu:

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

2. Nhận 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
}

3. 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.

Get Running Count (Lấy 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 chạy đồng thời tối đa: Trả về số lượng VM 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
}
```