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

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

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