بدء استخدام Fleet Engine لأداء المركبات

قدِّم نموذجًا لأنشطة أسطولك للأول والأخير من عمليات التسليم باستخدام واجهة برمجة تطبيقات Fleet Engine Deliveries. يمكنك استخدام واجهة برمجة التطبيقات هذه باستخدام حزمة Driver SDK لنظامي التشغيل Android وiOS، أو مباشرةً من خلال استخدام استدعاءات HTTP REST أو gRPC.

عملية الإعداد الأوّلية

يمكنك ضبط واجهة برمجة تطبيقات Fleet Engine Deliveries API في Google Cloud Console.

• للحصول على معلومات حول الخطوات التي يجب اتّخاذها داخل وحدة التحكّم وكيفية إنشاء رمز JSON المميّز للويب للتفويض، يمكنك الاطّلاع على المصادقة والترخيص.

• للحصول على تفاصيل حول استخدام وحدة التحكّم، راجِع مستندات Google Cloud Console.

التحقّق من صحة الإعداد

بعد إنشاء حسابات الخدمة، تحقق من اكتمال عملية الإعداد وأنه يمكنك إنشاء مركبة تسليم. يضمن التحقق من الإعداد على الفور أنك عالجت مشكلات التفويض الشائعة التي يمكن أن تنشأ عند إعداد مشروعك. هناك طريقتان للتحقق من الإعداد:

• يمكنك اختبار جزءَين رئيسيَّين من الإعداد: التوقيع على رمز التفويض وإنشاء مركبة تسليم تجريبية باستخدام أداة سطر الأوامر gcloud. للحصول على التفاصيل، يمكنك الاطّلاع على دليل التحقق من الإعداد.

• اختبِر الإعداد باستخدام نماذج مصادقة بيانات محرّكات البحث لمجموعة.

مكتبات العملاء

للحصول على تجربة أفضل للمطوّرين على gRPC أو REST، استخدِم مكتبات العملاء بعدة لغات برمجة شائعة. للحصول على تعليمات حول كيفية الحصول على مكتبات العملاء لتطبيق الخادم، يُرجى الاطّلاع على مكتبات العملاء.

تفترض أمثلة Java في هذا الوثائق أنك على دراية بـ gRPC.

هياكل البيانات

تستخدم واجهة برمجة تطبيقات Fleet Engine Deliveries API هيكلين للبيانات لوضع نماذج لاستلام الشحنات وتسليمها:

• مركبة التسليم المستخدَمة لنقل الشحنة
• مهام استلام وتوصيل الشحن.

يمكنك أيضًا استخدام المهام لوضع نماذج لفواصل السائق والتوقفات المجدولة على مدار اليوم.

مركبات توصيل

تنقل مركبات التوصيل الشحنات من المستودع إلى موقع التسليم، ومن موقع الاستلام إلى المستودع. في بعض الحالات، يمكنهم أيضًا نقل شحنة مباشرة من موقع الاستلام إلى موقع التسليم.

استخدِم Driver SDK لإنشاء عنصر DeliveryVehicle في Fleet Engine وأرسِل معلومات عن الموقع الجغرافي لعملية الشحن وتتبُّع الأسطول.

ملاحظة: يمكنك تعيين ما يصل إلى 500 مهمة و300 جزء متبقّي من رحلة المركبة إلى كائنات DeliveryVehicle.

المهام

بالنسبة إلى الإجراءات التي تتخذها مركبة خلال اليوم، يمكنك تعيين المهام وفقًا لنوع الإجراء:

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

يجب أن يكون لكل مهمة تعينها معرّف مهمة فريد، ولكن يمكن أن تشترك المهام في نفس رقم تعريف التتبع. عندما يحسب Fleet Engine نوافذ الوقت المقدّر للوصول لكل مهمة، فإنه يستخدم جميع المهام والترتيب الذي تمت جدولتها لعمل التقديرات. لمزيد من المعلومات حول معرّفات المهام، راجِع إرشادات معرّف المهمة.

لإنشاء مهام في Fleet Engine، استخدِم أداة إدارة المهام لحزمة تطوير البرامج (SDK) للسائق.

مهام الشحن

أنشئ مهام شحن لكل من استلام الشحنة وتسليمها، وأدرج المعلومات التالية:

• تمثّل هذه السمة الموقع الجغرافي لاستلام الطلبات أو توصيلها.
• رقم تعريف أو رقم تتبُّع
• وقت الثبات لحساب وقت إضافي لإنجاز المهمة أو البحث عن موقف سيارات أو السير إلى موقع التسليم.
• معرّف مهمة فريد يُرجى الاطّلاع على إرشادات معرّف المهمة.

لمزيد من المعلومات، يُرجى الاطّلاع على المواضيع التالية:

Android

• إنشاء مهمة استلام الشحن
• إنشاء مهمة تسليم شحن

iOS

• GMTD DeliveryTaskManager:
• GMTSTaskType

المهام المتعلّقة بعدم التوفّر

تغطي مهام عدم التوفّر الفترات الزمنية التي لا تكون فيها المركبة متاحة لعمليات الاستلام أو التسليم، مثل أوقات الاستراحة لإعادة تعبئة المركبة أو أوقات استراحة السائق.

أنشئ مهمة عدم التوفّر باستخدام المعلومات التالية:

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

ملاحظة: أثناء تنفيذ مهمة عدم التوفّر، لا تتم مشاركة أي معلومات عن الموقع الجغرافي مع المستخدمين النهائيين لـ "مكتبة تتبُّع الشحنات". ومع ذلك، فهي متاحة لمدراء الأسطول من خلال "مكتبة تتبع الأسطول".

لمزيد من المعلومات، يُرجى الاطّلاع على المواضيع التالية:

Android

• عدم التوفّر المجدول

iOS

• GMTD DeliveryTaskManager:
• GMTSTaskType

مهام المحطات المجدوَلة

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

لمزيد من المعلومات، يُرجى الاطّلاع على المواضيع التالية:

Android

• المحطات المجدوَلة

iOS

• GMTD DeliveryTaskManager:
• GMTSTaskType

إرشادات معرّف المهمة

عند إنشاء معرّفات المهام، اتّبِع إرشادات المحتوى والتنسيق التالية:

• إنشاء مُعرّفات مهام فريدة
• لا تكشف عن أي معلومات لتحديد الهوية الشخصية أو بيانات نصية واضحة.
• استخدِم سلاسل Unicode صالحة.
• استخدِم 64 حرفًا أو أقل.
• يجب عدم تضمين أي من أحرف ASCII التالية: "/" أو ":" أو ""\" أو "?" أو "#".
• تتم التسوية وفقًا لنموذج تسوية Unicode.

ملاحظة: يمكنك إنشاء معرّفات المهام باستخدام الآلية الآلية المفضّلة لديك. تنصح Google باستخدام أداة الإصدار 4 من المعرّف الفريد العالمي (UUID).

فيما يلي بعض الأمثلة على معرفات المهام الجيدة:

• 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
• e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
• NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk

يعرض الجدول التالي أمثلة لمعرّفات المهام غير المتوافقة:

أرقام تعريف المهام غير المتوافقة	السبب
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680	يخالف هذا الإعداد معلومات تحديد الهوية الشخصية ومتطلبات الأحرف: الفواصل والنقاط والنقطتين والشرطة المائلة.
JohnDoe-577b484da26f-Cupertino-SantaCruz	يخالف متطلبات معلومات تحديد الهوية الشخصية.
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a	يخالف معلومات تحديد الهوية الشخصية ومتطلبات الأحرف: المسافات البيضاء والفواصل وعلامات الاقتباس. يتجاوز طوله 64 حرفًا.

مزيد من المراجع

لمعرفة الحقول المحددة المضمَّنة في كل بنية بيانات، راجِع المستندات المرجعية لواجهة برمجة التطبيقات لكل من DeliveryVehicle (gRPC وREST) وTask (gRPC وREST).

عمر المركبة

يمثّل العنصر DeliveryVehicle مركبة توصيل من الميل الأول أو الأخير. يمكنك إنشاء كائن DeliveryVehicle باستخدام:

• رقم تعريف المشروع لمشروع Google Cloud الذي يحتوي على حساب الخدمة المستخدَم لطلب واجهات برمجة تطبيقات Fleet Engine
• رقم تعريف مركبة يمتلكها العميل.

استخدِم معرّفات المركبات الفريدة لكل مركبة. لا تُعِد استخدام رقم تعريف المركبة إلا إذا لم تكن هناك مهام نشطة للمركبة الأصلية.

يحذف Fleet Engine تلقائيًا عناصر DeliveryVehicle التي لم يتم تعديلها باستخدام UpdateDeliveryVehicle بعد سبعة أيام. لمعرفة ما إذا كانت هناك مركبة:

1. يُرجى إجراء مكالمة مع الرقم UpdateDeliveryVehicle.
2. إذا ظهر لك خطأ NOT_FOUND، اتّصِل بـ CreateDeliveryVehicle لإعادة إنشاء المركبة. إذا أدّت المكالمة إلى إرجاع مركبة، ستظلّ متاحة للتحديث.

ملاحظة: في حال الاتصال بـ "CreateDeliveryVehicle" مع رقم تعريف المشروع ومعرّف المركبة، ستظهر لك رسالة خطأ.

سمات المركبات

يحتوي كيان DeliveryVehicle على حقل متكرّر لـ DeliveryVehicleAttribute. تتضمن واجهة برمجة التطبيقات ListDeliveryVehicles حقل filter الذي يمكن أن يحصر كيانات DeliveryVehicle التي تم عرضها لتقتصر على تلك التي تتضمن السمات المحددة. لا يؤثّر DeliveryVehicleAttribute في سلوك توجيه Fleet Engine.

لا تضمِّن معلومات تحديد الهوية الشخصية (PII) أو معلومات حسّاسة في السمات لأنّ هذا الحقل قد يكون مرئيًا للمستخدمين.

مدة المهمة

يمكنك إنشاء مهام وتحديثها والاستعلام عنها في Fleet Engine باستخدام واجهتَي gRPC أو REST لواجهة برمجة التطبيقات Deliveries API.

يحتوي الكائن Task على حقل حالة لتتبُّع مستوى تقدُّمه خلال مراحل نشاطه. يتم نقل القيم من OPEN إلى CLOSED. يتم إنشاء مهام جديدة في الحالة OPEN، مما يشير إلى أي مما يلي:

• لم يتم تعيين المهمة بعد لمركبة تسليم.
• لم تجتز مركبة التسليم حتى الآن موقف المركبة المخصص للمهمة.

إرشادات حول المهام

لا يمكنك تعيين مهمة لمركبة إلا عندما تكون في الحالة OPEN.

يمكنك إلغاء مهمة عن طريق إزالتها من قائمة محطات توقف المركبات، ما يؤدي إلى ضبط حالة المهمة على "مغلقة" تلقائيًا.

عندما تكمل مركبة المهمة موقف مركبة المهمة:

1. عدِّل حقل نتائج المهمة إلى "تم بنجاح" أو "فشل".

   ملاحظة: يمكنك تحديد نتيجة المهمة في أي وقت قبل أو بعد اكتمال المهمة، ولكن يمكنك ضبطها مرة واحدة فقط.

2. حدِّد الطابع الزمني للحدث.

   بعد ذلك، تشير مكتبة تتبع مجموعة JavaScript إلى نتيجة المهمة ويتم تعيين حالة المهمة على "مغلقة" تلقائيًا. ولمزيد من المعلومات، يُرجى الاطّلاع على تتبُّع مجموعة الأجهزة باستخدام مكتبة JavaScript Fleet Tracking (تتبُّع مجموعة الأجهزة في JavaScript).

كما هو الحال مع المركبات، يحذف Fleet Engine المهام التي لم يتم تحديثها بعد سبعة أيام، وإذا حاولت إنشاء مهمة ذات معرف موجود، فسيتم عرض خطأ.

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

سمات المهام

يحتوي الكيان Task على حقل متكرّر لـ TaskAttribute، والذي يمكن أن يكون له قيمة من أحد الأنواع الثلاثة: سلسلة ورقم وقيمة منطقية. تتضمّن واجهة برمجة التطبيقات ListTasks حقل filter الذي يمكن أن يحصر كيانات Task التي تم عرضها، بحيث تشمل السمات المحدَّدة. لا تؤثر سمات المهام في سلوك توجيه Fleet Engine.

لا تضمِّن معلومات تحديد الهوية الشخصية أو معلومات حساسة أخرى في السمات، لأنّ هذه السمات قد تكون مرئية للمستخدمين.

إدارة مراحل نشاط المركبات والمهام

تذكير: يعمل نظامك الداخلي كمصدر موثوق للبيانات التي تعزّزها Fleet Engine Deliveries API نيابةً عنك.

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

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

على سبيل المثال، لنفترض أن لديك السيناريو التالي:

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

يوضِّح الرسم البياني التالي هذه العمليات على مستوى عام. كما يعرض العلاقة القياسية بين نظامك والعميل وFleet Engine.

إدارة الرموز المميّزة للعميل

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

1. أنشئ الرمز المميّز باستخدام دور حساب الخدمة مستخدم خدمة Drive غير موثوق به في تسليم مجموعة محركات البحث.

2. امنح تطبيق برنامج التشغيل رمزًا مميزًا للنطاق المحدود. يتيح له هذا النطاق تحديث الموقع الجغرافي للجهاز في Fleet Engine فقط.

ويضمن هذا المنهج أن تلتزم المكالمات التي تنشأ من أجهزة جوّالة - تعتبر بيئات منخفضة الثقة - بمبدأ الامتياز الأقل.

الأدوار الأخرى لحساب الخدمة

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

لمزيد من المعلومات عن استخدامات أدوار السائق الموثوق بها وغير الموثوق بها، يُرجى الاطّلاع على إعداد المشروع على السحابة الإلكترونية.

وضع نموذج ليوم العمل

يصف الجدول التالي كيف يمكن أن يبدو يوم العمل للسائقين من الدرجة الأولى أو الأخيرة في شركة تسليم وخدمات لوجستية. قد تختلف شركتك في التفاصيل، ولكن يمكنك أن ترى كيف يمكنك تصميم يوم العمل.

الوقت	النشاط	وضع النماذج
خلال 24 ساعة من بداية اليوم	يقوم المرسل بتعيين الشحنات لمركبات أو مسارات التوصيل.	يمكنك إنشاء مهام لعمليات تسليم الشحن واستلام الطلب والاستراحات وغيرها في Fleet Engine بشكل مسبق. على سبيل المثال، يمكنك إنشاء مهمة لاستلام الشحن أو مهمة تسليم الشحن أو تحديد موعد عدم التوفّر أو محطة مُجدوَلة. يمكنك إسناد المهام إلى مركبة بعد الانتهاء من مجموعة طرود التسليم وترتيب تسليمها.
بداية اليوم	يبدأ السائق اليوم في المستودع من خلال تسجيل الدخول إلى تطبيق Drive.	إعداد Delivery Driver API أنشئ مركبة التوصيل في Fleet Engine حسب الحاجة.
	يحمّل السائق الشحنات على مركبة التوصيل ويفحص الشحنات.	إذا لم يتم إنشاء مهام تسليم الشحن بشكل مسبق، يمكنك إنشاء مهام تسليم الشحن في وقت الفحص.
	يؤكد السائق ترتيب المهام المراد تنفيذها.	إذا لم يتم إنشاؤها مسبقًا، يمكنك إنشاء مهام استلام الشحنات وعدم التوفّر المجدول والمحطات المُجدوَلة.
	يغادر السائق المستودع ويلتزم بالعدد التالي من المهام المطلوب إكمالها.	إسناد جميع المهام أو مجموعة فرعية من المهام للمركبة من خلال تنفيذ طلب الإكمال.
	السائق يسلم شحنة.	بعد الوصول إلى محطة التسليم، اتّخِذ إجراءات تتعلّق بمركبة تصل إلى محطة معيّنة. بعد تسليم الشحنة، أغلِق مهمة التسليم، ويمكنك أيضًا الاطّلاع على حالة شحن المتجر والمعلومات الوصفية الأخرى إذا أردت. بعد إكمال كل المهام عند المحطة وقبل البدء بالقيادة إلى المحطة التالية، نفِّذ الإجراءات المتعلقة بإكمال المركبة والمركبة في طريقها إلى المحطة التالية.
	يلتقي السائق بمركبة تغذية لنقل الشحنات الإضافية إلى مركبة التسليم.	يجب تصنيف نقطة التلاقي لعملية النقل بين مركبات التغذية ومركبات التسليم على أنّها محطة توقّف مجدولة. بعد نقل الشحنات ومسحها ضوئيًا، يمكنك إنشاء مهام تسليم إذا لم يسبق إنشاؤها. يمكنك بعد ذلك تعديل ترتيب إكمال المهام من خلال تعيين المهام إلى مركبة وتعديل ترتيب المهام.
	يتلقى السائق إشعارًا بطلب الاستلام.	بعد قبول طلب الاستلام، عليك إنشاء مهمّة لاستلام الطلبات. يمكنك بعد ذلك تعديل ترتيب تنفيذ المهام من خلال تخصيص المهام لمركبة وتعديل ترتيب المهام.
ظهرًا	يأخذ السائق استراحة الغداء.	إذا كان الموقع الجغرافي مرتبطًا بالمهمة "عدم التوفّر"، يمكنك التعامل معها كأي مهمة أخرى. تنفيذ إجراءات متعلقة بمركبة تصل إلى محطة توقف وإكمال المركبة وبالمركبة في طريقها إلى المحطة التالية في الحالات الأخرى، ليس عليك اتّخاذ أي إجراء حتى نهاية الفاصل. أزِل المهمة من خلال تأكيد المهام التالية والمتبقية وتعديل ترتيب المهام.
	يستقل السائق شحنة.	وقد تم تصميمه على غرار محطة التسليم. يمكنك تنفيذ إجراءات متعلقة بمركبة تصل إلى محطة توقف وإغلاق مهمة، بالإضافة إلى تخزين حالة الشحن ومعلومات وصفية أخرى إذا أردت ذلك. بعد إكمال جميع المهام عند المحطة وقبل البدء بالقيادة إلى المحطة التالية، نفِّذ الإجراءات المتعلّقة بإكمال المركبة والمركبة في طريقها إلى المحطة التالية. ملاحظة: لضمان تقديم معلومات فوترة صحيحة، يجب أن تكون هناك مَهمّة توصيل مقابلة لكل طلبات الاستلام. إذا كان سيتم تسليم الطلب إلى موقع جغرافي آخر على المسار نفسه في ذلك اليوم، ننصحك بتصميم مهمة التسليم هذه كأيّ مهمة تسليم أخرى على المسار. إذا كان السائق يعيد استلام الطلب إلى المستودع، ننصحك بإنشاء مهمة تسليم في وجهة المستودع.
	يقوم السائق بإجراء محطة مجدولة لاستلام الشحنات من صندوق إيداع.	تشبه هذه المنطقة تمامًا أي محطة نقل أخرى. تنفيذ إجراءات متعلّقة بمركبة تصل إلى محطة توقف وإغلاق مهمة بعد إكمال جميع المهام عند المحطة والبدء بالقيادة إلى المحطة التالية، نفِّذ الإجراءات المتعلقة بإكمال المركبة والمركبة في طريقها إلى المحطة التالية.
	يتلقى السائق إشعارًا بشأن تحويل شحنة إلى موقع بديل.	يجب ضبط حالة مهمة تسليم الشحن الأصلية على "مكتملة" وإنشاء مهمة تسليم شحن جديدة لموقع التسليم الجديد. لمزيد من المعلومات، يُرجى الاطّلاع على إعادة توجيه شحنة.
	حاول السائق تسليم حزمة ولكن لم يتمكن من القيام بذلك.	وتم تصميم ذلك بالطريقة نفسها التي يتم بها إيقاف تسليم ناجح، ما يشير إلى أنّ مهمة التسليم قد اكتملت. تنفيذ الإجراءات المتعلّقة بمركبة تصل إلى محطة توقف بعد عدم تسليم الشحنة، أغلِق المهمة، ويمكنك اختياريًا الاطّلاع على حالة شحن المتجر والمعلومات الوصفية الأخرى. بعد إكمال جميع المهام عند المحطة وقبل البدء بالقيادة إلى المحطة التالية، نفِّذ الإجراءات المتعلّقة بإكمال المركبة والمركبة في طريقها إلى المحطة التالية.
	تم إبلاغ السائق بحجز (عدم تسليم) شحنة.	بعد تلقّي الإشعار وتأكيده، اضبط حالة المهمة على "مكتملة".
	تم إخطار السائق بتسليم شحنة معينة بعد ذلك، مما يؤدي إلى تغيير طلب التسليم المُلتزم.	تعديل ترتيب المهام
	يختار السائق تسليم شحنة خارج الطلب.	تعديل ترتيب المهام ثم المتابعة كالمعتاد.
	يقوم السائق بتسليم شحنات متعددة إلى موقع واحد.	وتم تصميم ذلك بشكل مشابه لمحطة تسليم شحنة واحدة. بعد الوصول إلى المحطة، نفِّذ إجراءات متعلّقة بمركبة تصل إلى محطة معيّنة. بعد تسليم كل شحنة، أغلِق كل مهمة، وحالة شحن المتجر والمعلومات الوصفية الأخرى إذا أردت. بعد إكمال جميع المهام عند المحطة وقبل البدء بالقيادة إلى المحطة التالية، نفِّذ الإجراءات المتعلّقة بإكمال المركبة والمركبة في طريقها إلى المحطة التالية.
نهاية اليوم	يَعُودُ السائق إلى المستودع.	وإذا عاد السائق إلى المستودع وشحن الشحنات التي تم استلامها خلال مساره، عليك أيضًا إنشاء كل حزمة وإغلاقها كمهمة تسليم لضمان صحة الفوترة. يمكنك إجراء ذلك من خلال تصميم المستودع مثل أي محطة تسليم أخرى. إذا لم يكن المستودع قيد الاستخدام كمحطة تسليم، يمكنك اختيار تصميم المستودع على أنّه محطة مجدوَلة. ومن خلال إعداد نموذج للمحطة، يمكن للسائقين الاطّلاع على مسار العودة إلى المستودع وإطلاعهم على الوقت المقدّر لوصولهم.

آلية عمل تعديلات الموقع الجغرافي

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

1. استخدام Driver SDK - Android، وiOS - وهو أبسط الخيارات.
2. استخدِم الرمز المخصّص: وهو مفيد إذا يتم ترحيل المواقع الجغرافية من خلال الخلفية أو في حال استخدام أجهزة أخرى غير Android أو iOS.

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

محطات توقّف المركبات ومواقع التسليم

محطة توقف المركبات هي المكان الذي تكمل فيه مركبة توصيل مهمة شحن أو بعض المهام الأخرى. وهي إما نقطة وصول مثل رصيف التحميل أو موقع مواجه للطريق.

موقع التسليم هو الموقع الذي يتم فيه تسليم الشحنة أو استلامها. قد يتطلب الوصول إلى موقع التسليم ومنه بعض المشي من محطة المركبة.

على سبيل المثال، عندما يقوم السائق بتسليم شحنة إلى متجر في مركز تسوق، تتوقف مركبة التوصيل في موقف سيارات المركز التجاري بالقرب من أقرب مدخل للمتجر. هذه هي محطة المركبة. ثم يسير السائق بعد ذلك من محطة المركبات إلى الموقع داخل المركز التجاري حيث يوجد المتجر. هذا هو موقع التسليم.

للحصول على أفضل تجربة لتتبع الشحن للمستخدمين، ضع في اعتبارك كيفية تعيين مهام الشحن لمحطات توقف المركبات وتذكر أنه يتم إبلاغ المستخدم بعدد محطات التوقف المتبقية لمهام الشحن لمساعدته في عرض التقدم المحرز في شحنه.

على سبيل المثال، إذا كان السائق يقوم بالعديد من عمليات التوصيل إلى مبنى مكتبي واحد، ففكر في تعيين جميع مهام التوصيل لمحطة مركبة واحدة. إذا تم تعيين كل مهمة تسليم إلى محطة مركبة خاصة بها، فستكون تجربة تتبع الشحن الخاصة بك أقل فائدة للمستخدمين لأن التتبع لا يتوفر إلا بمجرد أن تكون المركبة ضمن عدد محدود من مرات توقف المركبة قبل وجهتها. إن اكتمال العديد من محطات التوقف للمركبات في وقت قصير لا يمنح المستخدم الكثير من الوقت لاستخدامه لتتبع تقدم عملية التسليم.

استخدام حِزم تطوير البرامج (SDK) للأجهزة الجوّالة

قبل إجراء أي استدعاءات لحزمة Driver SDK، تأكَّد من إعدادها.

ضبط Delivery Driver API

قبل إعداد Delivery Driver API في Driver SDK، تأكَّد من إعداد حزمة تطوير البرامج (SDK) لميزة "التنقل". بعد ذلك، يُرجى إعداد Delivery Driver API كما هو موضَّح في المثال التالي:

static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";

NavigationApi.getNavigator(
   this, // Activity.
   new NavigatorListener() {
     @Override
     public void onNavigatorReady(Navigator navigator) {
       DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
         .setNavigator(navigator)
         .setProviderId(PROVIDER_ID)
         .setVehicleId(VEHICLE_ID)
         .setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
         .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
         .setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
         .setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
             Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
         .build));
     }
     @Override
     public void onError(int errorCode) {
       Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
     }
   });

ملاحظة: تحتوي Driver SDK على واجهات برمجة تطبيقات لفئات متعدّدة، بما في ذلك عمليات التسليم. لتقليل الحجم الكلي للبرنامج الثنائي، استخدِم ProGuard أو أداة تحسين أخرى لإزالة الرمز غير المستخدَم.

حالات الاستخدام

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

معرّفات الكيانات الفريدة

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

إنشاء مركبة

يمكنك إنشاء مركبة إما من Driver SDK أو من بيئة خادم باستخدام gRPC أو REST.

gRPC

لإنشاء مركبة جديدة، عليك الاتصال بخدمة CreateDeliveryVehicle مع Fleet Engine. استخدِم الكائن CreateDeliveryVehicleRequest لتحديد سمات مركبة التسليم الجديدة. تجدر الإشارة إلى أنّه يتم تجاهل أي قيمة محدّدة في الحقل Name وفقًا لإرشادات واجهة برمجة التطبيقات التي تخص أرقام التعريف المحدّدة من جانب المستخدم. يجب استخدام الحقل DeliveryVehicleId لضبط معرّف المركبة.

عند إنشاء DeliveryVehicle، يمكنك تحديد الحقول التالية بشكل اختياري:

• السمات
• LastLocation
• النوع

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

لإنشاء مركبة بدون ضبط أي حقول اختيارية، يمكنك ترك الحقل DeliveryVehicle بدون ضبط في CreateDeliveryVehicleRequest.

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لإنشاء مركبة:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    String parent = "providers/" + PROJECT_ID;
    DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
      .addAttributes(DeliveryVehicleAttribute.newBuilder()
        .setKey("route_number").setValue("1"))  // Opaque to the Fleet Engine
      .build();

    // Vehicle request
    CreateDeliveryVehicleRequest createVehicleRequest =
      CreateDeliveryVehicleRequest.newBuilder()  // No need for the header
          .setParent(parent)
          .setDeliveryVehicleId(VEHICLE_ID)     // Vehicle ID assigned by the Provider
          .setDeliveryVehicle(vehicle)
          .build();

    // Error handling
    // If Fleet Engine does not have vehicle with that ID and the credentials of the
    // requestor pass, the service creates the vehicle successfully.

    try {
      DeliveryVehicle createdVehicle =
        deliveryService.createDeliveryVehicle(createVehicleRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

راحة

لإنشاء مركبة من بيئة خادم، عليك إجراء طلب HTTP REST بـ CreateDeliveryVehicle:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>

<id> هو معرّف فريد لمركبة تسليم ضمن أسطولك.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يمثل نص POST الكيان DeliveryVehicle الذي سيتم إنشاؤه. يمكنك تحديد الحقول الاختيارية التالية:

• attributes
• lastLocation
• كتابة

مثال على الأمر curl:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
  "attributes": [{"key": "model", "value": "sedan"}],
  "lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM

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

لإنشاء مركبة بدون ضبط أي حقول، اترك نص طلب POST فارغًا. بعد ذلك، تستخرج المركبة التي تم إنشاؤها حديثًا رقم تعريفها من المعلَمة deliveryVehicleId في عنوان URL POST.

مثال على الأمر curl:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}"

إنشاء مهمة استلام شحنة

يمكنك إنشاء مهمة استلام الشحن إما من حزمة تطوير البرامج (SDK) للسائق أو من بيئة خادم باستخدام gRPC أو REST.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لإنشاء مهمة استلام شحن:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لإنشاء مهمة استلام شحن من بيئة خادم، عليك إجراء طلب HTTP REST بـ CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> هو معرّف فريد للمهمة. يجب ألا يكون رقم تتبع الشحنة. إذا لم يكن لديك معرفات مهام في نظامك، يمكنك إنشاء معرف فريد عالميًا (UUID).

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان Task:

• الحقول المطلوبة:

  الحقل	القيمة
  كتابة	Type.PICKUP
  state	State.OPEN
  trackingId	الرقم أو المعرّف المُستخدَم لتتبُّع شحنة
  plannedLocation	تمثّل هذه السمة الموقع الجغرافي الذي سيتم إنجاز المهمة فيه، وفي هذه الحالة موقع استلام الشحن.
  taskDuration	الوقت المتوقَّع بالثواني الذي يستغرقه لاستلام الشحنة في الموقع الجغرافي للاستلام.

• الحقول الاختيارية:

  الحقل	القيمة
  targetTimeWindow	الفترة الزمنية التي يجب إكمال المهمة خلالها. ولا يؤثّر ذلك في سلوك التوجيه.
  attributes	قائمة بسمات المهام المخصّصة يجب أن يكون لكل سمة مفتاح فريد.

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

مثال على الأمر curl:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "PICKUP",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

إنشاء مهمة تسليم شحن

يمكنك إنشاء مهمة تسليم شحن إما من Driver SDK أو من بيئة خادم باستخدام gRPC أو REST.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لإنشاء مهمة تسليم شحن:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لإنشاء مهمة تسليم شحن من بيئة خادم باستخدام gRPC أو REST، أجرِ استدعاء HTTP REST إلى CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> هو معرّف فريد للمهمة. يجب ألا يكون رقم تتبع الشحنة. إذا لم يكن لديك معرفات مهام في نظامك، يمكنك إنشاء معرف فريد عالميًا (UUID).

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان Task:

• الحقول المطلوبة:

  الحقل	القيمة
  كتابة	Type.DELIVERY
  state	State.OPEN
  trackingId	الرقم أو المعرّف المُستخدَم لتتبُّع شحنة
  plannedLocation	تمثّل هذه السمة الموقع الجغرافي الذي سيتم إنجاز المهمة فيه، وفي هذه الحالة موقع التسليم لهذه الشحنة.
  taskDuration	الوقت المتوقَّع بالثواني الذي يستغرقه تسليم الشحنة في موقع التسليم.

• الحقول الاختيارية:

  الحقل	القيمة
  targetTimeWindow	الفترة الزمنية التي يجب إكمال المهمة خلالها. ولا يؤثّر ذلك في سلوك التوجيه.
  attributes	قائمة بسمات المهام المخصّصة يجب أن يكون لكل سمة مفتاح فريد.

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

مثال على الأمر curl:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "DELIVERY",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

إنشاء مهام مجمّعة

يمكنك إنشاء مجموعة من المهام من بيئة خادم باستخدام gRPC أو REST.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لإنشاء مهمتين، إحداهما للتسليم والأخرى للاستلام في الموقع نفسه:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Delivery Task settings
Task deliveryTask = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("delivery-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8312508")  // Task ID assigned by the Provider
      .setTask(deliveryTask)      // Initial state
      .build();

// Pickup Task settings
Task pickupTask = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("pickup-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(pickupTask)        // Initial state
      .build();

// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;

// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
  BatchCreateTasksRequest.newBuilder()
      .setParent(parent)
      .addRequests(createDeliveryTaskRequest)
      .addRequests(createPickupTaskRequest)
      .build();

// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.

try {
  BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
    batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لإنشاء مهمة تسليم واستلام من بيئة الخادم، عليك إجراء طلب HTTP REST إلى BatchCreateTasks:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة حامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان BatchCreateTasksRequest:

• الحقول المطلوبة:

  الحقل	القيمة
  طلبات	مصفوفة<CreateTasksRequest>

• الحقول الاختيارية:

  الحقل	القيمة
  header	"DeliveryRequestHeader"

يجب أن يجتاز كل عنصر CreateTasksRequest في requests قواعد التحقّق نفسها في الطلب CreateTask، باستثناء أنّ الحقلَين parent وheader اختياريان. وفي حال ضبطها، يجب أن تكون مطابقة للحقول الخاصة بها في أعلى قيمة في BatchCreateTasksRequest. يمكنك الاطلاع على إنشاء مهمة استلام الشحن وإنشاء مهمة تسليم الشحن للحصول على قواعد تحقق محددة لكل منها.

للمزيد من المعلومات، يُرجى الاطّلاع على المستندات المرجعية لواجهة برمجة التطبيقات الخاصة بـ BatchCreateTasks (gRPC وREST).

مثال على الأمر curl:

# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "requests" : [
    {
      "taskId": "${DELIVERY_TASK_ID}",
      "task" : {
        "type": "DELIVERY",
        "state": "OPEN",
        "trackingId": "${DELIVERY_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    },
    {
      "taskId": "${PICKUP_TASK_ID}",
      "task" : {
        "type": "PICKUP",
        "state": "OPEN",
        "trackingId": "${PICKUP_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    }
  ]
}
EOM

عدم التوفّر المجدوَل

يمكنك إنشاء مهمة تشير إلى عدم التوفّر (على سبيل المثال، بالنسبة إلى أوقات توقُّف السائق أو إعادة تعبئة المركبات) إمّا من حزمة تطوير البرامج (SDK) للسائق، أو من بيئة خادم باستخدام gRPC أو REST. يجب ألا تتضمن المهمة المجدوَلة لعدم التوفّر رقم تعريف تتبُّع. يمكنك إدخال موقع جغرافي بشكل اختياري.

gRPC

يوضّح المثال التالي كيفية استخدام مكتبة Java gRPC لإنشاء مهمة عدم التوفّر:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String parent = "providers/" + PROJECT_ID;
    Task task = Task.newBuilder()
      .setType(Task.Type.UNAVAILABLE)
      .setState(Task.State.OPEN)
      .setTaskDuration(
        Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
      .build();

    // Task request
    CreateTaskRequest createTaskRequest =
      CreateTaskRequest.newBuilder()  // No need for the header
          .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
          .setTaskId("task-8241890")  // Task ID assigned by the Provider
          .setTask(task)              // Initial state
          .build();

    // Error handling
    // If Fleet Engine does not have task with that ID and the credentials of the
    // requestor pass, the service creates the task successfully.

    try {
      Task createdTask = deliveryService.createTask(createTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

راحة

لإنشاء مهمة عدم التوفّر من بيئة الخادم، عليك إجراء طلب HTTP REST بـ CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> هو معرّف فريد للمهمة. إذا لم يكن لديك معرِّفات مهام في نظامك، يمكنك إنشاء معرِّف فريد عالميًا (UUID).

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان Task:

• الحقول المطلوبة:

  الحقل	القيمة
  كتابة	Type.UNAVAILABLE
  state	State.OPEN
  taskDuration	مدة الفاصل بالثواني.

• الحقول الاختيارية:

  الحقل	القيمة
  plannedLocation	تمثّل هذه السمة موقع الفاصل إذا كان يجب تصويره في مكان معيّن.

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

مثال على الأمر curl:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "UNAVAILABLE",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "300s"
    }
    EOM

المحطات المجدوَلة

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

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لإنشاء مهمة إيقاف مجدولة:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.SCHEDULED_STOP)
  .setState(Task.State.OPEN)
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTrip(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لإنشاء مهمة إيقاف مجدولة من بيئة الخادم، عليك إجراء طلب HTTP REST بـ CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> هو معرّف فريد للمهمة. إذا لم يكن لديك معرفات مهام في نظامك، يمكنك إنشاء معرف فريد عالميًا (UUID).

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان Task:

• الحقول المطلوبة:

  الحقل	القيمة
  كتابة	Type.SCHEDULED_STOP
  state	State.OPEN
  plannedLocation	موقع المحطة.
  taskDuration	المدة المتوقعة للمحطة بالثواني.

• الحقول الاختيارية:

  • لا ينطبق

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

مثال على الأمر curl:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "SCHEDULED_STOP",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "600s"
    }
    EOM

ضبط الفترة الزمنية المستهدَفة

نافذة الوقت المستهدَف هي TimeWindow التي يجب إكمال المهمة خلالها. على سبيل المثال، إذا أبلغت مستلمي التسليم بفترة زمنية للتسليم، يمكنك استخدام النافذة الزمنية المستهدفة للمهمة لالتقاط هذه الفترة الزمنية وإنشاء تنبيهات أو تحليل أداء ما بعد الرحلة باستخدام الحقل.

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

gRPC

يوضِّح المثال التالي كيفية استخدام مكتبة Java gRPC لضبط نافذة لوقت المهمة:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String TASK_ID = "task-8241890";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
    Task task = Task.newBuilder()
      .setName(taskName)
      .setTargetTimeWindow(
        TimeWindow.newBuilder()
          .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
          .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
      .build();

    // Task request
    UpdateTaskRequest updateTaskRequest =
      UpdateTaskRequest.newBuilder()  // No need for the header
          .setTask(task)
          .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
          .build();

    try {
      Task updatedTask = deliveryService.updateTask(updateTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case NOT_FOUND:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

راحة

لضبط نافذة وقت مهمة باستخدام HTTP، يمكنك استدعاء الدالة UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`

<id> هو معرّف فريد للمهمة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان Task:

• الحقول المطلوبة:

  الحقل	القيمة
  targetTimeWindow	الفترة الزمنية التي يجب إكمال المهمة خلالها. لا يؤثر هذا الإعداد في سلوك التوجيه.

• الحقول الاختيارية:

  • لا ينطبق

ويتم تجاهل جميع الحقول الأخرى في العنصر أثناء عملية التعديل.

مثال على الأمر curl:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

ضبط إعدادات إذن الوصول إلى تتبُّع المهام

يمكن التحكّم في مستوى ظهور البيانات في مكتبة "تتبُّع الشحن" والبيانات التي يتم عرضها من خلال طلب اتصال إلى GetTaskTrackingInfo على أساس كل مهمة من خلال ضبط TaskTrackingViewConfig على المهمة. يمكنك الاطّلاع على مهام المركبات النشطة للحصول على مزيد من المعلومات. يمكن القيام بذلك عند إنشاء المهمة أو تحديثها. في ما يلي مثال على تعديل المهمة باستخدام هذه الإعدادات:

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لضبط إعداد عرض تتبع المهام:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}

راحة

لضبط نافذة إعداد عرض تتبُّع المهام باستخدام HTTP، يمكنك استدعاء الدالة UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`

<id> هو معرّف فريد للمهمة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان Task:

• الحقول المطلوبة:

  الحقل	القيمة
  taskTrackingViewConfig	يشير ذلك المصطلح إلى عملية إعداد تتبُّع المهام التي تحدِّد عناصر البيانات التي ستكون مرئية للمستخدمين النهائيين وتحت أي ظروف.

• الحقول الاختيارية:

  • لا ينطبق

ويتم تجاهل جميع الحقول الأخرى في العنصر أثناء عملية التعديل.

مثال على الأمر curl:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

تعيين المهام لمركبة

يمكنك تعيين المهام لمركبة توصيل عن طريق تحديث ترتيب المهام للمركبة. يتم تحديد ترتيب المهام للمركبة من خلال قائمة محطات توقف المركبة لمركبة التسليم، ويمكنك تعيين مهمة واحدة أو أكثر لكل محطة مركبة. للحصول على التفاصيل، راجِع تعديل ترتيب المهام.

لتغيير شحنة من مركبة إلى أخرى، يجب إغلاق المهمة الأصلية ثم إعادة إنشائها قبل تعيين المركبة الجديدة لها. إذا قمت بتحديث ترتيب المهمة لمهمة تم تعيينها بالفعل لمركبة مختلفة، فستحصل على خطأ.

تعديل ترتيب المهام

يمكنك تعديل ترتيب تنفيذ المهام المخصّصة لمركبة من حزمة تطوير البرامج (SDK) للسائقين أو بيئة الخادم. لا تستخدم كلتا الطريقتين لتجنب شروط العِرق والحفاظ على مصدر واحد للحقيقة.

عند تعديل ترتيب المهام لمركبة، يتم أيضًا إجراء ما يلي:

• يعيّن المهام الجديدة في المركبة.
• يغلق أي مهام تم تعيينها سابقًا للمركبة، ولكنها ليست في الترتيب المحدث.

لتغيير شحنة من مركبة إلى أخرى، عليك إغلاق المهمة الأصلية ثم إعادة إنشائها قبل تعيين المركبة الجديدة لها. إذا قمت بتحديث ترتيب المهمة لمهمة تم تعيينها بالفعل لمركبة مختلفة، فستحصل على خطأ.

يمكنك تعديل ترتيب المهام في أي وقت.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لتحديث ترتيب المهام للمركبة:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.NEW)))
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لتعديل ترتيب المهام للمركبة من بيئة الخادم، عليك إجراء طلب HTTP REST بـ UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> هو معرّف فريد لمركبة تسليم في أسطولك تنوي تعديل ترتيب المهام له. إنه المعرف الذي حددته عند إنشاء المركبة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان DeliveryVehicle:

• الحقول المطلوبة:

  الحقل	القيمة
  remainingVehicleJourneySegments	قائمة بأجزاء رحلة الطيران للمهام بالترتيب المطلوب تنفيذها. يتم تنفيذ المهمة الأولى في القائمة أولاً.
  LastVehicleJourneyClips[i].stop	تمثّل هذه السمة محطة المهمة i في القائمة.
  متبقيةVehicleJourneysegments[i].stop.plannedLocation	الموقع المخطط للمحطة.
  متبقيةVehicleJourneyClips[i].stop.tasks	قائمة المهام التي سيتم أداؤها عند محطة المركبة هذه.
  remainingVehicleJourneySegments[i].stop.state	State.NEW

• الحقول الاختيارية:

  • لا ينطبق

ويتم تجاهل جميع الحقول الأخرى في العنصر أثناء عملية التعديل.

مثال على الأمر curl:

ملاحظة: يستبدل هذا الأمر أي remainingVehicleJourneySegments سبق أن تم ضبطها على مركبة التسليم.

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

المركبة في طريقها إلى المحطة التالية

يجب إرسال إشعار إلى Fleet Engine عند انطلاق مركبة من محطة توقّف أو بدء التنقّل. يمكنك إعلام Fleet Engine إما من Driver SDK، أو من بيئة خادم باستخدام gRPC أو REST. لا تستخدم كلتا الطريقتين لتجنب شروط العِرق والحفاظ على مصدر واحد للحقيقة.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لإشعار Fleet Engine بأن هناك مركبة في طريقها إلى محطتها التالية.

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String VEHICLE_ID = "vehicle-8241890";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
        // Next stop marked as ENROUTE
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.7749)
                       .setLongitude(122.4194)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
               .setState(VehicleStop.State.ENROUTE)))
        // All other stops marked as NEW
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.3382)
                       .setLongitude(121.8863)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
               .setState(VehicleStop.State.NEW)))
        .build();

    // DeliveryVehicle request
    UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
      UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
          .setName(vehicleName)
          .setDeliveryVehicle(deliveryVehicle)
          .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
          .build();

    try {
      DeliveryVehicle updatedDeliveryVehicle =
          deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case NOT_FOUND:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

راحة

لإعلام Fleet Engine بأنّ المركبة في طريقها إلى محطتها التالية من بيئة الخادم، يمكنك إجراء طلب HTTP REST بـ UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> هو معرّف فريد لمركبة التسليم في أسطولك والتي تنوي تعديل ترتيب المهام لها. إنه المعرف الذي حددته عند إنشاء المركبة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان DeliveryVehicle:

• الحقل المطلوب:

  الحقل	القيمة
  remainingVehicleJourneySegments	قائمة بمحطات توقّف المركبات المتبقية التي تحمل علامة State.NEW. يجب وضع علامة State.ENROUTE على المحطة الأولى في القائمة.

• الحقول الاختيارية:

  • لا ينطبق

ويتم تجاهل جميع الحقول الأخرى في العنصر.

مثال على الأمر curl:

ملاحظة: يؤدي هذا الأمر إلى استبدال أي remainingVehicleJourneySegments سبق أن تم ضبطها في مركبة التسليم.

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ENROUTE",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

تعديل الموقع الجغرافي للمركبة

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

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لتعديل الموقع الجغرافي للمركبة في Fleet Engine:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
    .setLastLocation(DeliveryVehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(myDeliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("last_location"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لتعديل الموقع الجغرافي للمركبة في Fleet Engine باستخدام HTTP REST، اتّصِل بالرقم UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`

<id> هو معرّف فريد لمركبة التسليم في أسطولك أو تريد تعديل الموقع الجغرافي له. إنه المعرف الذي حددته عند إنشاء المركبة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان DeliveryVehicle:

• الحقل المطلوب:

  الحقل	القيمة
  lastLocation.supplementalLocation	الموقع الجغرافي للمركبة
  lastLocation.supplementalLocationTime	آخر طابع زمني معروف للمركبة كانت في هذا الموقع الجغرافي.
  lastLocation.supplementalLocationSensor	يجب تعبئة هذا الحقل بـ CUSTOMER_SUPPLIED_LOCATION.

• الحقول الاختيارية:

  الحقل	القيمة
  lastLocation.supplementalLocationAccuracy	دقة الموقع الجغرافي الذي تم تقديمه، بالمتر

مثال على الأمر curl:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
  }
}
EOM

مركبة تصل إلى محطة

يجب إرسال إشعار إلى Fleet Engine عند وصول مركبة إلى محطة توقّف. يمكنك إرسال إشعار إلى Fleet Engine إما من حزمة تطوير البرامج (SDK) للسائق، أو من بيئة خادم تستخدم gRPC أو REST. لا تستخدم كلتا الطريقتين لتجنب شروط العِرق والحفاظ على مصدر واحد للحقيقة.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لإشعار Fleet Engine بأن مركبة وصلت إلى محطة:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Marking the arrival at stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لإعلام Fleet Engine بوصول مركبة إلى محطة توقف من بيئة الخادم، يمكنك إجراء طلب HTTP REST بـ UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> هو معرّف فريد لمركبة التسليم في أسطولك والتي تنوي تعديل ترتيب المهام لها. إنه المعرف الذي حددته عند إنشاء المركبة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان DeliveryVehicle:

• الحقول المطلوبة:

  الحقل	القيمة
  remainingVehicleJourneySegments	المحطة التي وصلت إليها وقد تم ضبط حالتها على State.ARRIVED، متبوعة بقائمة من محطات التوقف للمركبات المتبقية مع وضع علامة State.NEW على حالاتها.

• الحقول الاختيارية:

  • لا ينطبق

ويتم تجاهل جميع الحقول الأخرى في العنصر أثناء عملية التعديل.

مثال على الأمر curl:

ملاحظة: يستبدل هذا الأمر أي remainingVehicleJourneySegments سبق أن تم ضبطها على مركبة التسليم.

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ARRIVED",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

مركبة تكمل محطة توقّف

يجب إرسال إشعار إلى أسطول المركبات عند اكتمال توقّف مركبة. يؤدي هذا إلى تعيين جميع المهام المرتبطة بالتوقف على حالة إغلاق. يمكنك إعلام Fleet Engine إما من حزمة SDKr، أو من بيئة خادم باستخدام gRPC أو REST. ولا تستخدم كلتا الطريقتين لتجنب شروط العِرق وللحفاظ على مصدر واحد للحقيقة.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لإشعار Fleet Engine بأن هناك مركبة قد اكتملت.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // This stop has been completed and is commented out to indicate it
    // should be removed from the list of vehicle journey segments.
    // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
    //    .setStop(VehicleStop.newBuilder()
    //        .setPlannedLocation(LocationInfo.newBuilder()
    //            .setPoint(LatLng.newBuilder()
    //                .setLatitude(37.7749)
    //                .setLongitude(122.4194)))
    //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
    //        .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    // The next stop could be marked as ENROUTE if the vehicle has begun
    // its journey to the next stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // no need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لإعلام Fleet Engine باكتمال عملية الإيقاف في بيئة الخادم، يمكنك إجراء طلب HTTP REST إلى UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`

<id> هو معرّف فريد لمركبة التسليم في أسطولك والتي تنوي تعديل ترتيب المهام لها. إنه المعرف الذي حددته عند إنشاء المركبة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان DeliveryVehicle:

• الحقول المطلوبة:

  الحقل	القيمة
  remaining_vehicle_journey_segments	من المفترض ألّا تظهر المحطة التي أكملتها في قائمة محطات المركبات المتبقية.

• الحقول الاختيارية:

  • لا ينطبق

ويتم تجاهل جميع الحقول الأخرى في العنصر أثناء عملية التعديل.

مثال على الأمر curl:

ملاحظة: يستبدل هذا الأمر أي remainingVehicleJourneySegments سبق أن تم ضبطها على مركبة التسليم.

    # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
    # environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "remainingVehicleJourneySegments": [
        {
          "stop": {
            "state": "NEW",
            "plannedLocation": {
              "point": {
                "latitude": 37.3382,
                "longitude": 121.8863
              }
            },
            "tasks": [
              {
                "taskId": "${TASK2_ID}"
              }
            ]
          }
        }
      ]
    }
    EOM

تعديل مهمة

معظم حقول المهام غير قابلة للتغيير. ومع ذلك، يمكنك تعديل الحالة ونتائج المهمة ووقت نتيجة المهمة وموقع نتيجة المهمة والسمات من خلال تحديث كيان المهمة مباشرةً. على سبيل المثال، في الحالات التي لم يتم فيها تعيين مهمة لمركبة، يمكنك إغلاق المهمة عن طريق تحديث الحالة مباشرة.

gRPC

هذا مثال على تعديل مهمة من خلال تكلفة النقرة الإجمالية (gRPC).

راحة

هذا مثال على تعديل مهمة من خلال REST.

إغلاق مهمة

لإغلاق مهمة تم تكليفك بها، يمكنك إما إبلاغ Fleet Engine بأن المركبة قد اكتملت في المكان الذي تحدث فيه المهمة أو أزِلها من قائمة محطات التوقف. للقيام بذلك، يمكنك إعداد قائمة بمحطات المركبة المتبقية كما هو الحال عند تعديل ترتيب المهام لمركبة.

إذا لم يتم تعيين مركبة لمهمة بعد ويجب إغلاقها، فقم بتحديث المهمة إلى حالة إغلاق. ومع ذلك، لا يمكنك إعادة فتح مهمة مغلقة.

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

gRPC

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setState(Task.State.CLOSED) // You can only directly CLOSE a
  .build();                    // task that is NOT assigned to a vehicle.

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("state"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لوضع علامة على مهمة تشير إلى أنها مغلقة من بيئة خادم، عليك إجراء طلب HTTP REST لـ UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`

<id> هو معرّف فريد للمهمة.

يجب أن يحتوي عنوان الطلب على حقل تفويض يتضمّن القيمة حامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب تضمين كيان Task في نص الطلب:

• الحقول المطلوبة:

  الحقل	القيمة
  state	State.CLOSED

• الحقول الاختيارية:

  الحقل	القيمة
  taskOutcome	النتيجة.SUCCEEDED أو النتيجة.تعذّر
  taskOutcomeTime	الوقت الذي تم فيه إنجاز المهمة
  taskOutcomeLocation	الموقع الذي تم فيه إنجاز المهمة يضبط Fleet Engine هذا الخيار تلقائيًا على آخر موقع للمركبة ما لم يتجاهله موفّر الخدمة يدويًا.

ويتم تجاهل جميع الحقول الأخرى في العنصر أثناء عملية التعديل.

مثال على الأمر curl:

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "state": "CLOSED",
      "taskOutcome": "SUCCEEDED",
      "taskOutcomeTime": "$(date -u --iso-8601=seconds)"
    }
    EOM

حدد نتيجة المهمة وموقع النتيجة

لا يشير إغلاق المهمة إلى النجاح أو الفشل، بل يشير إلى أن المهمة لم تعد قيد التقدم. بالنسبة لتتبع الأسطول، من المهم الإشارة إلى النتيجة الفعلية لمهمة ما حتى يمكن عرض نتيجة التسليم وهناك فوترة مناسبة للخدمات. وبعد الضبط، لا يمكنك تغيير نتيجة المهمة. ومع ذلك، يمكنك تعديل وقت نتيجة المهمة وموقع نتيجة المهمة بعد تعيينهما.

يمكن ضبط نتيجتها للمهام التي تكون في الحالة "مغلقة" على SUCCEEDED أو "تعذّر". لا تفرض Fleet Engine رسومًا إلا على مهام التسليم التي تكون بالحالة SUCCEEDED.

عند وضع علامة على نتيجة مهمة، يملأ Fleet Engine تلقائيًا موقع نتيجة المهمة بآخر موقع معروف للمركبة. يمكنك التغلب على هذا السلوك.

gRPC

لديك الخيار لتحديد موقع نتيجة المهمة عند تحديد النتيجة. يؤدي تحديد هذا الموقع إلى منع Fleet Engine من ضبطه على الموقع التلقائي لآخر موقع للمركبة. يمكنك أيضًا استبدال موقع نتيجة المهمة الذي تم ضبطه Fleet Engine في وقت لاحق. لا يستبدل Fleet Engine أبدًا موقع نتائج المهمة الذي قدمته. لا يمكنك تعيين موقع نتيجة مهمة لمهمة لم يتم تحديد نتيجة مهمة لها. يمكنك تحديد كل من نتيجة المهمة وموقع نتيجة المهمة في نفس الطلب.

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC لضبط نتيجة مهمة على SUCCEEDED وتعيين الموقع الذي تم فيه إنجاز المهمة:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskOutcome(TaskOutcome.SUCCEEDED)
  .setTaskOutcomeTime(now())
  .setTaskOutcomeLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لوضع علامة اكتمال على مهمة من بيئة الخادم، يمكنك إجراء استدعاء HTTP REST لـ UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`

<id> هو معرّف فريد للمهمة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يحتوي نص الطلب على الكيان Task:

• الحقول المطلوبة:

  الحقل	القيمة
  taskOutcome	النتيجة.SUCCEEDED أو النتيجة.تعذّر

• الحقول الاختيارية:

  الحقل	القيمة
  taskOutcomeLocation	الموقع الذي تم فيه إنجاز المهمة وفي حال تم ترك السياسة بدون ضبط، يضبط Fleet Engine تلقائيًا هذا الموقع على آخر موقع للمركبة.
  taskOutcomeTime	الطابع الزمني لوقت اكتمال المهمة

ويتم تجاهل جميع الحقول الأخرى في العنصر أثناء عملية التعديل.

مثال على الأمر curl:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)",
  "taskOutcomeLocation": {
    "point": {
      "latitude": -6.195139,
      "longitude": 106.820826
    }
  }
}
EOM

تغيير مسار شحنة

بمجرد إنشاء مهمة الشحن، لا يمكن تغيير الموقع المخطط له. لتغيير مسار الشحنة، أغلق مهمة الشحن دون تحديد نتيجة، ثم أنشئ مهمة جديدة بالموقع المخطط له المحدث. بعد إنشاء المهمة الجديدة، قم بتعيين المهمة إلى نفس المركبة. لمزيد من المعلومات، يُرجى الاطّلاع على إغلاق مهمة الشحن وإسناد المهمة.

استخدام مركبات التغذية ومركبات التوصيل

إذا كنت تستخدم مركبات التغذية لنقل الشحنات إلى مركبات التسليم على مدار اليوم، فضع نموذج لنقل الشحنات كمهمة توقف مجدولة لمركبة التسليم. لضمان تتبع الموقع بدقة، قم بتعيين مهمة تسليم شحن لشحنة تم نقلها فقط بعد تحميلها على مركبة التسليم. لمزيد من المعلومات، راجع المحطة المجدولة.

حالة شحن المتجر والمعلومات الوصفية الأخرى

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

لمزيد من المعلومات، راجع مسار المهمة.

البحث عن مركبة

يمكنك البحث عن مركبة من خلال Driver SDK أو من بيئة خادم باستخدام gRPC أو REST.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC للبحث عن مركبة:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder()  // No need for the header
    .setName(name)
    .build();

try {
  DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

للبحث عن مركبة من بيئة خادم، يمكنك إجراء استدعاء HTTP REST لـ GetVehicle:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`

<id> هو معرّف فريد للمهمة.

<vehicleId> هو رقم تعريف المركبة المطلوب البحث عنها.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يكون نص الطلب فارغًا.

إذا تمت عملية البحث بنجاح، يحتوي نص الاستجابة على كيان مركبة.

مثال على الأمر curl:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"

البحث عن مهمة

يمكنك البحث عن مهمة من بيئة الخادم باستخدام gRPC أو REST. لا توفّر حزمة Driver SDK إمكانية البحث عن مهمة.

gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC للبحث عن مهمة:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
    .setName(taskName)
    .build();

try {
  Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

للبحث عن مهمة من بيئة الخادم، يمكنك إجراء استدعاء HTTP REST لـ GetTask:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`

<id> هو معرّف فريد للمهمة.

<taskId> هي معرّف المهمة المطلوب البحث عنها.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

يجب أن يكون نص الطلب فارغًا.

إذا تمت عملية البحث بنجاح، سيحتوي نص الاستجابة على عنصر مهم.

مثال على الأمر curl:

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

البحث عن معلومات مهمة الشحن حسب رقم تعريف التتبع الخاص بها

يمكنك البحث عن معلومات مهام مجموعة الأجهزة بالطرق التالية، لكل منها غرض منفصل:

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

يناقش هذا القسم البحث عن معلومات المهمة من خلال رقم تعريف التتبع. إذا كنت تريد البحث عن مهمة حسب معرّف المهمة، انتقِل إلى البحث عن مهمة.

للبحث عن المعلومات من خلال رقم تعريف تتبُّع، يمكنك استخدام أيّ مما يلي:

• عمليات البحث باستخدام Java باستخدام gRPC
• عمليات البحث باستخدام HTTP

متطلبات البحث

• تلتزم معلومات الشحن التي يقدّمها رقم تعريف التتبّع بقواعد مستوى الرؤية المذكورة في التحكّم في إمكانية رؤية المواقع الجغرافية التي يتم تتبّعها.

• استخدِم Fleet Engine للبحث عن معلومات الشحن باستخدام رقم تعريف التتبّع. ولا توفِّر "حزمة تطوير البرامج (SDK) للسائقين" عمليات البحث عن المعلومات باستخدام رقم تعريف التتبّع. ولإجراء ذلك باستخدام Fleet Engine، يمكنك استخدام إما بيئة خادم أو متصفح.

• استخدِم أضيق رمز مميّز ممكن للحدّ من المخاطر الأمنية. على سبيل المثال، إذا كنت تستخدم الرمز المميّز للتسليم للمستهلكين، لن تعرض أي طلبات من Fleet Engine Deliveries API سوى المعلومات ذات الصلة بهذا المستخدم النهائي، مثل جهة الشحن أو المستلِم. ويتم تنقيح جميع المعلومات الأخرى الواردة في الردود. لمزيد من المعلومات حول الرموز المميّزة، يمكنك الاطّلاع على إنشاء رمز JSON المميّز للويب (JWT) للتفويض.

عمليات البحث باستخدام Java باستخدام gRPC

يوضح المثال التالي كيفية استخدام مكتبة Java gRPC للبحث عن معلومات حول مهمة شحن من خلال رقم تعريف التتبع.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

عمليات البحث باستخدام HTTP

للبحث عن مهمة شحن من متصفّح، عليك إجراء طلب HTTP REST للعبارة GetTaskTrackingInfo:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`

<tracking_id> هو رقم تعريف التتبّع المرتبط بالمهمة.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة حامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

إذا تمت عملية البحث بنجاح، يحتوي نص الاستجابة على العنصر taskTrackingInfo.

مثال على الأمر curl:

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

إدراج المهام

يمكنك إدراج المهام من بيئة خادم أو متصفّح. لا تتوافق "حزمة تطوير البرامج (SDK) للسائق" مع مهام إدراج البيانات.

يتطلّب عرض المهام وصولاً واسع النطاق إلى المهام. مهام قائمة البيانات مخصصة فقط للمستخدمين الموثوق بهم. استخدام "قارئ مجموعة التسليم" أو "الرموز المميّزة لمصادقة المستخدم المميّز للتسليم" عند إجراء طلبات المهام ضمن القائمة

تم إخفاء الحقول التالية في المهام المدرَجة:

• VehicleStop.planned_location
• VehicleStop.state
• VehicleStop.TaskInfo.taskId

يمكن فلترة المهام المدرَجة حسب معظم خصائص المهام. لمعرفة بنية طلب البحث للفلتر، راجِع AIP-160. تعرض القائمة التالية خصائص المهام الصالحة التي يمكنك استخدامها للتصفية:

• attributes
• delivery_vehicle_id
• state
• planned_location
• task_duration
• task_outcome
• task_outcome_location
• task_outcome_location_source
• task_outcome_time
• tracking_id
• كتابة

استخدِم تنسيقات الحقول التالية استنادًا إلى اقتراحات تحسين واجهة Google API:

نوع الحقل	التنسيق	مثال
الطابع الزمني	RFC-3339	task_outcome_time = 2022-03-01T11:30:00-08:00
المدة	عدد الثواني متبوعًا بـ s	task_duration = 120s
التعداد	سلسلة	state = CLOSED AND type = PICKUP
الموقع الجغرافي	point.latitude وpoint.longitude	planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

راجِع AIP-160 للحصول على قائمة كاملة بعوامل تشغيل طلبات البحث للفلاتر.

إذا لم يتم تحديد أي طلب فلتر، سيتم إدراج جميع المهام.

تُقسَّم قوائم المهام على صفحات. يمكن تحديد حجم الصفحة في طلبات مهام القائمة. إذا تم تحديد حجم الصفحة، لن يكون عدد المهام المعروضة أكبر من حجم الصفحة المحدّد. إذا لم يكن هناك حجم صفحة موجود، فيتم استخدام افتراضي معقول. إذا تجاوز حجم الصفحة المطلوب قيمة قصوى داخلية، سيتم استخدام الحد الأقصى الداخلي.

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

ملاحظة: يمكن أن تؤدي فلترة سمات المهام إلى زيادة كبيرة في وقت استجابة الاسترجاع، لذا يجب استخدامها بحذر.

gRPC

يوضّح المثال التالي كيفية استخدام مكتبة Java gRPC لإدراج المهام لـdeliveryVehicleId وسمة مهمة. ويمكن أن يكون الرد الناجح فارغًا. تشير الاستجابة الفارغة إلى عدم ربط أي من "مهام Google" بـdeliveryVehicleId المقدَّم.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
    .build();

try {
  ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

راحة

لإدراج المهام من متصفّح، عليك إجراء استدعاء HTTP REST لـ ListTasks:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`

لتطبيق فلتر على المهام المدرَجة، أدرِج معلَمة عنوان URL "فلتر" مع إدخال طلب بحث يتضمّن أحرف إلغاء لعنوان URL.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

إذا تم البحث بنجاح، يحتوي نص الاستجابة على بيانات بالبنية التالية:

    // JSON representation
    {
      "tasks": [
        {
          object (Task)
        }
      ],
      "nextPageToken": string,
      "totalSize": integer
    }

ويمكن أن تكون الإجابة الناجحة فارغة. تشير الإجابة الفارغة إلى أنه لم يتم العثور على مهام تلبي معايير التصفية المحددة.

مثال على الأمر curl:

    # Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

إدراج مركبات التسليم

يمكنك إدراج مركبات التسليم من بيئة خادم أو متصفّح. لا تتوافق "حزمة تطوير البرامج (SDK) للسائق" مع عرض بيانات مركبات التسليم.

تطلب مركبات التسليم المدرجة في القائمة وصولاً واسع النطاق إلى مركبات التسليم وهي مخصصة فقط للمستخدمين الموثوق بهم. استخدام "قارئ مجموعة التسليم" أو "الرموز المميزة لمصادقة المستخدم المتميز للتسليم" عند تقديم طلبات مركبات تسليم القائمة.

تم إخفاء الحقول التالية من مركبات التوصيل المُدرَجة بسبب تأثيرها في حجم الاستجابة:

• CurrentRouteSegment
• RemainingVehicleJourneySegments

يمكنك فلترة مركبات التسليم المُدرَجة حسب الموقع الإلكتروني الخاص بها على attributes. على سبيل المثال، للاستعلام عن سمة مع المفتاح my_key والقيمة my_value، استخدم attributes.my_key = my_value. للاستعلام عن سمات متعددة، قم بدمج الاستعلامات باستخدام عاملي التشغيل AND وOR المنطقيين كما في attributes.key1 = value1 AND attributes.key2 = value2. راجع AIP-160 للحصول على وصف كامل لبنية طلب بحث الفلتر.

يمكنك فلترة مركبات التسليم المُدرَجة حسب الموقع الجغرافي باستخدام معلَمة الطلب viewport. تحدِّد معلَمة طلب viewport إطار العرض باستخدام إحداثيَين حدود: زوجان من إحداثيات high (شمال شرق) وlow (جنوب غرب) لخط العرض وخط الطول. يتم رفض الطلبات إذا كانت تحتوي على خط عرض عالٍ أقل جغرافيًا من خط العرض المنخفض.

ملاحظة: في حال عدم تحديد إطار عرض أو طلب بحث عن فلتر، سيشمل الردّ جميع مركبات التسليم.

تكون قوائم مركبات التسليم مقسّمة على صفحات بشكل تلقائي باستخدام حجم صفحة معقول. وإذا حدّدت حجم الصفحة، لن يعرض الطلب سوى عدد المركبات المحدّد ضمن الحدّ الأقصى أو أقل. إذا تجاوز حجم الصفحة المطلوب قيمة قصوى داخلية، يتم استخدام الحد الأقصى الداخلي. يبلغ الحجم التلقائي والحد الأقصى للصفحات كلاهما 100 مركبة.

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

gRPC

يوضّح المثال التالي كيفية استخدام مكتبة Java gRPC لإدراج مركبات التسليم في منطقة معيّنة باستخدام سمة معيّنة. قد تكون الإجابة الناجحة فارغة. وعندما يحدث ذلك، يعني ذلك عدم وجود مركبات ذات السمة المحددة في إطار العرض المحدد.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
  ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setViewport(
            Viewport.newBuilder()
              .setHigh(LatLng.newBuilder()
                  .setLatitude(37.45)
                  .setLongitude(-122.06)
                  .build())
              .setLow(LatLng.newBuilder()
                  .setLatitude(37.41)
                  .setLongitude(-122.11)
                  .build())
      .setFilter("attributes.my_key = my_value")
      .build();

try {
  ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
      deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
          break;

      case PERMISSION_DENIED:
          break;
  }
  return;
}

راحة

لإدراج المهام من متصفّح، عليك إجراء استدعاء HTTP REST لـ ListDeliveryVehicles:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`

لتطبيق فلتر على المهام المدرَجة، أدرِج معلمة عنوان URL "فلتر" مع طلب بحث يتضمّن أحرف إلغاء لعنوان URL كقيمته.

يجب أن يحتوي عنوان الطلب على حقل تفويض بالقيمة الحامل <token>، حيث يكون <token> رمزًا مميّزًا صادرًا عن مصنع الرموز المميّزة في Fleet Engine.

إذا تم البحث بنجاح، يحتوي نص الاستجابة على بيانات بالبنية التالية:

// JSON representation
{
  "deliveryVehicles": [
    {
      object (DeliveryVehicle)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

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

مثال على الأمر curl:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"

تتبُّع أسطول المركبات

أمامك خياران لاستخدام واجهة برمجة تطبيقات Fleet Engine Deliveries API لتمكين تتبع الأسطول:

• الخيار المفضّل: عليك استخدام مكتبة تتبُّع مجموعة JavaScript. تتيح لك المكتبة تصور مواقع المركبات والمواقع محل الاهتمام التي يتم تتبعها في Fleet Engine. وهو يحتوي على مكون خريطة JavaScript الذي يُعد بديلاً عن كائن google.maps.MAP القياسي، ومكونات البيانات للاتصال بـ Fleet Engine. ويتيح لك هذا المكون تقديم تجربة تتبع أسطول سيارات متحركة وقابلة للتخصيص من خلال الويب أو تطبيق الأجهزة الجوّالة.

• تنفيذ عملية تتبُّع مجموعة الأجهزة الخاصة بك بالإضافة إلى واجهة برمجة تطبيقات Fleet Engine Deliveries.

المفتاح هو البحث عن مهام مجموعة الأجهزة من خلال رقم تعريف التتبّع.

التسجيل

يمكنك ضبط Fleet Engine لإرسال سجلات RPC إلى Cloud Logging. لمزيد من المعلومات، يُرجى الاطّلاع على تسجيل الدخول.

الأدوار والرموز المميزة للتفويض

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

لمزيد من المعلومات، راجع المصادقة والتفويض.

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

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

المرونة

لا يعتبر Fleet Engine مصدرًا للحقيقة. وتقع على عاتقك مسؤولية استعادة حالة نظامك، إذا لزم الأمر، بدون الاعتماد على Fleet Engine.

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

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

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

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

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

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

الأسئلة الشائعة

ماذا لو توقف سائق عن مهمة خارج الترتيب؟

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