إعداد المهام

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

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

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

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

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

النافذة الزمنية المستهدَفة هي 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.

# 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 علامات الموقع الجغرافي لموقع تسليم الشحنة الموضّح على الخريطة، بغض النظر عن حالة التسليم.

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

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

قد لا يتم تخصيص المهام التالية:

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

قواعد مستوى ظهور مهام عدم التوفّر

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

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

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

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

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

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

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

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

قواعد ظهور الخطوط المتعدّدة للمسارات والموقع الجغرافي للمركبة

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

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

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

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

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

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

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

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

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

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

في ما يلي مثال على ذلك:

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

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

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

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

  • عرض الخطوط المتعدّدة للمسار إذا كانت المركبة على بُعد 3 محطات توقّف أو أقل
  • عرض الوقت المقدَّر للوصول إذا كانت المسافة المتبقية للقيادة أقل من 5,000 متر
  • عدم عرض عدد المحطات المتبقية مطلقًا
  • يحتفظ كل حقل آخر بمستوى العرض التلقائي الذي يظهر عندما تكون المركبة على بُعد 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

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