Utwórz zadania związane z dostawą

Zakładamy, że znasz już przewodnik wprowadzający do zaplanowanych zadań w sekcji Wprowadzenie do Fleet Engine, a także Czym jest zaplanowane zadanie? w tej sekcji.

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

  • Zadania związane z przesyłkami: używaj ich do zadań związanych z jazdą, 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 związane z wysyłką. 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.

Pola wymagane w przypadku zadań

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 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 – tylko zadania: miejsce, w którym ma zostać wykonane zadanie. Nie jest wymagane w przypadku zadań UNAVAILABLE.
task_duration Oczekiwany czas potrzebny na wykonanie zadania. Możesz na przykład 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 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 w jakich okolicznościach.
attributes Lista atrybutów zadań niestandardowych. 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. 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 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, 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> to token wydany przez serwer zgodnie z wytycznymi opisanymi w sekcjach Role konta usługi i Tokeny JSON Web.

Treść żądania musi zawierać encję Task z odpowiednimi polami opisanymi w sekcji Pola zadania dostawy.

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 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, 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> to token wydany przez serwer zgodnie z wytycznymi opisanymi w sekcjach Role konta usługi i Tokeny JSON Web.

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

Co dalej?