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

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

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

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

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

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

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

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

في حال تعطُّل تطبيق السائق، يجب أن يعيد التطبيق إنشاء الحالة الحالية ضمن حزمة Driver SDK. يجب أن يحاول التطبيق إعادة إنشاء المهام لضمان توفّرها واستعادة حالاتها الحالية. يجب أن يعيد التطبيق أيضًا إنشاء قائمة المحطات وتحديدها بشكل صريح لحزمة تطوير البرامج Driver 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.
• الإجراءات العلاجية: يمكن إعادة محاولة تنفيذ الطلب بأمان باستخدام خوارزمية الرقود الأسي الثنائي.