يفترض هذا المستند أنّك قرأت الدليل التمهيدي حول المهام المُجدوَلة في قسم مقدمة عن Fleet Engine، بالإضافة إلى ما هي المهمة المُجدوَلة؟ في هذا القسم.
توفّر Fleet Engine للمهام المُجدوَلة فئات مختلفة من المهام:
- مهام الشحن: تُستخدَم لمهام القيادة، بما في ذلك استلام الشحنات وتسليمها.
- مهام عدم التوفّر: تُستخدَم لتحديد الأوقات التي لا يكون فيها السائقون متاحين، مثل فترات الاستراحة الإلزامية.
- مهام التوقف المُجدوَلة: استخدِم هذا النوع من المهام لتحديد مهام غير متعلّقة بالقيادة في صناديق التسليم أو مواقع العملاء، مثل الوقت اللازم للدخول إلى مبنى أو تحديد نقطة التسليم.
يوضّح هذا المستند كيفية إنشاء مهام غير متعلّقة بالشحن على خادمك. بالنسبة إلى أنواع مهام الشحن، يُرجى الاطّلاع على إنشاء مهام الشحن.
حقول المهام غير المتعلّقة بالقيادة
يوضّح هذا القسم حقول المهام المطلوبة لكل من مهام عدم التوفّر ومهام التوقف المجدوَل.
حقول المهام المطلوبة
بالنسبة إلى كل مهمة تنشئها في Fleet Engine، عليك توفير الحقول المطلوبة، ويمكنك أيضًا توفير أي من الحقول الاختيارية. يتجاهل Fleet Engine جميع الحقول الأخرى، ويُصدر استثناءً إذا كان طلب إنشاء مهمة يوفّر deliveryVehicleId
معيّنًا. لإسناد مهام إلى مركبة، استخدِم UpdateDeliveryVehicleRequest
. لمزيد من المعلومات، يُرجى الاطّلاع على
تعديل المهام.
الحقل | القيمة |
---|---|
type |
اضبط القيمة على النوع الذي يتطابق مع نوع المهمة، وهو أحد الخيارات التالية:
|
state |
State.OPEN |
task_id |
معرّف المهمة الفريد يجب ألا يكون هذا الرقم هو رقم تتبُّع الشحنة. إذا لم تكن لديك أرقام تعريف للمهام في نظامك، يمكنك إنشاء معرّف فريد عالميًا (UUID). لمزيد من التفاصيل، يُرجى الاطّلاع على معرّفات المهام. |
tracking_id |
مهام PICKUP أو DELIVERY فقط:
الرقم أو المعرّف الذي تستخدمه لتتبُّع شحنة. لا توفِّر هذا الحقل للمهام غير المتعلقة بالشحن. |
planned_location |
PICKUP أو DELIVERY أو
SCHEDULED_STOP مهمة فقط: الموقع الجغرافي الذي يجب إكمال المهمة فيه غير مطلوبة لمهام UNAVAILABLE . |
task_duration |
الوقت المتوقّع إضافته لإكمال المهمة على سبيل المثال، للبحث عن مكان لإيقاف السيارة أو المشي إلى موقع استلام الطلب. |
حقول مهام الشحن الاختيارية
الحقل | القيمة |
---|---|
target_time_window |
الفترة الزمنية التي يجب إكمال المهمة خلالها لا يؤثر هذا الحقل في سلوك التوجيه. |
task_tracking_view_config |
مهام PICKUP أو DELIVERY فقط:
إعدادات تتبُّع المهام التي تحدّد عناصر البيانات التي يمكن للمستخدمين النهائيين الاطّلاع عليها في ظل ظروف معيّنة. |
attributes |
قائمة بسمات المهام المخصّصة يجب أن تتضمّن كل سمة مفتاحًا فريدًا. |
إنشاء مهمة عدم توفّر
يمكنك إنشاء مهمة تشير إلى عدم التوفّر، مثلاً، لفترات استراحة السائق. لإنشاء مهمة عدم توفّر، اتّبِع الإرشادات التالية:
- اضبط نوع المهمة على
UNAVAILABLE
. - عدم تضمين رقم تعريف تتبُّع
- على الرغم من أنّه ليس عليك تقديم موقع جغرافي لمهمة عدم التوفّر، فإنّ إجراء ذلك يوفّر حسابات محسّنة للوقت المقدّر للوصول على مدار اليوم.
تنطبق قواعد خاصة على إذن الوصول إلى موقع المركبة الجغرافي عندما تكون في مهمة UNAVAILABLE
لمشاركة الرحلة.
- تطبيقات المستهلكين المدمجة مع مكتبة Shipment Tracking API: عندما تكون المركبة في مهمة عدم توفّر، لا يمكن لمستخدمي تطبيق المستهلكين الاطّلاع على موقع المركبة، ولكن سيظل بإمكانهم الاطّلاع على معلومات الحالة الخاصة بشحنتهم.
- تطبيقات تتبُّع أسطول المركبات المدمجة مع مكتبة Fleet Tracking: عندما تكون المركبة في مهمة عدم توفّر، سيتمكّن مديرو الأساطيل الذين يستخدمون تطبيق تتبُّع أسطول المركبات من الاطّلاع على الموقع الجغرافي للمركبة في مهام عدم التوفّر.
توضّح الأمثلة التالية كيفية إنشاء مهمة عدم توفّر مجدوَلة باستخدام مكتبة 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