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

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

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

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