تحديد المشاكل الشائعة وحلّها

راجِع الأقسام التالية للحصول على المساعدة في حال واجهت أي مشاكل.

الحالة غير متوفّرة في Fleet Engine

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

في سيناريو نادر جدًا لحدوث عطل كارثي في Fleet Engine، قد تحتاج إلى إعادة إنشاء معظم المركبات والمهام أو جميعها. إذا أصبح معدّل الإنشاء مرتفعًا جدًا، قد يتعذّر تنفيذ بعض الطلبات مرة أخرى بسبب مشاكل في الحصة، لأنّ عمليات التحقّق من الحصة متوفّرة لتجنُّب هجمات رفض الخدمة (DOS). في هذه الحالة، عليك تقليل معدّل إعادة الإنشاء باستخدام استراتيجية التراجع عن المحاولات.

عمليات إعادة المحاولة

احرص على أن ينفّذ نظامك عمليات إعادة محاولة للطلبات إلى Fleet Engine لأنّها قد تفشل أحيانًا. تعيد مكتبات برامج Fleet Engine لمحرك البحث محاولة تنفيذ الطلبات تلقائيًا.

فقدان الحالة في تطبيق السائق

في حال تعطُّل تطبيق السائق، يجب أن يعيد التطبيق إنشاء الحالة الحالية ضمن حزمة Driver SDK. يجب أن يحاول التطبيق إعادة إنشاء المهام لضمان توفّرها واستعادة حالاتها الحالية. يجب أن يعيد التطبيق أيضًا إنشاء قائمة المحطات ويضبطها بشكل صريح لحزمة تطوير البرامج (SDK) الخاصة بالسائق.

ملاحظة: يجب إجراء عمليات الاستعادة هذه بشكل مستقل بدون الاعتماد على معلومات من Fleet Engine، باستثناء الأخطاء التي تشير إلى ما إذا كان هناك عنصر متوفّر في قاعدة البيانات ومتى. إذا كان الكيان متوفّرًا، يمكن تجاهل هذا الخطأ وتعديل الكيان باستخدام معرّفه.

أخطاء تجاوز الموعد النهائي

إذا تلقّيت الخطأ DEADLINE_EXCEEDED عند الاتصال بخدمة Fleet Engine، يعني ذلك أنّ الطلب استغرق وقتًا أطول من المهلة المحدّدة. تتضمّن مكتبات برامج Fleet Engine أوقات مهلة تلقائية، ولكن قد تحتاج إلى تعديلها.

للحصول على معلومات عامة حول المواعيد النهائية في gRPC، يُرجى الاطّلاع على gRPC والمواعيد النهائية.

لضبط الموعد النهائي عند استخدام مكتبة برامج Java الخاصة بـ Fleet Engine، يمكنك تعديل إعدادات إعادة محاولة طلبات الإجراءات عن بُعد (RPC). يوضّح المثال التالي كيفية ضبط مهلة مخصّصة عند إعداد VehicleService:

VehicleServiceSettings.Builder settingsBuilder = VehicleServiceSettings.newBuilder();

// Set the timeout to 10 seconds.
settingsBuilder
    .getVehicleSettings()
    .setRetrySettings(
        settingsBuilder.getVehicleSettings().getRetrySettings().toBuilder()
            .setTotalTimeout(java.time.Duration.ofSeconds(10))
            .build());

VehicleServiceClient client = VehicleServiceClient.create(settingsBuilder.build());

أخطاء شائعة في واجهة برمجة التطبيقات

يسرد هذا القسم أخطاء واجهة برمجة التطبيقات الشائعة التي قد تواجهها وأسبابها وكيفية حلّها.

NOT_FOUND (HTTP 404)

تعذّر العثور على العنصر المطلوب (مثل مركبة أو رحلة أو مهمة).

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

ALREADY_EXISTS (HTTP 409)

الكيان الذي تحاول إنشاءه متوفّر مسبقًا.

• السبب: يحدث هذا الخطأ عند استدعاء طريقة إنشاء (مثل CreateVehicle أو CreateTrip) باستخدام رقم تعريف مستخدَم من قبل.
• الإصلاح: إمّا تعديل العنصر الحالي بدلاً من ذلك، أو استخدام معرّف فريد جديد لطلب الإنشاء.

‫PERMISSION_DENIED (HTTP 403)

ليس لديك الأذونات المطلوبة لإكمال الطلب.

• السبب: يحدث هذا الخطأ عادةً إذا كان رمز JSON المميّز للويب (JWT) لا يتضمّن المطالبات الصحيحة، أو إذا كان حساب الخدمة الذي يوقّع على رمز JWT لا يتضمّن أدوار إدارة الهوية وإمكانية الوصول (IAM) المطلوبة. على سبيل المثال، "لا يحتوي رمز JWT على نطاق مطابق للرحلة المطلوبة".
• الإجراءات العلاجية: راجِع أذونات حساب الخدمة وتأكَّد من أنّ مطالبات JWT تتضمّن النطاقات الصحيحة للكيان الذي تحاول الوصول إليه.

INVALID_ARGUMENT (HTTP 400)

هناك وسيطة واحدة أو أكثر تم تمريرها في الطلب غير صالحة.

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

FAILED_PRECONDITION (HTTP 400)

تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذها.

• السبب: تشمل الأسباب الشائعة محاولة تغيير رحلة COMPLETE أو CANCELED إلى ولاية أخرى، أو محاولة تعيين مهمة CLOSED لمركبة.
• الإصلاح: تأكَّد من أنّ الحالة الحالية للعنصر تسمح بالعملية التي تحاول تنفيذها. راجِع رسالة الخطأ لمعرفة المخالفات المحدّدة في الولاية.

UNAVAILABLE (HTTP 503)

الخدمة غير متوفّرة.

• السبب: يشير ذلك إلى مشكلة مؤقتة في خدمة Fleet Engine.
• الحل: يمكن إعادة محاولة تنفيذ الطلب بأمان باستخدام خوارزمية الرقود الأسي الثنائي.