Создание задач по доставке

Предполагается, что вы прочитали вводное руководство по [запланированным задачам][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.

В примерах ниже показано, как создать задачу по забору груза с помощью [библиотеки gRPC для Java][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> – уникальный идентификатор задачи.

Заголовок запроса должен содержать поле Authorization со значением 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

Создание задачи по доставке груза

Чтобы отслеживать действия водителя, доставляющего груз, создайте задачу доставки груза. Для этого нужно задать атрибуту task type значение DELIVERY. В примере ниже показана доставка в торговый центр Grand Indonesia East Mall.

В примерах ниже показано, как создать задачу по забору груза с помощью [библиотеки gRPC для Java][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> – уникальный идентификатор задачи.

Заголовок запроса должен содержать поле Authorization со значением 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