فهم عملية التحقّق من صحة المسار

بعد إنشاء مسار، تُجري واجهة برمجة التطبيقات Roads Selection API عملية تحقّق. يضمن هذا التحقّق أنّ المسار مناسب لجمع البيانات وتعديلها ضمن "إحصاءات إدارة الطرق". تكتمل هذه العملية عادةً في غضون بضع دقائق.

يمكنك رصد حالة التحقّق من صحة مساراتك من خلال الحقل state في ردّ من واجهة برمجة التطبيقات. يمكنك التحقّق من ذلك باستخدام نقطة النهاية get، كما هو موضّح في مقالة الحصول على المسارات المحدّدة، أو من خلال فحص الجدول routes_status في BigQuery.

حالات المسار

يشير الحقل state في مصدر SelectedRoute إلى حالة التحقّق والتشغيل الحالية. يمكن أن يحتوي الحقل state على القيم التالية:

• STATE_UNSPECIFIED: لم يتم ضبط حالة التحقّق من صحة هذا المسار.
• ‫STATE_VALIDATING: يتم التحقّق من صحة المسار.
• ‫STATE_RUNNING: اجتاز المسار عملية التحقّق بنجاح وأصبح نشطًا الآن. تجمع واجهة برمجة التطبيقات البيانات بشكل نشط وترسل تحديثات دورية لهذا المسار إلى BigQuery أو Pub/Sub أو كليهما.
• ‫STATE_DELETING: تم وضع علامة على المسار لحذفه، وتتم إزالته من النظام.
• STATE_INVALID: تعذّر التحقّق من صحة المسار استنادًا إلى معايير محدّدة. عندما تكون حالة المسار STATE_INVALID، يتضمّن الردّ الحقل validationError الذي يقدّم تفاصيل حول سبب تعذُّر التحقّق من الصحة.

أخطاء التحقق من الصحة

عندما تكون قيمة state الخاصة بمورد SelectedRoute هي STATE_INVALID، يتضمّن ردّ واجهة برمجة التطبيقات الحقل validationError. يوفّر هذا الحقل سببًا محدّدًا لتعذُّر التحقّق من الصحة.

يمكن أن يتضمّن الحقل validationError القيم التالية:

• VALIDATION_ERROR_UNSPECIFIED: لم يتم ضبط خطأ التحقّق من صحة هذا المسار.
• VALIDATION_ERROR_ROUTE_OUTSIDE_JURISDICTION: المسار خارج نطاق السلطة المسموح بها لمشروعك.
• ‫VALIDATION_ERROR_LOW_ROAD_USAGE: المسار ذو استخدام منخفض للطرق، ما يعني أنّه لا يمكن جمع بيانات حركة مرور كافية لإجراء تحليل مفيد. قد يصبح المسار الذي تم تصنيفه على أنّه غير صالح بسبب انخفاض استخدام الطريق صالحًا مرة أخرى إذا زاد حجم حركة المرور عن حدّ معيّن مسبقًا. مزيد من المعلومات حول المسارات التي تتضمّن طرقًا منخفضة

مسار ذو استخدام منخفض للطرق

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

إليك ما يمكن توقّعه للمسارات ذات الاستخدام المنخفض للطرق:

• استمرار نشر البيانات في BigQuery: حتى إذا تم تصنيف مسار على أنّه STATE_INVALID بسبب انخفاض معدّل استخدام الطريق، تواصل واجهة برمجة التطبيقات معالجة أي بيانات متاحة لهذا المسار ونشرها في BigQuery.
• توقُّف تعديلات Pub/Sub: تتوقف التعديلات الدورية في الوقت الفعلي على Pub/Sub إذا تغيّر state للمسار إلى STATE_INVALID.
• التقييمات ربع السنوية: تُجري واجهة برمجة التطبيقات تقييمات ربع سنوية لجميع المسارات النشطة من حيث حجم الزيارات.
  • في حال رصد عدد قليل من الزيارات أثناء التقييم، ستصدر واجهة برمجة التطبيقات تحذيرًا ضمن المرجع SelectedRoute.
  • إذا استمر انخفاض عدد الزيارات لأربعة أرباع متتالية، سيتغير state الخاص بالمسار إلى STATE_INVALID، وسيتوقف تلقّي التحديثات من Pub/Sub.
• إعادة التحقّق ممكنة: حتى إذا كان المسار STATE_INVALID، سيظل خاضعًا لعمليات تقييم مستمرة لحركة المرور. قد تؤدي عمليات التقييم اللاحقة إلى إعادة تصنيف المسار على أنّه صالح (STATE_RUNNING) إذا زاد حجم الزيارات فيه عن حدّ معيّن مسبقًا.
• حالة المراقبة: يمكنك مراقبة حالة التحقّق من المسار من خلال نقطة النهاية get، كما هو موضّح في مقالة الحصول على المسارات المحدّدة، أو من خلال فحص الجدول routes_status في BigQuery.

تحديد المشاكل وحلّها في المسارات غير الصالحة

إذا كان المسار state هو STATE_INVALID، اتّبِع إرشادات تحديد المشاكل وحلّها التالية استنادًا إلى validationError الذي تتلقّاه:

• VALIDATION_ERROR_ROUTE_OUTSIDE_JURISDICTION: يشير هذا الخطأ إلى أنّ المسار المحدّد يتجاوز المنطقة الجغرافية المصرّح بها لمشروعك. لحلّ هذه المشكلة، احذف المسار الحالي وأعِد إنشاءه، مع التأكّد من أنّ جميع نقاطه (نقطة البداية ونقطة النهاية وأي نقاط وسيطة) تقع ضمن نطاق السلطة الذي يتبعه مشروعك المعتمَد.

• VALIDATION_ERROR_LOW_ROAD_USAGE: يشير هذا الخطأ إلى أنّ المسار المحدّد لا يتضمّن بيانات كافية عن استخدام الطرق لإجراء تحليل وتعديلات مفيدة. لحلّ هذه المشكلة، احذف المسار الحالي وأعِد إنشاءه، واختَر منطقة ذات معدّل استخدام أعلى للطرق أو "مدى الازدحام" لجمع البيانات. يُرجى العِلم أنّه إذا كان مسارك يتضمّن هذا الخطأ، يمكن أن تتغيّر حالة المسار إلى STATE_RUNNING إذا زادت حركة المرور بمرور الوقت كما هو موضّح في مسار استخدام الطريق المنخفض.