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

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

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

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

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