يفترض هذا المستند أنّك اطّلعت على الدليل التمهيدي لموضوع المهام المُجدوَلة في قسم مقدّمة عن Fleet Engine، بالإضافة إلى ما هي المهام المُجدوَلة؟ في هذا القسم.
يوفّر "محرك الأسطول" للمهام المُجدوَلة فئات واسعة مختلفة من المهام:
- مهام الشحن: استخدِم هذه المهام لمهام القيادة، بما في ذلك استلام shipments وتسليمها.
- مهام عدم التوفّر: استخدِمها في الأوقات التي لا يتوفّر فيها السائقون، مثل فترات الراحة المطلوبة.
- مهام التوقف المُجدوَلة: استخدِمها للمهام التي لا تتطلّب القيادة في صناديق التسليم أو مواقع العميل، مثل الوقت المستغرَق لدخول مبنى أو تحديد موقع نقطة تسليم.
يتناول هذا المستند كيفية إنشاء مهام غير متعلقة بالشحن على خادمك. للاطّلاع على أنواع مهام الشحن، يُرجى الاطّلاع على مقالة إنشاء مهام الشحن.
حقول المهام للمهام غير المتعلقة بالقيادة
يوثّق هذا القسم حقول المهام المطلوبة لكلّ من مهام إيقاف الخدمة وعدم التوفّر ومهام الإيقاف المُجدوَلة.
حقول المهام المطلوبة
لكل مهمة تنشئها في Fleet Engine، يجب تزويدها بالحقول المطلوبة، ويمكنك أيضًا تقديم أي من الحقول الاختيارية. يتجاهل Fleet Engine
جميع الحقول الأخرى، ويُرسِل استثناءً إذا كان طلب إنشاء مهمة
يقدّم deliveryVehicleId
مخصّصًا. لإسناد مهام إلى مركبة،
استخدِم UpdateDeliveryVehicleRequest
. لمزيد من المعلومات، يُرجى الاطّلاع على
تعديل المهام.
الحقل | القيمة |
---|---|
type |
اضبطه على النوع الذي يتطابق مع نوع المهمة، والذي يكون أحد الخيارَين التاليَين:
|
state |
State.OPEN |
task_id |
معرّف فريد للمهمة يجب ألا يكون هذا الرقم هو رقم تتبُّع الشحنة. إذا لم يكن لديك أرقام تعريف المهام في نظامك، يمكنك إنشاء معرّف عالمي فريد (UUID). لمعرفة التفاصيل، يُرجى الاطّلاع على أرقام تعريف المهام. |
tracking_id |
مهام PICKUP أو DELIVERY فقط:
الرقم أو المعرّف الذي تستخدمه لتتبُّع شحنة. لا ينبغي
تقديم هذا الحقل للمهام غير المتعلقة بالشحن. |
plannedLocation |
مهام PICKUP أو DELIVERY أو
SCHEDULED_STOP فقط: الموقع الجغرافي الذي سيتم إكمال المهمة فيه غير مطلوبة ل tasks
UNAVAILABLE |
taskDuration |
الوقت المتوقّع لإكمال المهمة. على سبيل المثال، للبحث عن مكان وقوف للسيارة أو السير إلى مكان تسليم الطلب. |
حقول مهمة الشحن الاختيارية
الحقل | القيمة |
---|---|
targetTimeWindow |
الفترة الزمنية التي يجب إنجاز المهمة خلالها. لا يؤثر هذا الحقل في سلوك التوجيه. |
task_tracking_view_config |
مهام PICKUP أو DELIVERY فقط:
إعدادات تتبُّع المهام التي تحدِّد عناصر البيانات التي تظهر للمستخدمين النهائيين في ظلّ أيّ ظروف |
attributes |
قائمة بسمات المهام المخصّصة يجب أن يكون لكل سمة مفتاح فريد. |
إنشاء مهمة عدم التوفّر
يمكنك إنشاء مهمة تشير إلى عدم التوفّر، مثلاً فترات راحة للسائق. لإنشاء مهمة عدم التوفّر، اتّبِع الإرشادات التالية:
- اضبط نوع المهمة على
UNAVAILABLE
. - لا تُدرِج رقم تعريف التتبّع.
- على الرغم من أنّه ليس عليك تقديم موقع جغرافي لمهمة غير متاحة، فإنّ إجراء ذلك يقدّم عمليات حسابية محسّنة لأوقات الوصول المقدَّرة على مدار اليوم.
تنطبق قواعد مستوى العرض الخاص على موقع المركبة الجغرافي عندما تكون في مهمة
UNAVAILABLE
لمشاركة الرحلة.
- تطبيقات المستهلك المدمجة مع مكتبة تتبُّع الشحنات: عندما يكون المركبة في مهمة تشير إلى عدم التوفّر، لا يمكن لمستخدمي تطبيق المستهلك الاطّلاع على موقع المركبة الجغرافي، ولكن سيظل بإمكانهم الاطّلاع على معلومات حالة شحنتهم.
- تطبيقات تتبُّع الأسطول المدمجة مع مكتبة تتبُّع الأسطول: عندما تكون المركبة في مهمة عدم التوفّر، سيتمكّن مدراء الأسطول الذين يستخدمون تطبيق تتبُّع الأسطول من الاطّلاع على موقع المركبة لمهام عدم التوفّر.
توضِّح الأمثلة التالية كيفية إنشاء مهمة غير متاحة مجدّدًا مجدوَلة باستخدام
مكتبة Java gRPC أو كيفية إرسال طلب HTTP REST إلى
CreateTask
.
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;
}
```
REST
لإنشاء مهمة عدم توفّر من بيئة خادم، يمكنك إرسال طلب HTTP REST
إلى CreateTask
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> هو معرّف فريد للمهمة.
يجب أن يحتوي رأس الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.
يجب أن يحتوي نص الطلب على عنصر Task
يتضمّن الحقول المناسبة описанة في حقول المهام للمهام غير المتعلقة بالقيادة.
مثال على طلب 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
إنشاء مهمة إيقاف مجدوَلة
يمكنك إنشاء مهمة لمحطة توقف مجدوَلة، على سبيل المثال، للمهام غير المتعلقة بالقيادة في مواقع العملاء، أو لمحطّات تعبئة الوقود، أو عندما يتلقّى السائق شحنات من مركبة نقل. عند إنشاء مهمة إيقاف مجدوَلة، اتّبِع الإرشادات التالية:
- اضبط نوع المهمة على
- لا تُدرِج رقم تعريف التتبّع.
- يمكنك اختياريًا تقديم موقع جغرافي.
توضِّح الأمثلة التالية كيفية إنشاء مهمة غير متاحة مجدّدًا مجدوَلة باستخدام
مكتبة Java gRPC أو كيفية إرسال طلب HTTP REST إلى
CreateTask
.
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;
}
```
REST
لإنشاء مهمة إيقاف مجدوَلة من بيئة خادم، يمكنك إرسال طلب HTTP REST
إلى CreateTask
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> هو معرّف فريد للمهمة.
يجب أن يحتوي رأس الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.
يجب أن يحتوي نص الطلب على عنصر Task
:
مثال على طلب 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