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

يفترض هذا المستند الإلمام بما يلي:

  • [إنشاء مهام الشحن][1]
  • مقدمة عن [المهام المجدوَلة][3]، والتي تتناول العلاقة بين المهام ومحطات التوقف والمركبات بالتفصيل

كما هو موضّح في [المهام المجدوَلة][3] في أساسيات Fleet Engine، يمكنك إنشاء مهام وربطها بنقطة توقّف للمركبة كطريقة لنمذجة الربط الواقعي بين المهمة والموقع الجغرافي الذي من المتوقّع أن تتوقّف فيه المركبة ليتمكّن السائق من إكمال المهمة.

بعد ذلك، يمكنك إدارة مستوى تقدّم المهام طوال مراحل نشاطها من خلال إرسال التعديلات إلى Fleet Engine ليتمكّن من إجراء تعديلات على المسارات والحالة على أفضل نحو خلال رحلة المهمة. ومن الطرق الرئيسية لإجراء ذلك تعديل محطة توقّف المركبة عندما تقترب المركبة من المحطة وتصل إليها وتغادرها. يتيح ذلك إعداد التقارير وتحليل مستوى تقدّم المهمة لكل من مشغّلي الأسطول والمستخدمين النهائيين. في ما يلي تحديثات الحالة هذه:

  • في الطريق: يستخدم التعداد STATE لـ VehicleStop السمة ENROUTE للإشارة إلى أنّ المحطة هي التالية في قائمة برنامج رحلة المركبة. من منظور المهمة، يعني ذلك أنّ أي مهمة مرتبطة بالمحطة هي التالية في القائمة التي يجب إكمالها.
  • Arrived: يستخدم التعداد STATE لـ VehicleStop القيمة ARRIVED للإشارة إلى أنّ المركبة قد وصلت إلى المحطة. من منظور المهمة، يعني ذلك أنّ أي مهمة مرتبطة بالإيقاف يتم العمل عليها بشكل نشط.
  • مكتملة: يمكنك وضع علامة "مكتملة" على محطة من خلال إزالتها من قائمة محطات المركبة. عند إجراء ذلك، يضع Fleet Engine علامة "مغلقة" تلقائيًا على جميع المهام المرتبطة. لمزيد من التفاصيل حول إغلاق المهام، راجع [إنهاء المهام][4].

يوضّح هذا المستند كيفية تعديل حالة المحطة باستخدام طرق من جهة الخادم. يمكنك أيضًا إجراء ذلك من تطبيق السائق إذا منحت السائق إمكانية إدارة المهام باستخدام جهاز موثوق به. استخدِم طريقة واحدة فقط لتجنُّب حالات السباق والحفاظ على مصدر وحيد للحقيقة.

المركبة في طريقها إلى المحطة

يجب أن يرسل نظامك إشعارًا إلى Fleet Engine عندما تبدأ المركبة في الانتقال إلى المحطة التالية. يساعد ذلك في تحسين الوقت المقدَّر للوصول وحسابات المسارات.

الحقول المطلوبة لتعديل محطات الشحن

يتجاهل Fleet Engine جميع الحقول الأخرى في الكيان للإشعار.

الحقلالقيمة
remainingVehicleJourneySegments قائمة بنقاط توقّف المركبة المتبقية مع وضع علامة على حالاتها على أنّها State.NEW

مثال على حالة "في الطريق إلى المحطة"

توضّح الأمثلة التالية كيفية إعلام Fleet Engine بأنّ المركبة في طريقها إلى محطتها التالية، وذلك باستخدام [مكتبة Java gRPC][5] أو طلب 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> وفقًا للإرشادات الموضّحة في [أدوار حسابات الخدمة][6] و [الرموز المميّزة الخاصة بالويب JSON][6].
  • يجب أن يحتوي نص الطلب على كيان 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

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

وصول المركبة إلى المحطة

يجب إرسال إشعار إلى Fleet Engine عند وصول مركبة إلى محطة.

الحقول المطلوبة لتعديل محطات الشحن

يتجاهل Fleet Engine جميع الحقول الأخرى في الكيان للإشعار.

الحقلالقيمة
remainingVehicleJourneySegments قائمة بنقاط توقّف المركبة المتبقية مع وضع علامة على حالاتها على أنّها State.NEW

مثال على الوصول إلى محطة

توضّح الأمثلة التالية كيفية إبلاغ Fleet Engine بوصول مركبة إلى المحطة، باستخدام [مكتبة Java gRPC][5] أو طلب 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> وفقًا للإرشادات الموضّحة في [أدوار حسابات الخدمة][6] و [الرموز المميّزة الخاصة بالويب JSON][6].
  • يجب أن يحتوي نص الطلب على كيان 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][5] أو طلب 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> وفقًا للإرشادات الموضّحة في [أدوار حسابات الخدمة][6] و [الرموز المميّزة الخاصة بالويب JSON][6].
  • يجب أن يحتوي نص الطلب على كيان 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

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

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

  • [إكمال المهام][4]

[1]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks [3]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [4]: /maps/documentation/mobility/fleet-engine/journeys/tasks/finalize-tasks [5]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts