הפניית API

בדף הזה מופיעים מאמרי עזרה של נקודות קצה ל-API של Metrics Configuration Generator (MCG).

סקירה כללית של נקודות הקצה (endpoint)

בקטעים הבאים מפורטות נקודות הקצה ל-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). יש שני סוגי תוכן:

• ‫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 כדי לקרוא ל-API בארכיטקטורת REST, בהנחה שהגדרתם את משתנה הסביבה 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)"

הגדרת המדדים

בקטע הזה מתוארות נקודות קצה (endpoints) ליצירה ולאימות של הגדרות מדדים.

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"
      

קטלוגים של אותות רכב

בקטע הזה מתוארות נקודות קצה לניהול קטלוגים של אותות רכב.

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"
      

סטטוס השירות

בקטע הזה מתוארות נקודות קצה (endpoints) לבדיקת Service Health.

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