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

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

الحالة "مفقود" في Fleet Engine

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

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

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

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

حالة "مفقود" في تطبيق السائق

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