Utwórz zadania związane z dostawą

Ten dokument zakłada, że przeczytano przewodnik wprowadzający do zadań zaplanowanych w sekcji Wprowadzenie do Fleet Engine oraz artykuł Co to jest zadanie zaplanowane? w tej sekcji.

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

  • Zadania związane z dostawą: używaj ich w przypadku zadań związanych z jazdą, w tym z odbiorem i dostawą przesyłek.
  • Zadania związane z niedostępnością: używaj ich w przypadku, gdy kierowcy są niedostępni, np. podczas wymaganych przerw.
  • Zadania związane z zaplanowanym przystankiem: używaj ich w przypadku zadań niezwiązanych z jazdą w skrzynkach pocztowych lub lokalizacjach klientów, np. na wejście do budynku lub znalezienie punktu dostawy.

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

Pola zadań związanych z dostawą

W tej sekcji opisujemy pola zadań wymagane zarówno w przypadku zadań odbioru, jak i dostawy.

Wymagane pola zadań

W przypadku każdego zadania utworzonego w Fleet Engine musisz podać wymagane pola, ale 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 element 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 identyfikatorów zadań w swoim systemie, możesz wygenerować uniwersalny unikalny identyfikator (UUID). Szczegółowe informacje znajdziesz w artykule Identyfikatory zadań.
tracking_id PICKUP lub DELIVERY tylko zadania: Numer lub identyfikator używany do śledzenia przesyłki. Nie podawaj tego pola w przypadku zadań niezwiązanych z dostawą.
planned_location PICKUP, DELIVERY, lub SCHEDULED_STOP zadania tylko: lokalizacja, w której ma zostać wykonane zadanie. Nie jest wymagane w przypadku UNAVAILABLE zadań.
task_duration Przewidywany czas potrzebny na wykonanie zadania. Na przykład na znalezienie miejsca parkingowego lub dojście do miejsca przekazania.

Opcjonalne pola zadań związanych z dostawą

PoleWartość
target_time_window Okienko czasowe, w którym zadanie powinno zostać wykonane. To pole nie wpływa na sposób wyznaczania trasy.
task_tracking_view_config PICKUP lub DELIVERY tylko zadania: konfiguracja śledzenia zadań, która określa, które elementy danych są widoczne dla użytkowników końcowych i w jakich okolicznościach.
attributes Lista niestandardowych atrybutów zadania. Każdy atrybut musi mieć unikalny klucz.

Tworzenie zadania odbioru przesyłki

Aby śledzić aktywność kierowcy odbierającego przesyłkę za pomocą Fleet Engine, utwórz zadanie odbioru przesyłki. W tym celu ustaw atrybut 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 lub jak wysłać żądanie HTTP REST do CreateTask.

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, wyślij żądanie 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 sekcji Role kont usługi i tokeny JSON Web.

Treść żądania musi zawierać encję Task z odpowiednimi polami opisanymi w Pola zadań związanych z dostawą.

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. W tym celu ustaw atrybut 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 lub jak wysłać żądanie HTTP REST do CreateTask.

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, wyślij żądanie 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 sekcji Role kont usługi i tokeny JSON Web.

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
 ```

Co dalej?