مرجع واجهة برمجة تطبيقات

تقدّم هذه الصفحة مستندات مرجعية لنقاط نهاية واجهة برمجة التطبيقات (API) الخاصة بأداة Metrics Configuration Generator (MCG).

نظرة عامة على نقاط النهاية

توضِّح الأقسام التالية نقاط نهاية واجهة برمجة التطبيقات المتاحة في 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

تقبل عدة نقاط نهاية لواجهة برمجة التطبيقات البيانات أو تعرضها بتنسيق مخزن البروتوكول (protobuf). ويتم استخدام نوعَين من المحتوى:

• application/x-protobuf: يشير إلى بيانات protobuf بتنسيقها الثنائي. هذا التنسيق فعال للتواصل بين الأجهزة، ولكن لا يمكن قراءته.
• text/x-protobuf: يشير إلى بيانات protobuf بتنسيقها النصي، الذي يمكن قراءته ويكون مفيدًا لتحديد الأخطاء وحلّها أو الفحص اليدوي.

عندما تتيح نقطة نهاية تنسيقات protobuf متعددة لطلب أو استجابة، استخدِم عنوان Content-Type لتحديد تنسيق بيانات الطلب، وعنوان Accept لتحديد التنسيق الذي تم اختياره لبيانات الاستجابة. على سبيل المثال:

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

استدعاء واجهة برمجة التطبيقات

تستخدم الأمثلة الواردة في هذه الصفحة curl لاستدعاء واجهة برمجة التطبيقات 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)"

إعدادات المقاييس

يوضِّح هذا القسم نقاط نهاية لإنشاء إعدادات المقاييس والتحقّق من صحتها.

POST /api/v1/generate_metrics_config

إنشاء مثال MetricsConfig من تفاصيل طلب إعدادات المقاييس تتضمّن هذه العملية التحقّق من الصحة، وإذا تعذّر الإنشاء بسبب انتهاكات المخطط أو المراجع غير الصالحة أو التبعيات الدورية أو مشاكل أخرى، تعرض واجهة برمجة التطبيقات قائمة بتفاصيل الخطأ.

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"
      

الاستجابات التي تتضمّن أخطاء

عندما يؤدي طلب بيانات من واجهة برمجة التطبيقات إلى حدوث خطأ (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"
          }
        ]
      }
    ]
  }
}