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

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

يوفّر "محرك الأسطول" للمهام المُجدوَلة فئات واسعة مختلفة من المهام:

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

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

حقول مهمة الشحن

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

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

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

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

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

الحقل	القيمة
targetTimeWindow	الفترة الزمنية التي يجب إنجاز المهمة خلالها. لا يؤثر هذا الحقل في سلوك التوجيه.
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

لإنشاء مهمة استلام شحنة من بيئة خادم، يمكنك إرسال 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 أو كيفية إرسال طلب 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

لإنشاء مهمة استلام شحنة من بيئة خادم، يمكنك إرسال 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
 ```

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

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