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

يفترض هذا المستند أنك قد قرأت الدليل التمهيدي المهام المُجدوَلة في القسم مقدّمة عن Fleet Engine أيضًا مثل ما هي المهمة المُجدوَلة؟ في هذا القسم.

يوفر Fleet Engine للمهام المجدولة فئات واسعة مختلفة من المهام:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

&lt;id&gt; هو معرّف فريد للمهمة.

يجب أن يحتوي عنوان الطلب على الحقل Authorize (تفويض) مع القيمة الحامل <token>، حيث يتم إصدار <token> من قِبل الخادم وفقًا بالإرشادات الموضحة في أدوار حساب الخدمة وJSON Web الرموز المميّزة.

يجب أن يحتوي نص الطلب على كيان 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. يوضح المثال التالي تسليم شحنة إلى متحف إندونيسيا إيست مول.

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

يجب أن يحتوي عنوان الطلب على الحقل Authorize (تفويض) مع القيمة الحامل <token>، حيث يتم إصدار <token> من قِبل الخادم وفقًا بالإرشادات الموضحة في أدوار حساب الخدمة وJSON Web الرموز المميّزة.

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

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