การอ้างอิง API

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

ภาพรวมของอุปกรณ์ปลายทาง

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

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

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

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

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

สถานะบริการ

• GET /health: ตรวจสอบประสิทธิภาพของบริการ

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

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

• application/x-protobuf: ระบุข้อมูล protobuf ในรูปแบบไบนารีแบบ Wire รูปแบบนี้มีประสิทธิภาพสำหรับการสื่อสารระหว่างเครื่องกับเครื่อง แต่ไม่สามารถอ่านได้โดยมนุษย์
• 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 เมื่อเรียกใช้ในเครื่อง โดยปกติแล้วจะเป็น http://localhost:8005

หากต้องการกำหนดเป้าหมายอินสแตนซ์ Cloud Run ระยะไกล ให้ตั้งค่า SERVICE_URL โดยใช้ gcloud ดังนี้

SERVICE_URL=$(gcloud run services describe mcg-service \
  --region=GCP_REGION \
  --format='value(status.url)')

เมื่อเรียกใช้ปลายทาง Cloud Run ระยะไกล ให้เพิ่มส่วนหัวการให้สิทธิ์ต่อไปนี้ต่อท้ายคำสั่ง curl

-H "Authorization: Bearer $(gcloud auth print-identity-token)"

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

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

POST /api/v2/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/v2/generate_metrics_config"
      

POST /api/v2/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/v2/get_file_descriptor_set"
      

POST /api/v2/validate_metrics_config

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

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

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

ส่วนนี้จะอธิบายปลายทางสำหรับการจัดการ Vehicle Signal Catalog

POST /api/v2/vs/

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

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

{"version": "string"}

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

GET /api/v2/vs/

แสดงข้อมูลเมตาของ Vehicle Signal Catalog ทั้งหมด

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

curl "$SERVICE_URL/api/v2/vs/"
      

DELETE /api/v2/vs/{version}

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

{"version": "string"}

curl --request DELETE "$SERVICE_URL/api/v2/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"
          }
        ]
      }
    ]
  }
}