เอกสารอ้างอิง API

หน้านี้มีเอกสารอ้างอิงสำหรับปลายทาง API ของเครื่องมือสร้างการกำหนดค่าเมตริก (MCG)

ภาพรวมของปลายทาง

ส่วนต่อไปนี้จะแสดงรายละเอียดปลายทาง API ที่มีใน MCG

การกำหนดค่าเมตริก

• POST /api/v1/generate_metrics_config: สร้างอินสแตนซ์ MetricsConfig จากรายละเอียดคำขอการกำหนดค่าเมตริก
• POST /api/v1/get_file_descriptor_set: แสดงผลตัวอธิบายไฟล์สำหรับ MetricsConfig ที่ระบุเพื่อถอดรหัสรายงาน
• POST /api/v1/validate_metrics_config: ตรวจสอบ MetricsConfig ที่ส่งมา โดยแสดงผลรายการข้อผิดพลาดในการตรวจสอบ

แคตตาล็อกสัญญาณยานพาหนะ

• POST /api/v1/vs/: สร้างแคตตาล็อกสัญญาณยานพาหนะใหม่หรืออัปเดตแคตตาล็อกที่มีอยู่
• GET /api/v1/vs/: แสดงข้อมูลเมตาทั้งหมดของแคตตาล็อกสัญญาณยานพาหนะ
• DELETE /api/v1/vs/{version}: ลบแคตตาล็อกสัญญาณยานพาหนะที่ระบุ

สถานะบริการ

• GET /health: ตรวจสอบสถานะของบริการ

ประเภทเนื้อหา Protobuf

ปลายทาง API หลายรายการยอมรับหรือแสดงผลข้อมูลในรูปแบบบัฟเฟอร์โปรโตคอล (Protobuf) โดยใช้ประเภทเนื้อหา 2 ประเภทดังนี้

• application/x-protobuf: ระบุข้อมูล Protobuf ในรูปแบบไบนารี รูปแบบนี้มีประสิทธิภาพสำหรับการสื่อสารระหว่างเครื่องกับเครื่อง แต่ไม่สามารถอ่านได้
• text/x-protobuf: ระบุข้อมูล Protobuf ในรูปแบบข้อความ ซึ่งสามารถอ่านได้และมีประโยชน์สำหรับการแก้ไขข้อบกพร่องหรือการตรวจสอบด้วยตนเอง

เมื่อปลายทางรองรับ Protobuf หลายรูปแบบสำหรับคำขอหรือการตอบกลับ ให้ใช้ส่วนหัว Content-Type เพื่อระบุรูปแบบข้อมูลคำขอ และส่วนหัว Accept เพื่อระบุรูปแบบข้อมูลการตอบกลับที่เลือก เช่น

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

เรียก API

ตัวอย่างในหน้านี้ใช้ curl สำหรับเรียก REST API และสมมติว่าคุณได้ตั้งค่าตัวแปรสภาพแวดล้อม SERVICE_URL เพื่ออ้างอิงโฮสต์ที่ติดตั้งใช้งาน MCG เมื่อเรียกใช้ในเครื่อง โดยปกติแล้ว URL จะเป็น http://localhost:8005

หากต้องการกำหนดเป้าหมายอินสแตนซ์ Cloud Run ระยะไกล ให้ตั้งค่า SERVICE_URL โดยใช้ gcloud จากนั้นแนบส่วนหัวการให้สิทธิ์ด้วยโทเค็นข้อมูลประจำตัว OpenID Connect (OIDC) ลงในคำสั่ง 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)"

การกำหนดค่าเมตริก

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

POST /api/v1/generate_metrics_config

สร้างอินสแตนซ์ MetricsConfig จากรายละเอียดคำขอการกำหนดค่าเมตริก กระบวนการนี้รวมถึงการตรวจสอบความถูกต้อง และหากการสร้างไม่สำเร็จเนื่องจากการละเมิดสคีมา การอ้างอิงที่ไม่ถูกต้อง การพึ่งพาแบบวนซ้ำ หรือปัญหาอื่นๆ API จะแสดงผลรายการรายละเอียดข้อผิดพลาด

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

แสดงผลตัวอธิบายไฟล์สำหรับ MetricsConfig ที่ระบุเพื่อถอดรหัสรายงาน

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

ตรวจสอบ MetricsConfig ที่ระบุ โดยแสดงผลรายการข้อผิดพลาดในการตรวจสอบ

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

แคตตาล็อกสัญญาณยานพาหนะ

ส่วนนี้อธิบายปลายทางสำหรับการจัดการแคตตาล็อกสัญญาณยานพาหนะ

POST /api/v1/vs/

สร้างแคตตาล็อกสัญญาณยานพาหนะใหม่หรืออัปเดตแคตตาล็อกที่มีอยู่

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

แสดงข้อมูลเมตาทั้งหมดของแคตตาล็อกสัญญาณยานพาหนะ

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

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

DELETE /api/v1/vs/{version}

ลบแคตตาล็อกสัญญาณยานพาหนะที่ระบุ

{"version": "string"}

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

สถานะบริการ

ส่วนนี้อธิบายปลายทางสำหรับการตรวจสอบสถานะของบริการ

GET /health

ตรวจสอบสถานะของบริการ

curl "$SERVICE_URL/health"
      

การตอบกลับข้อผิดพลาด

เมื่อการเรียก API ทำให้เกิดข้อผิดพลาด (HTTP status 4xx หรือ 5xx) เนื้อความของการตอบกลับจะมีออบเจ็กต์ข้อผิดพลาดที่มีโครงสร้างดังต่อไปนี้

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