Versandaufgaben erstellen

In diesem Dokument wird davon ausgegangen, dass Sie den Einführungsleitfaden zu geplanten Aufgaben im Abschnitt Einführung in Fleet Engine und den Abschnitt Was ist eine geplante Aufgabe? in diesem Abschnitt gelesen haben.

Fleet Engine für geplante Aufgaben bietet verschiedene allgemeine Aufgabenkategorien:

  • Versandaufgaben: Für Fahraufgaben, einschließlich Abholung und Zustellung von Sendungen.
  • Aufgaben für Nichtverfügbarkeit: Für Zeiten, in denen Fahrer nicht verfügbar sind, z. B. bei erforderlichen Pausen.
  • Aufgaben für geplante Stopps: Für Aufgaben, die nicht mit dem Fahren zusammenhängen, z. B. an Abgabestellen oder Kunden standorten, z. B. Zeit für den Eintritt in ein Gebäude oder die Suche nach einer Zustelladresse.

In diesem Dokument wird beschrieben, wie Sie Versandaufgaben auf Ihrem Server erstellen. Informationen zu anderen Aufgabentypen finden Sie unter Andere Aufgabentypen erstellen.

Felder für Versandaufgaben

In diesem Abschnitt werden die Aufgabenfelder dokumentiert, die sowohl für Abhol- als auch für Zustellaufgaben erforderlich sind.

Erforderliche Aufgabenfelder

Für jede Aufgabe, die Sie in Fleet Engine erstellen, müssen Sie die Pflichtfelder angeben. Sie können auch alle optionalen Felder angeben. Fleet Engine ignoriert alle anderen Felder und löst eine Ausnahme aus, wenn in einer Anfrage zur Aufgabenerstellung eine zugewiesene deliveryVehicleId angegeben wird. Verwenden Sie UpdateDeliveryVehicleRequest, um Aufgaben einem Fahrzeug zuzuweisen. Weitere Informationen finden Sie unter Aufgaben aktualisieren.

FeldWert
type

Legen Sie den Typ fest, der dem Aufgabentyp entspricht. Das ist einer der folgenden Typen:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id Eindeutige Aufgaben-ID. Dies darf nicht die Sendungsnummer für die Sendung sein. Wenn Sie in Ihrem System keine Aufgaben-IDs haben, können Sie eine universell eindeutige Kennung (Universally Unique Identifier, UUID) generieren. Weitere Informationen finden Sie unter Aufgaben-IDs.
tracking_id PICKUP oder DELIVERY Aufgaben nur: Die Nummer oder ID, die Sie zum Verfolgen einer Sendung verwenden. Geben Sie dieses Feld nicht für Aufgaben an, die keine Sendungen betreffen.
planned_location PICKUP, DELIVERY oder SCHEDULED_STOP Aufgaben only: The Ort, an dem die Aufgabe ausgeführt werden soll. Für UNAVAILABLE Aufgaben nicht erforderlich.
task_duration Die voraussichtliche Zeit, die für die Ausführung der Aufgabe benötigt wird. Zum Beispiel, um einen Parkplatz zu suchen oder zum Übergabeort zu gehen.

Optionale Felder für Versandaufgaben

FeldWert
target_time_window Das Zeitfenster, in dem die Aufgabe ausgeführt werden soll. Dieses Feld hat keine Auswirkungen auf das Routingverhalten.
task_tracking_view_config PICKUP oder DELIVERY Aufgaben: Die Konfiguration für die Aufgabenverfolgung, in der festgelegt wird, welche Datenelemente unter welchen Umständen für Endnutzer sichtbar sind.
attributes Eine Liste benutzerdefinierter Aufgabenattribute. Jedes Attribut muss einen eindeutigen Schlüssel haben.

Aufgabe für die Abholung einer Sendung erstellen

Wenn Sie mit Fleet Engine die Aktivität eines Fahrers verfolgen möchten, der eine Sendung abholt, erstellen Sie eine Aufgabe für die Abholung einer Sendung. Dazu müssen Sie das Attribut für den Aufgabentyp auf PICKUP festlegen. Das folgende Beispiel zeigt die Abholung einer Sendung aus der Grand Indonesia East Mall.

In den folgenden Beispielen wird gezeigt, wie Sie mit der Java gRPC-Bibliothek eine Aufgabe für die Abholung einer Sendung erstellen oder eine HTTP-REST-Anfrage an CreateTask senden.

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

Wenn Sie eine Aufgabe für die Abholung einer Sendung in einer Serverumgebung erstellen möchten, senden Sie einen HTTP-REST-Aufruf an CreateTask:

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

<id> ist eine eindeutige ID für die Aufgabe.

Der Anfrageheader muss ein Feld Authorization mit dem Wert Bearer <token> enthalten. <token> wird von Ihrem Server gemäß den Richtlinien unter Dienstkontorollen und JSON-Web Tokens ausgestellt.

Der Anfragetext muss eine Task-Entität mit den entsprechenden Feldern enthalten, die unter Felder für Versandaufgaben beschrieben sind.

Beispiel für einen curl-Befehl:

 # 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

Aufgabe für die Zustellung einer Sendung erstellen

Wenn Sie mit Fleet Engine die Aktivität eines Fahrers verfolgen möchten, der eine Sendung zustellt, erstellen Sie eine Aufgabe für die Zustellung einer Sendung. Dazu müssen Sie das Attribut für den Aufgabentyp auf DELIVERY festlegen. Das folgende Beispiel zeigt die Zustellung einer Sendung an die Grand Indonesia East Mall.

In den folgenden Beispielen wird gezeigt, wie Sie mit der Java gRPC-Bibliothek eine Aufgabe für die Abholung einer Sendung erstellen oder eine HTTP-REST-Anfrage an CreateTask senden.

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

Wenn Sie eine Aufgabe für die Abholung einer Sendung in einer Serverumgebung erstellen möchten, senden Sie einen HTTP-REST-Aufruf an CreateTask:

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

<id> ist eine eindeutige ID für die Aufgabe.

Der Anfrageheader muss ein Feld Authorization mit dem Wert Bearer <token> enthalten. <token> wird von Ihrem Server gemäß den Richtlinien unter Dienstkontorollen und JSON-Web Tokens ausgestellt.

Der Anfragetext muss eine Task-Entität enthalten:

Beispiel für einen curl-Befehl:

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

Nächste Schritte