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 artykuł [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łką: 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 zatrzymaniem: używaj do zadań niezwiązanych z jazdą, takich jak czas na wejście do budynku lub zlokalizowanie punktu dostawy.

Z tego dokumentu dowiesz się, jak tworzyć zadania związane z przesyłką na serwerze. Informacje o innych typach zadań znajdziesz w artykule Tworzenie innych typów zadań.

Pola zadania związanego z przesyłką

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

Wymagane pola zadania

W przypadku każdego zadania tworzonego w Fleet Engine musisz podać wymagane pola. Możesz też podać dowolne pola opcjonalne. Fleet Engine ignoruje wszystkie inne 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, który odpowiada typowi zadania, czyli jeden z tych:

  • 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 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 związanego z przesyłką

PoleWartość
target_time_window Przedział czasu, w którym zadanie powinno zostać ukończone. To pole nie wpływa na działanie routingu.
task_tracking_view_config Tylko zadania PICKUP lub DELIVERY: konfiguracja śledzenia zadań, która określa, jakie elementy danych są widoczne dla użytkowników i w jakich okolicznościach.
attributes Lista niestandardowych atrybutów zadań. Każdy atrybut musi mieć unikalny klucz.

Tworzenie zadania odbioru przesyłki

Aby używać Fleet Engine do śledzenia aktywności 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 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.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 ze środowiska serwera, wykonaj wywołanie HTTP REST do 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 wydawany przez serwer zgodnie z wytycznymi opisanymi w sekcjach [Role kont usługi][6] i [Tokeny internetowe JSON][7].

Treść żądania musi zawierać encję Task z odpowiednimi polami opisanymi w sekcji [Pola zadania związanego z przesyłką][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 używać Fleet Engine do śledzenia aktywności kierowcy dostarczającego przesyłkę, 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 ze środowiska serwera, wykonaj wywołanie HTTP REST do 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 wydawany przez serwer zgodnie z wytycznymi opisanymi w sekcjach [Role kont usługi][6] i [Tokeny internetowe 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