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

يفترض هذا المستند أنّك قرأت الدليل التمهيدي حول المهام المجدوَلة في قسم مقدمة عن 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 أو كيفية إرسال طلب 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

تجريبي: كميزة تجريبية، يتيح الحقل LocationInfo (gRPC أو REST) الآن استخدام place (gRPC أو REST)، إما إلى جانب LatLng أو بدلاً منه.

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

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

توضّح الأمثلة التالية كيفية إنشاء مهمة استلام شحنة باستخدام مكتبة Java gRPC أو كيفية إرسال طلب 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
 ```

تجريبي: كميزة تجريبية، يتيح الحقل LocationInfo (gRPC أو REST) الآن استخدام place (gRPC أو REST)، إما إلى جانب LatLng أو بدلاً منه.

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

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