مرجع API

این صفحه مستندات مرجع برای نقاط پایانی API مولد پیکربندی معیارها (MCG) را ارائه می‌دهد.

نمای کلی نقاط پایانی

بخش‌های بعدی جزئیات نقاط پایانی API موجود در MCG را شرح می‌دهند.

پیکربندی معیارها

• POST /api/v1/generate_metrics_config : یک نمونه MetricsConfig از جزئیات درخواست پیکربندی metric ایجاد کنید.
• 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 : سلامت سرویس را بررسی می‌کند.

انواع محتوای پروتوباف

چندین نقطه پایانی 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 برای فراخوانی REST API استفاده می‌کنند و فرض می‌کنند که شما متغیر محیطی 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)"

پیکربندی معیارها

این بخش، نقاط پایانی برای تولید و اعتبارسنجی پیکربندی‌های معیارها را شرح می‌دهد.

پست /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"
      

پست /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"
      

پست /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"
      

کاتالوگ‌های سیگنال خودرو

این بخش، نقاط پایانی مدیریت کاتالوگ‌های سیگنال خودرو را شرح می‌دهد.

پست /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
      

دریافت /api/v1/vs/

تمام فراداده‌های کاتالوگ سیگنال خودرو را فهرست کنید.

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

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

حذف /api/v1/vs/{version}

کاتالوگ سیگنال وسیله نقلیه مشخص شده را حذف کنید.

{"version": "string"}

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

وضعیت خدمات

این بخش، نقاط پایانی برای بررسی سلامت سرویس را شرح می‌دهد.

دریافت /سلامتی

سلامت سرویس را بررسی کنید.

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