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

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

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

Как создать задачу по доставке посылки

Чтобы использовать Fleet Engine для отслеживания действий водителя, доставляющего груз, создайте задачу по доставке груза. Для этого нужно задать атрибуту типа задачи значение 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