Versandaufgaben erstellen

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

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

  • Lieferaufgaben: Verwenden Sie diese für Fahraufgaben, einschließlich Abholung und Zustellung von Sendungen.
  • Tasks für Nichtverfügbarkeit: Verwenden Sie diese, wenn Fahrer nicht verfügbar sind, z. B. während vorgeschriebener Pausen.
  • Aufgaben für geplante Haltestellen: Verwenden Sie diese für Aufgaben, die nicht mit dem Fahren zu tun haben, an Abholstellen oder Kundenstandorten, z. B. die Zeit, die zum Betreten eines Gebäudes oder zum Auffinden eines Lieferorts benötigt wird.

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

Felder für Versandaufgaben

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

Pflichtfelder für Aufgaben

Für jede Aufgabe, die Sie in Fleet Engine erstellen, müssen Sie die erforderlichen Felder ausfüllen. Optionale Felder können Sie ebenfalls angeben. Die Fleet Engine ignoriert alle anderen Felder und wirft eine Ausnahme aus, wenn in einer Anfrage zur Aufgabenerstellung eine zugewiesene deliveryVehicleId angegeben ist. Verwenden Sie UpdateDeliveryVehicleRequest, um einem Fahrzeug Aufgaben zuzuweisen. Weitere Informationen finden Sie unter Aufgaben aktualisieren.

FeldWert
type

Legen Sie den Wert für den Aufgabentyp fest. Mögliche Werte sind:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id Eindeutige Aufgaben-ID. Dies darf nicht die Tracking-Nummer der Sendung sein. Wenn Sie keine Aufgaben-IDs in Ihrem System haben, können Sie eine universell eindeutige Kennung (Universally Unique Identifier, UUID) generieren. Weitere Informationen finden Sie unter Aufgaben-IDs.
tracking_id Nur PICKUP- oder DELIVERY-Aufgaben: Die Nummer oder Kennung, mit der Sie eine Sendung verfolgen. Geben Sie dieses Feld für Aufgaben, die nicht mit dem Versand zusammenhängen, nicht an.
plannedLocation Nur Aufgaben vom Typ PICKUP, DELIVERY oder SCHEDULED_STOP: Der Ort, an dem die Aufgabe erledigt werden soll. Nicht erforderlich für UNAVAILABLE-Aufgaben.
taskDuration Die voraussichtliche Zeit, die für die Erledigung der Aufgabe benötigt wird. Zum Beispiel, um nach einem Parkplatz zu suchen oder zum Übergabeort zu laufen.

Optionale Felder für Versandaufgaben

FeldWert
targetTimeWindow Das Zeitfenster, in dem die Aufgabe erledigt werden soll. Dieses Feld hat keinen Einfluss auf das Routingverhalten.
task_tracking_view_config Nur PICKUP- oder DELIVERY-Aufgaben: Mit dieser Konfiguration für das Aufgaben-Tracking wird festgelegt, welche Datenelemente für die Endnutzer unter welchen Umständen 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äten eines Fahrers verfolgen möchten, der eine Sendung abholt, erstellen Sie eine Aufgabe für die Sendungsabholung. Dazu müssen Sie das Attribut „Task type“ (Aufgabentyp) auf PICKUP festlegen. Das folgende Beispiel zeigt die Abholung einer Sendung in 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 aus einer Serverumgebung erstellen möchten, führen Sie einen HTTP-REST-Aufruf an CreateTask aus:

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

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

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten. Dabei wird <token> von deinem Server gemäß den in den Abschnitten Dienstkontorollen und JSON Webtokens beschriebenen Richtlinien ausgestellt.

Der Anfragetext muss ein Task-Objekt mit den entsprechenden Feldern enthalten, die unter Felder für Versandaufgaben beschrieben sind.

Beispiel eines curl-Befehls:

 # 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 Lieferung 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 „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 aus einer Serverumgebung erstellen möchten, führen Sie einen HTTP-REST-Aufruf an CreateTask aus:

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

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

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten. Dabei wird <token> von deinem Server gemäß den in den Abschnitten Dienstkontorollen und JSON Webtokens beschriebenen Richtlinien ausgestellt.

Der Anfragetext muss eine Task-Entität enthalten:

Beispiel eines curl-Befehls:

 # 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