ایجاد تکالیف ارسال

این سند فرض می‌کند که راهنمای مقدماتی [تکالیف زمان‌بندی‌شده][1] را در بخش مقدمه‌ای بر Fleet Engine و همچنین [تکلیف زمان‌بندی‌شده چیست؟][2] را در این بخش خوانده‌اید.

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][4] تکلیف تحویل محموله ایجاد کنید یا چگونه درخواست HTTP REST به [CreateTask][5] ارسال کنید.

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> شناسه یکتای تکلیف است.

سرایند درخواست باید حاوی فیلد مجوز با مقدار Bearer <token> باشد، که در آن <token> توسط سرور شما طبق دستورالعمل‌های شرح‌داده‌شده در [نقش‌های حساب سرویس][6] و [نشان‌های وب JSON][7] صادر می‌شود.

بدنه درخواست باید حاوی موجودیت Task با فیلدهای مناسب شرح‌داده‌شده در [فیلدهای تکلیف ارسال][8] باشد.

نمونه فرمان 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 است. مثال زیر تحویل محموله به Grand Indonesia East Mall را نشان می‌دهد.

مثال‌های زیر نشان می‌دهند که چگونه بااستفاده از [کتابخانه Java gRPC][4] تکلیف تحویل محموله ایجاد کنید یا چگونه درخواست HTTP REST به [CreateTask][5] ارسال کنید.

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> شناسه یکتای تکلیف است.

سرایند درخواست باید حاوی فیلد مجوز با مقدار Bearer <token> باشد، که در آن <token> توسط سرور شما طبق دستورالعمل‌های شرح‌داده‌شده در [نقش‌های حساب سرویس][6] و [نشان‌های وب JSON][7] صادر می‌شود.

بدنه درخواست باید حاوی نهاد 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
 ```

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

قدم بعدی چیست

  • [ایجاد انواع دیگر تکلیف][13]
  • [به‌روزرسانی تکالیف][3]

[1]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [2]: /maps/documentation/mobility/fleet-engine/journeys/tasks [3]: update-tasks [4]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks#java [5]: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/create [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts [7]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt [8]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks#shipment_task_fields [13]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-other-tasks