تعديل حالة المحطة

يفترض هذا المستند معرفة ما يلي:

كما هو موضّح في المهام المُجدوَلة ضمن أساسيات 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`

مثال على طلب 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`

مثال على طلب 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`

مثال على طلب 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

الخطوات التالية