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

يفترض هذا المستند أنّك قرأت الدليل التمهيدي لـ المهام المجدولة في قسم مقدّمة عن Fleet Engine بالإضافة إلى مقالة ما هي المهمة المجدولة؟ في هذا القسم.

توفّر 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 library أو كيفية إرسال طلب HTTP REST إلى CreateTask.

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> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.

يجب أن يحتوي نص الطلب على كيان 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": "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 library أو كيفية إرسال طلب HTTP REST إلى CreateTask.

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> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.

يجب أن يحتوي نص الطلب على كيان 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
 ```

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