إنشاء مهام الشحن

يفترض هذا المستند أنّك قرأت الدليل التمهيدي حول [المهام المُجدوَلة][1] في قسم مقدّمة عن Fleet Engine بالإضافة إلى [ما هي المَهمّة المُجدوَلة؟][2] في هذا القسم.

يوفّر Fleet Engine للمهام المُجدوَلة فئات مختلفة من المهام:

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

يتناول هذا المستند كيفية إنشاء مهام شحنات على الخادم. بالنسبة إلى أنواع المهام الأخرى، يُرجى الاطّلاع على إنشاء أنواع مهام أخرى.

حقول مهام تسليم الشحنات

يوضّح هذا القسم حقول المهام المطلوبة لكل من مهام الاستلام والتسليم.

حقول المهام المطلوبة

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

الحقلالقيمة
type

يجب ضبطه على النوع الذي يتطابق مع نوع المهمة، وهو أحد الأنواع التالية:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id معرّف المهمة الفريد يجب ألا يكون هذا الرقم هو رقم تتبُّع الشحنة. إذا لم يكن لديك معرّفات مهام في نظامك، يمكنك إنشاء معرّف فريد عالميًا (UUID). لمعرفة التفاصيل، يُرجى الاطّلاع على أرقام تعريف المهام.
tracking_id مهام PICKUP أو DELIVERY فقط: الرقم أو المعرّف الذي تستخدمه لتتبُّع شحنة يُرجى عدم تقديم هذا الحقل للمهام غير المتعلّقة بالشحن.
planned_location مهام PICKUP أو DELIVERY أو SCHEDULED_STOP فقط: الموقع الجغرافي الذي يجب إكمال المهمة فيه هذا الإجراء غير مطلوب لمهام UNAVAILABLE.
task_duration الوقت المتوقّع لإكمال المهمة على سبيل المثال، للبحث عن موقف سيارات أو المشي إلى مكان التسليم

حقول اختيارية لمهمة الشحن

الحقلالقيمة
target_time_window يشير هذا الحقل إلى الفترة الزمنية التي يجب إكمال المهمة خلالها. لا يؤثر هذا الحقل في سلوك التوجيه.
task_tracking_view_config PICKUP أو DELIVERY مهمة فقط: إعدادات تتبُّع المهام التي تحدّد عناصر البيانات التي تظهر للمستخدمين النهائيين في ظروف معيّنة.
attributes قائمة بسمات المهام المخصّصة يجب أن يكون لكل سمة مفتاح فريد.

إنشاء مهمة استلام شحنة

لاستخدام Fleet Engine لمتابعة نشاط سائق يستلم شحنة، أنشئ مهمة استلام شحنة. يتضمن ذلك ضبط سمة نوع المهمة على PICKUP. يوضح المثال التالي استلام شحنة من Grand Indonesia East Mall.

توضّح الأمثلة التالية كيفية إنشاء مهمة استلام شحنة باستخدام [مكتبة Java gRPC][4] أو كيفية إرسال طلب HTTP REST إلى [CreateTask][5].

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String parent = "providers/" + PROJECT_ID;
  Task task = Task.newBuilder()
    .setType(Task.Type.PICKUP)
    .setState(Task.State.OPEN)
    .setTrackingId("my-tracking-id")
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .build();

  // Task request
  CreateTaskRequest createTaskRequest =
    CreateTaskRequest.newBuilder()  // No need for the header
        .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
        .setTaskId("task-8241890")  // Task ID assigned by the Provider
        .setTask(task)              // Initial state
        .build();

  // Error handling
  // If Fleet Engine does not have a task with that ID and the credentials of the
  // requestor pass, the service creates the task successfully.

  try {
    Task createdTask = deliveryService.createTask(createTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case ALREADY_EXISTS:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

لإنشاء مهمة استلام شحنة من بيئة خادم، يمكنك إجراء طلب HTTP REST إلى CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

‫<id> هو معرّف فريد للمهمة.

يجب أن يحتوي عنوان الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في [أدوار حسابات الخدمة][6] و[الرموز المميّزة الخاصة بالويب JSON][7].

يجب أن يحتوي نص الطلب على كيان Task مع الحقول المناسبة الموضّحة في [حقول مهمة الشحن][8].

مثال على أمر curl:

 # Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
 # environment
 curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "type": "PICKUP",
   "state": "OPEN",
   "trackingId": "${TRACKING_ID}",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "90s",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 EOM

إنشاء مهمة تسليم شحنة

لاستخدام Fleet Engine لمتابعة نشاط سائق يسلّم شحنة، يجب إنشاء مهمة تسليم شحنة. يتضمن ذلك ضبط سمة نوع المهمة على DELIVERY. يوضّح المثال التالي عملية تسليم شحنة إلى Grand Indonesia East Mall.

توضّح الأمثلة التالية كيفية إنشاء مهمة استلام شحنة باستخدام [مكتبة Java gRPC][4] أو كيفية إرسال طلب HTTP REST إلى [CreateTask][5].

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String parent = "providers/" + PROJECT_ID;
  Task task = Task.newBuilder()
    .setType(Task.Type.DELIVERY)
    .setState(Task.State.OPEN)
    .setTrackingId("my-tracking-id")
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .build();

  // Task request
  CreateTaskRequest createTaskRequest =
    CreateTaskRequest.newBuilder()  // No need for the header
        .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
        .setTaskId("task-8241890")  // Task ID assigned by the Provider
        .setTask(task)              // Initial state
        .build();

  // Error handling
  // If Fleet Engine does not have task with that ID and the credentials of the
  // requestor pass, the service creates the task successfully.

  try {
    Task createdTask = deliveryService.createTask(createTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case ALREADY_EXISTS:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

لإنشاء مهمة استلام شحنة من بيئة خادم، يمكنك إجراء طلب HTTP REST إلى CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

‫<id> هو معرّف فريد للمهمة.

يجب أن يحتوي عنوان الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في [أدوار حسابات الخدمة][6] و[الرموز المميّزة الخاصة بالويب JSON][7].

يجب أن يحتوي نص الطلب على كيان Task:

مثال على أمر curl:

 # Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
 # environment
 curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "type": "DELIVERY",
   "state": "OPEN",
   "trackingId": "${TRACKING_ID}",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "90s",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 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

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

  • [إنشاء أنواع مهام أخرى][13]
  • [تعديل المهام][3]

[1]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [2]: /maps/documentation/mobility/fleet-engine/journeys/tasks [3]: update-tasks [4]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks#java [5]: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/create [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts [7]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt [8]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks#shipment_task_fields [13]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-other-tasks