Utwórz zadania związane z dostawą

Zakładamy, że znasz już wprowadzenie do [zaplanowanych zadań][1] w sekcji Wprowadzenie do Fleet Engine oraz [co to jest zaplanowane zadanie?][2] w tej sekcji.

Fleet Engine w przypadku zaplanowanych zadań udostępnia różne ogólne kategorie zadań:

  • Zadania związane z przesyłkami: używaj ich do zadań związanych z prowadzeniem pojazdu, w tym do odbioru i dostawy przesyłek.
  • Zadania związane z niedostępnością: używaj ich w przypadku okresów, w których kierowcy są niedostępni, np. podczas wymaganych przerw.
  • Zaplanowane zadania związane z przystankami: używaj ich w przypadku zadań niezwiązanych z prowadzeniem pojazdu w skrzynkach pocztowych lub lokalizacjach klientów, takich jak czas potrzebny na wejście do budynku lub znalezienie punktu dostawy.

Z tego dokumentu dowiesz się, jak tworzyć na serwerze zadania dostawy. Informacje o innych typach zadań znajdziesz w artykule Tworzenie innych typów zadań.

Pola zadania dostawy

W tej sekcji opisujemy pola zadań wymagane w przypadku zadań odbioru i dostawy.

Wymagane pola zadania

W przypadku każdego zadania utworzonego w Fleet Engine musisz podać wymagane pola, a także możesz podać dowolne pola opcjonalne. Fleet Engine ignoruje wszystkie pozostałe pola i zgłasza wyjątek, jeśli w żądaniu utworzenia zadania podano przypisany deliveryVehicleId. Aby przypisać zadania do pojazdu, użyj UpdateDeliveryVehicleRequest. Więcej informacji znajdziesz w artykule Aktualizowanie zadań.

PoleWartość
type

Ustaw na typ pasujący do typu zadania, czyli jeden z tych typów:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id Unikalny identyfikator zadania. Nie może to być numer śledzenia przesyłki. Jeśli nie masz w systemie identyfikatorów zadań, możesz wygenerować unikalny identyfikator uniwersalny (UUID). Szczegółowe informacje znajdziesz w sekcji Identyfikatory zadań.
tracking_id PICKUP lub DELIVERY: numer lub identyfikator używany do śledzenia przesyłki. Nie podawaj tego pola w przypadku zadań niezwiązanych z przesyłką.
planned_location PICKUP, DELIVERY lub SCHEDULED_STOP: miejsce, w którym ma zostać wykonane zadanie. Nie jest wymagane w przypadku zadań UNAVAILABLE.
task_duration Oczekiwany czas potrzebny na wykonanie zadania. Na przykład, aby poszukać parkingu lub dojść do miejsca przekazania.

Opcjonalne pola zadania dostawy

PoleWartość
target_time_window Przedział czasu, w którym należy wykonać zadanie. To pole nie ma wpływu na routing.
task_tracking_view_config Tylko zadania PICKUP lub DELIVERY: konfiguracja śledzenia zadań, która określa, które elementy danych są widoczne dla użytkowników w jakich okolicznościach.
attributes Lista atrybutów zadań niestandardowych. Każdy atrybut musi mieć unikalny klucz.

Tworzenie zadania odbioru przesyłki

Aby śledzić za pomocą Fleet Engine aktywność kierowcy odbierającego przesyłkę, utwórz zadanie odbioru przesyłki. Wymaga to ustawienia atrybutu typu zadania na PICKUP. Poniższy przykład ilustruje odbiór przesyłki z centrum handlowego Grand Indonesia East Mall.

Poniższe przykłady pokazują, jak utworzyć zadanie odbioru przesyłki za pomocą [biblioteki Java gRPC][4] lub jak wysłać żądanie HTTP REST do [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

Aby utworzyć zadanie odbioru przesyłki w środowisku serwera, wywołaj interfejs HTTP REST pod adresem CreateTask:

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

<id> to unikalny identyfikator zadania.

Nagłówek żądania musi zawierać pole Authorization o wartości Bearer <token>, gdzie <token> jest tokenem wydanym przez serwer zgodnie z wytycznymi opisanymi w [rolach kont usługi][6] i [tokenach internetowych JSON][7].

Treść żądania musi zawierać obiekt Task z odpowiednimi polami opisanymi w [polach zadania dostawy][8].

Przykładowe polecenie 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

Tworzenie zadania dostawy przesyłki

Aby śledzić aktywność kierowcy dostarczającego przesyłkę za pomocą Fleet Engine, utwórz zadanie dostawy przesyłki. Wymaga to ustawienia atrybutu typu zadania na DELIVERY. Poniższy przykład ilustruje dostawę przesyłki do centrum handlowego Grand Indonesia East Mall.

Poniższe przykłady pokazują, jak utworzyć zadanie odbioru przesyłki za pomocą [biblioteki Java gRPC][4] lub jak wysłać żądanie HTTP REST do [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

Aby utworzyć zadanie odbioru przesyłki w środowisku serwera, wywołaj interfejs HTTP REST pod adresem CreateTask:

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

<id> to unikalny identyfikator zadania.

Nagłówek żądania musi zawierać pole Authorization o wartości Bearer <token>, gdzie <token> jest tokenem wydanym przez serwer zgodnie z wytycznymi opisanymi w [rolach kont usługi][6] i [tokenach internetowych JSON][7].

Treść żądania musi zawierać element Task:

Przykładowe polecenie 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

Co dalej?

  • [Tworzenie innych typów zadań][13]
  • [Aktualizowanie zadań][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