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

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

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

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