يفترض هذا المستند معرفة ما يلي:
- إنشاء مهام الشحن
- مقدمة حول المهام المُجدوَلة، والتي تغطي العلاقة بين المهام والمحطات والمركبات بالتفصيل
كما هو موضّح في المهام المُجدوَلة ضمن أساسيات Fleet Engine، يمكنك إنشاء مهام وربطها بمحطة توقّف للمركبة كطريقة لتصميم عملية الربط بين المهمة والموقع الجغرافي الذي من المتوقّع أن تتوقّف فيه المركبة ليتمكّن السائق من إكمال المهمة.
بعد ذلك، يمكنك إدارة تقدّم المهام طوال دورة حياتها من خلال إرسال إشعارات إلى Fleet Engine كي تتمكّن من تنفيذ توجيهات وتعديلات الحالة على طول رحلة المهمة بأفضل طريقة. إحدى الطرق الرئيسية لتحقيق ذلك هي تعديل حالة محطة النقل العام عندما تقترب المركبة من المحطة وتصل إليها وتغادرها. يتيح ذلك إعداد التقارير والتحليلات حول مستوى تقدّم المهمة لكل من مشغّلي أساطيل المركبات والمستخدمين النهائيين. في ما يلي حالات التحديث:
- في الطريق: يستخدم التعداد
STATE
الخاص بـVehicleStop
السمةENROUTE
للإشارة إلى أنّ المحطة هي التالية في قائمة خط سير المركبة. من منظور المهمة، يعني ذلك أنّ أي مهمة مرتبطة بالمحطة هي التالية في قائمة المهام المطلوب إكمالها. - وصلت: يستخدم التعداد
STATE
الخاص بـVehicleStop
القيمةARRIVED
للإشارة إلى أنّ المركبة وصلت إلى المحطة. من منظور المهمة، يعني ذلك أنّه سيتم إيقاف أي مهمة مرتبطة بالمحطة. - مكتملة: يمكنك وضع علامة "مكتملة" على محطة من خلال إزالتها من قائمة المحطات الخاصة بالمركبة. عند إجراء ذلك، يضع Fleet Engine علامة CLOSED تلقائيًا على جميع المهام المرتبطة. لمزيد من التفاصيل حول إغلاق المهام، يُرجى الاطّلاع على إنهاء المهام.
يوضّح هذا المستند كيفية تعديل حالة الإيقاف باستخدام طرق من جهة الخادم. يمكنك أيضًا إجراء ذلك من تطبيق السائق إذا أتحت للسائق إمكانية إدارة المهام باستخدام جهاز موثوق به. استخدِم طريقة واحدة فقط لتجنُّب حالات التزامن والحفاظ على مصدر واحد للحقيقة.
المركبة في طريقها إلى المحطة
يجب أن يرسل نظامك إشعارًا إلى 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