پیکربندی کردن تکالیف

این سند فرض می‌کند که شما می‌دانید چگونه تکالیف را ایجاد و استفاده کنید. این راهنما نمونه‌های خاصی برای نحوه پیکربندی تکالیف ارسال به روش‌های زیر ارائه می‌دهد:

  • تنظیم پنجره زمانی هدف برای تکلیف ارسال: پنجره زمانی را برای تکمیل تکلیف تنظیم کنید.

  • سفارشی‌سازی رؤیت‌پذیری تکلیف: رؤیت‌پذیری فعالیت‌های تکلیف را برای نمایش به مشتریان یا اپراتورهای ناوگان سفارشی‌سازی کنید.

برای جزئیات مربوط به فیلدهای مأموریت‌های مرسوله، به ایجاد مأموریت‌های مرسوله مراجعه کنید. وقتی اطلاعات تکمیلی درباره تکالیف موجود را به‌روز می‌کنید، باید علاوه‌بر فیلدهایی که برای تکالیف به‌روز می‌کنید، شناسه مربوط به تکلیف را نیز اضافه کنید.

تنظیم پنجره زمانی هدف

پنجره زمانی هدف، 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;
  }

استراحت

برای تنظیم پنجره زمانی تکلیف بااستفاده از HTTP، با PATCH تماس بگیرید و از updateMask برای به‌روزرسانی پارامتر targetTimeWindow استفاده کنید:

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

در اینجا <id> شناسه یکتای تکلیف است. سرایند درخواست باید حاوی فیلد Authorization با مقدار Bearer <token> باشد، که در آن <token> توسط سرور شما طبق دستورالعمل‌های شرح‌داده‌شده در نقش‌های حساب سرویس و JSON Web tokens صادر می‌شود.

# 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 تعدادی عنصر داده ارائه می‌دهد که می‌توانید بااستفاده از «کتابخانه پیگیری محموله» آن‌ها را نمایان کنید. به‌طور پیش‌فرض، این فیلدها وقتی تکلیف به خودرو واگذار می‌شود و وقتی خودرو در فاصله ۵ ایستگاه از تکلیف قرار دارد قابل‌مشاهده هستند. وقتی تکلیف تکمیل یا لغو شود، قابلیت رؤیت به‌پایان می‌رسد.

می‌توانید پیکربندی رؤیت‌پذیری را برای هر تکلیف به‌صورت جداگانه سفارشی‌سازی کنید. برای این کار، TaskTrackingViewConfig را هنگام ایجاد یا به‌روزرسانی تکلیف در Fleet Engine تنظیم کنید. این کار قوانینی را برای دردسترس بودن عناصر داده تکی ایجاد می‌کند.

جدول زیر فیلدهایی را نشان می‌دهد که می‌توانید قوانین رؤیت‌پذیری را برای آن‌ها اعمال کنید.

فیلدهای تکلیف خودرو برای قوانین نمایان بودن
  • چندخطی‌های مسیر
  • زمان تخمینی رسیدن
  • زمان تخمینی تکمیل تکلیف
  • مسافت رانندگی باقی‌مانده تا تکلیف
  • تعداد توقف‌های باقی‌مانده
  • مکان خودرو

این جدول گزینه‌های رؤیت‌پذیری دردسترس برای فیلدهای فهرست‌شده در بالا را نشان می‌دهد.

گزینه‌های رؤیت‌پذیری
  • تعداد توقف‌های باقی‌مانده
  • مدت زمان تا زمان تخمینی ورود
  • مسافت رانندگی باقی‌مانده
  • همیشه نمایان
  • هرگز قابل‌مشاهده نیست

قوانین رؤیت‌پذیری چندخطی‌های مسیر و مکان خودرو

برای مسیر ردیابی‌شده، نمایان بودن چندخطی‌های مسیر تابع نمایان بودن خودرو است. اگر چندخطی مسیر در مسیر فعالی که خودرو در آن نمایان نیست نمایان باشد، مکان خودرو همچنان می‌تواند از انتهای چندخطی نمایان استنباط شود. بنابراین، رؤیت‌پذیری چندخطی مسیر باید به‌اندازه رؤیت‌پذیری خودرو یا بیشتر از آن محدودکننده باشد.

این قوانین را دنبال کنید تا ترکیب رؤیت‌پذیری چندخطی‌های مسیر / مکان خودرو معتبری ارائه دهید.

چندخطی‌های مسیر و مکان خودرو گزینه‌های نمایانی یکسان را مشخص می‌کنند

در این سناریو، هم چندخطی و هم مکان خودرو گزینه‌های یکسانی را تنظیم می‌کنند که شامل موارد زیر است:

  • تعداد توقف‌های باقی‌مانده
  • مدت زمان تا زمان تخمینی ورود
  • مسافت رانندگی باقی‌مانده

برای رعایت قوانین، مقدار نمایان بودن چندخطی‌های مسیر باید کمتر یا مساوی مقدار تنظیم‌شده برای نمایان بودن خودرو باشد. در این مثال، آستانه توقف باقی‌مانده برای چندخطی روی ۳ تنظیم شده است که کمتر از مقدار ۵ مشخص‌شده برای خودرو است. این یعنی وقتی سفر ردیابی‌شده به ۵ ایستگاه مانده به مکان تکلیف می‌رسد، خودرو نشان داده می‌شود، اما مسیر آن خودرو تا زمانی که سفر به ۳ ایستگاه مانده به مکان تکلیف نرسد نشان داده نمی‌شود.

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

چندخطی‌های مسیر و مکان خودرو گزینه‌های نمایان بودن متفاوتی را مشخص می‌کنند

وقتی چندخطی‌های مسیر و مکان خودرو گزینه‌های نمایان بودن متفاوتی دارند، مکان خودرو فقط زمانی نمایان است که هر دو گزینه نمایان بودن آن‌ها برآورده شده باشد. مجدداً، رؤیت‌پذیری چندخطی تابع قوانین رؤیت‌پذیری خودرو است:

  • همیشه نمایان: چندخطی مسیر باید از گزینه رؤیت‌پذیری همیشه نمایان استفاده کند، وقتی مکان خودرو نیز همان گزینه رؤیت‌پذیری همیشه نمایان را ارائه می‌دهد.
  • هرگز نمایان نباشد: چندخطی مسیر باید از گزینه نمایان بودن هرگز نمایان نباشد استفاده کند وقتی مکان خودرو از گزینه نمایان بودن هرگز نمایان نباشد استفاده می‌کند.

نمونه‌ای در زیر آمده است:

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

در این مثال، مکان خودرو فقط درصورتی قابل‌مشاهده است که تعداد توقف‌های باقی‌مانده حداقل ۳ و مسافت رانندگی باقی‌مانده حداقل ۳۰۰۰ متر باشد.

نمونه سفارشی‌سازی رؤیت‌پذیری تکلیف

مثال‌های زیر نحوه تنظیم تکلیف با قوانین رؤیت‌پذیری زیر را نشان می‌دهد:

  • اگر خودرو در فاصله ۳ ایستگاه باشد، چندخطی‌های مسیر را نشان دهید.
  • اگر مسافت رانندگی باقی‌مانده کمتر از ۵۰۰۰ متر است، زمان تخمینی رسیدن را نشان دهید.
  • تعداد ایستگاه‌های باقی‌مانده هرگز نشان داده نشود.
  • هر فیلد دیگر رؤیت‌پذیری پیش‌فرض را حفظ می‌کند تا زمانی‌که خودرو در فاصله ۵ ایستگاه از تکلیف باشد نشان داده شود.

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;
}

استراحت

برای تنظیم پنجره پیکربندی نمای ردگیری تکلیف بااستفاده از 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

قدم بعدی چیست