إعداد المهام

يفترض هذا المستند أنّك تفهم كيفية إنشاء المهام واستخدامها. تقدّم هذه المقالة أمثلة محدّدة حول كيفية ضبط مهام الشحن بالطرق التالية:

  • ضبط الفترة الزمنية المستهدَفة لمهمة الشحن: اضبط الفترة الزمنية لإكمال المهمة.

  • تخصيص مستوى رؤية المهام: يمكنك تخصيص مستوى رؤية أنشطة المهام لعرضها على العملاء أو مشغّلي الأسطول.

اطّلِع على إنشاء مهام الشحن لمعرفة تفاصيل عن حقول مهام الشحن. عند تعديل معلومات إضافية عن المهام الحالية، يجب أيضًا تضمين المعرّف ذي الصلة بالمهمة، بالإضافة إلى الحقول التي تعدّلها للمهام.

ضبط الفترة الزمنية المستهدَفة

الفترة الزمنية المستهدَفة هي TimeWindow التي يجب أن يتم فيها إكمال المهمة. على سبيل المثال، إذا أبلغت عن فترة زمنية للتسليم إلى مستلمي التسليم، يمكنك استخدام الفترة الزمنية المستهدَفة للمهمة لتسجيل هذه الفترة الزمنية وإنشاء تنبيهات، أو يمكنك استخدامها لتحليل أداء الرحلات السابقة.

يتألّف الإطار الزمني المستهدَف من وقت بدء ووقت انتهاء ويمكن ضبطه على أي نوع من أنواع المهام. لا تؤثر النافذة الزمنية المستهدَفة في سلوك توجيه الطلبات.

توضّح الأمثلة التالية كيفية ضبط النافذة الزمنية باستخدام مكتبة Java gRPC أو كيفية إرسال طلب HTTP REST إلى UpdateTask. يمكنك أيضًا ضبط هذا الحقل في وقت إنشاء المهمة.

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";
  static final String TASK_ID = "task-8241890";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
  Task task = Task.newBuilder()
    .setName(taskName)
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .build();

  // Task request
  UpdateTaskRequest updateTaskRequest =
    UpdateTaskRequest.newBuilder()  // No need for the header
        .setTask(task)
        .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
        .build();

  try {
    Task updatedTask = deliveryService.updateTask(updateTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case NOT_FOUND:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

لضبط فترة زمنية للمهمة باستخدام HTTP، يمكنك استدعاء PATCH و استخدام updateMask لتعديل المَعلمة targetTimeWindow:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow

في هذه الحالة، <id> هو معرّف فريد للمهمة. يجب أن يحتوي عنوان الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر الخادم <token> وفقًا للإرشادات описанة في أدوار حسابات الخدمة ورموز JSON Web Token.

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
  curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
    -H "Content-type: application/json" \
    -H "Authorization: Bearer ${JWT}" \
    --data-binary @- << EOM
  {
    "targetTimeWindow": {
      "startTime": "2023-03-29T21:00:00Z",
      "endTime": "2023-03-29T23:00:00Z"
    }
  }
  EOM

تخصيص مستوى رؤية المهام

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

يصف هذا القسم قواعد مستوى الرؤية للعناصر التي يتم تتبُّعها على الخريطة. تنطبق هذه القواعد على فئتين من الكائنات:

  • مستوى ظهور علامة الموقع الجغرافي
  • مستوى رؤية بيانات المهام لمهام المركبات النشطة، مثل الخطوط المتعددة والوقت المقدَّر للوصول

قواعد مستوى رؤية علامة الموقع الجغرافي

تعرِض Fleet Engine علامات المواقع الجغرافية لموقع تسليم الشحنة المعروض على الخريطة، بغض النظر عن حالة التسليم.

قواعد مستوى الوصول إلى بيانات المهام

يصف هذا القسم قواعد مستوى العرض التلقائية التي تنطبق على بيانات المهام. يمكنك تخصيص مهام المركبات النشطة فقط، ما يعني أنّه يمكن فقط ل tasks pickup and drop-off تطبيق قواعد مستوى الرؤية المخصّصة.

لا يمكن تخصيص المهام التالية:

  • المحطات المجدوَلة
  • مهام عدم التوفّر
  • مهام المركبات غير النشطة

قواعد مستوى رؤية مهام "عدم التوفّر"

لا تظهر المركبة تلقائيًا على الخريطة إذا تم تعيين مهمة واحدة على الأقل لعدم التوفّر إلى المهمة التي يتم تتبُّعها. على سبيل المثال، إذا كان السائق يأخذ استراحة أو تتم تعبئة المركبة بالوقود على الطريق المؤدي إلىshipment التي يتم تتبُّعها. لا يزال الوقت المقدَّر للوصول والوقت المقدَّر لإكمال المهمة متاحَين. مرة أخرى، لا يمكنك تخصيص هذه القاعدة.

مستوى ظهور مهام المركبات النشطة

يقدّم عنصر TaskTrackingInfo عددًا من عناصر البيانات التي يمكنك إظهارها باستخدام "مكتبة تتبُّع الشحنات". تظهر هذه الحقول تلقائيًا عند تعيين المهمة للمركبة وعند وصول المركبة إلى مسافة 5 محطات من المهمة. تنتهي إمكانية الوصول عند اكتمال المهمة أو إلغائها.

يمكنك تخصيص إعدادات مستوى الرؤية لكل مهمة على حدة من خلال ضبط TaskTrackingViewConfig على المهمة عند إنشائها أو تعديلها في Fleet Engine. يؤدي ذلك إلى إنشاء قواعد لعناصر البيانات الفردية لتصبح متوفّرة.

يعرض الجدول التالي الحقول التي يمكنك تطبيق قواعد مستوى العرض عليها.

حقول مهام المركبات لقواعد مستوى العرض
  • خطوط المسار المتعدّدة
  • الوقت المقدَّر للوصول
  • الوقت المقدَّر لإكمال المهمة
  • المسافة المتبقية للقيادة إلى المهمة
  • عدد المحطات المتبقية
  • الموقع الجغرافي للمركبة

يعرض هذا الجدول خيارات مستوى العرض المتاحة للحقول المدرَجة أعلاه.

خيارات مستوى الرؤية
  • عدد المحطات المتبقية
  • المدة المتبقية حتى وقت الوصول المقدَّر
  • المسافة المتبقية للقيادة
  • مرئي دائمًا
  • غير مرئية مطلقًا

خطوط البوليلين للمسارات وقواعد مستوى رؤية الموقع الجغرافي للمركبة

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

اتّبِع هذه القواعد لتقديم خطوط متعددة صالحة للمسار / موقع المركبة / ميزة الرؤية.

تحدِّد الخطوط المتعددة للمسارات وموقع المركبة خيارات الرؤية نفسها.

في هذا السيناريو، يضبط كلّ من الخطّ المتعدّد والموقع الجغرافي للمركبة options نفسها، والتي تشمل ما يلي:

  • عدد المحطات المتبقية
  • المدة المتبقية حتى الوصول
  • المسافة المتبقية للقيادة

للالتزام بالقواعد، يجب أن تكون قيمة مستوى رؤية الخطوط المتعددة للمسار أقل من أو مساوية للقيمة المحدّدة لمستوى رؤية المركبة. في هذا المثال، تم ضبط الحدّ الأدنى لعدد محطات التوقف المتبقية للخط المتعدّد على 3، وهو أقل من القيمة 5 المحدّدة للمركبة. وهذا يعني أنّه عندما تصل الرحلة التي يتم تتبُّعها إلى 5 محطات من موقع المهمة، تظهر المركبة، ولكن لا يظهر مسار هذه المركبة إلى أن تصبح الرحلة على بعد 3 محطات.

```js
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingStopCountThreshold": 5
  },
}
```

تحدِّد الخطوط المتعددة للمسارات وموقع المركبة خيارات الرؤية المختلفة.

عندما يكون لدى خطوط البوليلين للمسار وموقع المركبة خيارات ظهور مختلفة، لا يكون موقع المركبة مرئيًا إلا عند استيفاء كلا خيارَي الظهور. تجدر الإشارة إلى أنّ مستوى رؤية الخطوط المتعددة يخضع لقواعد مستوى رؤية المركبة:

  • مرئي دائمًا: يجب أن يستخدم خط المسار المتعدد الأضلاع خيار مستوى الرؤية مرئي دائمًا عندما يقدّم موقع المركبة أيضًا خيار مستوى الرؤية مرئي دائمًا نفسه.
  • غير مرئية أبدًا: يجب أن يستخدم خط المسار المتعدد الأضلاع خيار مستوى الظهور غير مرئية أبدًا عندما يستخدم موقع المركبة خيار مستوى الظهور غير مرئية أبدًا.

في ما يلي مثال:

  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "vehicleLocationVisibility": {
      "remainingDrivingDistanceMetersThreshold": 3000
    },
  }

في هذا المثال، لا يظهر موقع المركبة إلا إذا كان عدد المحطات المتبقية يزيد عن 3 محطات وكانت المسافة المتبقية للقيادة تزيد عن 3000 متر.

مثال على تخصيص مستوى رؤية المهام

توضّح الأمثلة التالية كيفية ضبط مهمة باستخدام قواعد الظهور التالية:

  • عرض الخطوط المتعددة للمسار إذا كانت المركبة ضمن 3 محطات
  • عرض وقت الوصول المقدَّر إذا كانت المسافة المتبقية للقيادة أقصر من 5000 متر
  • لا تعرض أبدًا عدد المحطات المتبقية.
  • يحتفظ كل حقل آخر بمستوى العرض التلقائي الذي يتم عرضه عندما يكون المركبة ضمن 5 محطات من المهمة.

يُرجى الاطّلاع على TaskTrackingViewConfig لمعرفة كيفية استخدام gRPC أو REST.

gRPC

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}

REST

لضبط نافذة إعدادات عرض تتبُّع المهام باستخدام HTTP، اتصل بـ PATCH واستخدِم updateMask لتعديل المَعلمة taskTrackingViewConfig:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig

على سبيل المثال:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

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