يفترض هذا المستند معرفة ما يلي:
- إنشاء مهام الشحن
- مقدمة عن المهام المُجدوَلة، التي تتناول بالتفصيل العلاقة بين المهام ومحطات التوقف والمركبات
كما هو موضّح في المهام المُجدوَلة في أساسيات Fleet Engine، يمكنك إنشاء مهام وربطها بنقطة توقف للمركبة كطريقة لوضع نموذج للربط في العالم الواقعي بين المهمة والموقع الجغرافي الذي من المتوقّع أن تتوقف فيه المركبة كي يتمكّن السائق من إكمال المَهمّة.
ومن هناك، يمكنك إدارة مستوى تقدّم المهام على مدار دورة حياتها من خلال إرسال آخر المعلومات إلى Fleet Engine كي يتمكّن من تنفيذ عمليات إعادة التوجيه وتعديل الحالة بأفضل شكل على مدار رحلة المهمة. ومن الطرق الرئيسية لإجراء ذلك تعديل محطة المركبات عند اقتراب المركبة من المحطة ووصولها إليها ومغادرتها. يتيح ذلك إعداد التقارير والتحليلات حول مستوى تقدّم المهام لكل من مشغّلي الأسطول والمستخدمين النهائيين. في ما يلي تحديثات الحالة هذه:
- أثناء الرحلة: يستخدم التعداد
STATE
لـVehicleStop
القيمةENROUTE
لتحديد أنّ المحطة هي المحطة التالية في قائمة برنامج الرحلة للمركبة. من منظور المهمة، يعني ذلك أنّ أي مهمة مرتبطة بالنقطة المتوقفة هي التالية في القائمة التي يجب إكمالها. - وصل: يستخدم التعداد
STATE
لـVehicleStop
القيمةARRIVED
للإشارة إلى أنّ المركبة قد وصلت إلى المحطة. من منظور المهمة، يعني ذلك أنّ أي مهمة مرتبطة بالتوقف يتم العمل عليها بشكل نشط. - مكتمل: يمكنك وضع علامة على محطة بأنّها مكتملة من خلال إزالتها من قائمة محطات المركبة. عند إجراء ذلك، يضع Fleet Engine تلقائيًا علامة "مغلقة" على جميع المهام المرتبطة. لمزيد من التفاصيل حول إغلاق المهام، يُرجى الاطّلاع على مقالة إنهاء المهام.
يصف هذا المستند كيفية إيقاف تحديث حالة استخدام الأساليب من جهة الخادم. يمكنك أيضًا إجراء ذلك من تطبيق السائق إذا وفّرت للسائق إمكانية إدارة المهام باستخدام جهاز موثوق. استخدِم طريقة واحدة فقط لتجنُّب حالات التسابق والحفاظ على مصدر واحد للحقائق.
المركبة في طريقها إلى نقطة التوقف
من المفترض أن يُرسِل نظامك إشعارًا إلى Fleet Engine عندما تبدأ المركبة في التنقّل إلى المحطة التالية. ويؤدي ذلك إلى تحسين حسابات وقت الوصول إلى الوجهة والمسار.
الحقول المطلوبة لإيقاف التحديثات
يتجاهل Fleet Engine جميع الحقول الأخرى في العنصر المرتبط بالإشعار.
الحقل | القيمة |
---|---|
remainingVehicleJourneySegments
|
قائمة بنقاط توقّف المركبات المتبقية مع وضع علامة "State.NEW" على حالاتها |
مثال على التوقف أثناء الرحلة
توضِّح الأمثلة التالية كيفية إرسال إشعار إلى Fleet Engine بأنّ المركبة في طريقها إلى محطتها التالية، وذلك باستخدام مكتبة Java gRPC أو طلب HTTP
REST إلى UpdateDeliveryVehicle
.ويتم وضع علامة "جديد" على جميع المحطات الأخرى.
gRPC
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;
}
REST
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
- <id> هو معرّف فريد للمهمة.
- يجب أن يحتوي رأس الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.
- يجب أن يحتوي نص الطلب على عنصر
DeliveryVehicle
:
مثال على طلب 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
{
"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
وصول المركبة إلى المحطة
يجب إشعار Fleet Engine عندما تصل مركبة إلى محطة.
الحقول المطلوبة لإيقاف التحديثات
يتجاهل Fleet Engine جميع الحقول الأخرى في العنصر المرتبط بالإشعار.
الحقل | القيمة |
---|---|
remainingVehicleJourneySegments
|
قائمة بنقاط وقوف المركبات المتبقية مع وضع علامة "State.NEW" على حالاتها |
مثال على الوصول إلى المحطة
توضِّح الأمثلة التالية كيفية إبلاغ Fleet Engine بأنّ مركبة قد وصلت
إلى المحطة، وذلك باستخدام مكتبة Java gRPC أو طلب HTTP REST إلى
UpdateDeliveryVehicle
. يتم وضع علامة "جديد" على جميع المحطات الأخرى.
gRPC
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;
}
REST
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
- <id> هو معرّف فريد للمهمة.
- يجب أن يحتوي رأس الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.
- يجب أن يحتوي نص الطلب على عنصر
DeliveryVehicle
:
مثال على طلب 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
{
"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 عندما تنتهي المركبة من التوقف. يؤدي ذلك إلى ضبط جميع المهام المرتبطة بالتوقف على الحالة "مغلقة".
الحقول المطلوبة لإيقاف التحديثات
يتجاهل Fleet Engine جميع الحقول الأخرى في العنصر المرتبط بالإشعار.
الحقل | القيمة |
---|---|
remainingVehicleJourneySegments |
قائمة بنقاط وقوف المركبات المتبقية مع وضع علامة "State.NEW" على حالاتها يجب أن تكون حالة المحطة الأولى في القائمة هي State.ENROUTE. |
مثال على إكمال نقطة توقف
توضِّح الأمثلة التالية كيفية إبلاغ Fleet Engine بوصول مركبة
إلى المحطة، وذلك باستخدام مكتبة Java gRPC أو طلب HTTP REST إلى
UpdateDeliveryVehicle
. يتم وضع علامة "جديد" على جميع المحطات الأخرى.
gRPC
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;
}
REST
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
- <id> هو معرّف فريد للمهمة.
- يجب أن يحتوي رأس الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.
- يجب أن يحتوي نص الطلب على عنصر
DeliveryVehicle
:
مثال على طلب 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
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM