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

این سند فرض می‌کند که راهنمای مقدماتی [تکالیف زمان‌بندی‌شده][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;
  }

استراحت

برای ایجاد تکلیف تحویل‌گیری محموله از محیط سرور، با CreateTask تماس HTTP REST برقرار کنید:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> شناسه یکتای تکلیف است.

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

بدنه درخواست باید حاوی نهاد 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 می‌شود. مثال زیر تحویل محموله به 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;
  }

استراحت

برای ایجاد تکلیف تحویل‌گیری محموله از محیط سرور، با CreateTask تماس HTTP REST برقرار کنید:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> شناسه یکتای تکلیف است.

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

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