Tài liệu tham khảo API

Trang này cung cấp tài liệu tham khảo cho các điểm cuối API Trình tạo cấu hình chỉ số (MCG).

Tổng quan về điểm cuối

Các phần sau đây trình bày chi tiết về các điểm cuối API có trong MCG.

Cấu hình chỉ số

• POST /api/v1/generate_metrics_config: Tạo một thực thể MetricsConfig từ thông tin chi tiết về yêu cầu cấu hình chỉ số.
• POST /api/v1/get_file_descriptor_set: Trả về các giá trị nhận dạng tệp cho một MetricsConfig nhất định để giải mã báo cáo.
• POST /api/v1/validate_metrics_config: Xác thực MetricsConfig đã truyền, trả về danh sách mọi lỗi xác thực.

Danh mục tín hiệu xe

• POST /api/v1/vs/: Tạo mới hoặc cập nhật Danh mục tín hiệu xe hiện có.
• GET /api/v1/vs/: Liệt kê tất cả siêu dữ liệu trong Danh mục tín hiệu xe.
• DELETE /api/v1/vs/{version}: Xoá Vehicle Signal Catalog được chỉ định.

Trạng thái dịch vụ

• GET /health: Kiểm tra tình trạng của dịch vụ.

Các loại nội dung Protobuf

Một số điểm cuối API chấp nhận hoặc trả về dữ liệu ở định dạng vùng đệm giao thức (protobuf). Có 2 loại nội dung được sử dụng:

• application/x-protobuf: Cho biết dữ liệu protobuf ở định dạng nhị phân. Định dạng này hiệu quả cho việc giao tiếp giữa các máy nhưng không thể đọc được.
• text/x-protobuf: Cho biết dữ liệu protobuf ở định dạng văn bản. Định dạng này con người có thể đọc được và hữu ích cho việc gỡ lỗi hoặc kiểm tra thủ công.

Khi một điểm cuối hỗ trợ nhiều định dạng protobuf cho một yêu cầu hoặc phản hồi, hãy sử dụng tiêu đề Content-Type để chỉ định định dạng của dữ liệu yêu cầu và tiêu đề Accept để chỉ định định dạng đã chọn của dữ liệu phản hồi. Ví dụ:

• -H 'Content-Type: application/x-protobuf'
• -H 'Accept: text/x-protobuf'

Gọi API

Các ví dụ trên trang này sử dụng curl để gọi API REST và giả định rằng bạn đã đặt biến môi trường SERVICE_URL để tham chiếu đến máy chủ nơi MCG được triển khai. Khi chạy cục bộ, thư mục này thường là http://localhost:8005.

Để nhắm đến một phiên bản Cloud Run từ xa, hãy đặt SERVICE_URL bằng cách sử dụng gcloud. Sau đó, hãy thêm một tiêu đề uỷ quyền có mã thông báo nhận dạng OpenID Connect (OIDC) vào lệnh curl:

SERVICE_URL=$(gcloud run services describe mcg-service --region=<var label="Google Cloud region">GCP_REGION</var> --format='value(status.url)')

# Authorization header to append to curl command:
-H "Authorization: Bearer $(gcloud auth print-identity-token)"

Cấu hình chỉ số

Phần này mô tả các điểm cuối để tạo và xác thực cấu hình chỉ số.

POST /api/v1/generate_metrics_config

Tạo một thực thể MetricsConfig từ thông tin chi tiết về yêu cầu định cấu hình chỉ số. Quy trình này bao gồm cả việc xác thực. Nếu quá trình tạo không thành công do vi phạm giản đồ, tham chiếu không hợp lệ, các phần phụ thuộc theo chu kỳ hoặc các vấn đề khác, thì API sẽ trả về danh sách thông tin chi tiết về lỗi.

curl -H "Content-Type: application/json" \
  -H "Accept: text/x-protobuf" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v1/generate_metrics_config"
      

POST /api/v1/get_file_descriptor_set

Trả về chỉ số mô tả tệp cho một MetricsConfig nhất định để giải mã báo cáo.

curl -H "Content-Type: application/x-protobuf" \
  -H "Accept: application/x-protobuf" \
  --data-binary @PATH_TO_METRICS_CONFIG_PB \
  "$SERVICE_URL/api/v1/get_file_descriptor_set"
      

POST /api/v1/validate_metrics_config

Xác thực MetricsConfig đã cung cấp, trả về danh sách mọi lỗi xác thực.

curl -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v1/validate_metrics_config"
      

Danh mục tín hiệu xe

Phần này mô tả các điểm cuối để quản lý Danh mục tín hiệu xe.

POST /api/v1/vs/

Tạo mới hoặc cập nhật Danh mục tín hiệu xe hiện có.

{
  "version": "string",
  "vehicle_signals": "string"
}

{"version": "string"}

curl -H "Content-Type: application/json" \
  --data-binary @- "$SERVICE_URL/api/v1/vs/" << EOF
{
  "version": "v1.0",
  "vehicle_signals": "VEHICLE_SIGNALS_BASE64"
}
EOF
      

GET /api/v1/vs/

Liệt kê tất cả siêu dữ liệu trong Vehicle Signal Catalog.

{"versions": [{"version": "string"}]}

curl "$SERVICE_URL/api/v1/vs/"
      

DELETE /api/v1/vs/{version}

Xoá Vehicle Signal Catalog được chỉ định.

{"version": "string"}

curl --request DELETE "$SERVICE_URL/api/v1/vs/v1.0"
      

Trạng thái dịch vụ

Phần này mô tả các điểm cuối để kiểm tra tình trạng dịch vụ.

GET /health

Kiểm tra trạng thái của dịch vụ.

curl "$SERVICE_URL/health"
      

Phản hồi lỗi

Khi một lệnh gọi API dẫn đến lỗi (HTTP status 4xx hoặc 5xx), phần nội dung phản hồi sẽ chứa một đối tượng lỗi có cấu trúc sau:

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Request validation failed",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "fieldName",
            "description": "error description"
          }
        ]
      }
    ]
  }
}