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

توفّر هذه الصفحة مستندات مرجعية لنقاط نهاية واجهة برمجة التطبيقات 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/: تتيح هذه السمة عرض جميع البيانات الوصفية في Vehicle Signal Catalog.
• ‫DELETE /api/v1/vs/{version}: لحذف "كتالوج إشارات المركبات" المحدّد

حالة الخدمة

• GET /health: التحقّق من حالة الخدمة

أنواع محتوى Protobuf

تقبل العديد من نقاط نهاية واجهة برمجة التطبيقات البيانات أو تعرضها بتنسيق Protocol Buffers (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 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/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/

عرض قائمة بجميع البيانات الوصفية في 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"
      

حالة الخدمة

يصف هذا القسم نقاط النهاية للتحقّق من حالة الخدمة.

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