Utwórz zadania związane z dostawą

W tym dokumencie zakładamy, że znasz już przewodnik wprowadzający do [zaplanowanych zadań][1] w sekcji Wprowadzenie do Fleet Engine oraz [Co to jest zaplanowane zadanie?][2] w tej sekcji.

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

  • Zadania związane z przesyłkami: używaj do zadań związanych z jazdą, w tym do odbioru i dostawy przesyłek.
  • Zadania związane z niedostępnością: używaj ich, gdy 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 związane z wysyłką. Informacje o innych typach zadań znajdziesz w artykule Tworzenie innych typów zadań.

Pola zadania dostawy

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

Pola wymagane w przypadku zadań

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

PoleWartość
type

Ustaw 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). Więcej informacji znajdziesz w sekcji Identyfikatory zadań.
tracking_id Tylko zadania 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 Tylko zadania PICKUP, DELIVERY lub SCHEDULED_STOP: lokalizacja, w której zadanie ma zostać wykonane. 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 zadanie powinno zostać ukończone. To pole nie wpływa na sposób kierowania.
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 i 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. Obejmuje to ustawienie 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 z wartością Bearer <token>, gdzie <token> jest wystawiany przez serwer zgodnie z wytycznymi opisanymi w sekcjach [Role konta usługi][6] i [Tokeny internetowe JSON][7].

Treść żądania musi zawierać encję Task z odpowiednimi polami opisanymi w sekcji [Pola 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 gRPC w języku Java][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ć encję 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