הפניית API

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

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

בקטעים הבאים מפורטות נקודות הקצה של ה-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/: רשימת כל המטא-נתונים של Vehicle Signal Catalog.
• ‫DELETE /api/v1/vs/{version}: מחיקת קטלוג אותות הרכב שצוין.

סטטוס השירות

• ‫GET /health: בדיקת תקינות השירות.

סוגי תוכן של Protobuf

כמה נקודות קצה ל-API מקבלות או מחזירות נתונים בפורמט של מאגר אחסון לפרוטוקולים (protobuf). משתמשים בשני סוגי תוכן:

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

הגדרת מדדים

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

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"
      

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

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

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/

הצגת רשימה של כל המטא-נתונים של Vehicle Signal Catalog.

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

סטטוס השירות

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

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