Erste Schritte mit Fleet Engine

Mit der Fleet Engine Deliveries API können Sie Ihre Flottenaktivitäten für die erste und letzte Meile von Lieferungen modellieren. Die Deliveries API wird über das Driver SDK für Android und iOS bereitgestellt und kann auch direkt über HTTP REST- oder gRPC-Aufrufe verwendet werden.

Ersteinrichtung

Die Fleet Engine Deliveries API wird über die Google Cloud Console konfiguriert. Informationen zu den Schritten in der Console und zum Erstellen eines JSON-Webtokens für die Autorisierung finden Sie unter Authentifizierung und Autorisierung. Weitere Informationen zur Verwendung der Console finden Sie in der Dokumentation zur Google Cloud Console.

Einrichtung überprüfen

Nachdem Sie die Dienstkonten erstellt haben, sollten Sie prüfen, ob die Einrichtung abgeschlossen ist und Sie ein Lieferfahrzeug erstellen können. Durch die Überprüfung in dieser Phase des Workflows können Sie häufige Autorisierungsprobleme beheben, die beim Einrichten Ihres Projekts auftreten können. Folgen Sie der Anleitung unter Einrichtung überprüfen. In diesem Leitfaden wird beschrieben, wie Sie mit dem gcloud-Befehlszeilendienstprogramm zwei wichtige Teile Ihrer Einrichtung testen können: das Signieren eines Autorisierungstokens und das Erstellen eines Testfahrzeugs.

Alternativ können Sie Ihre Einrichtung mit den Beispielskripts für die Authentifizierung von Fleet Engine testen.

Clientbibliotheken

Wir veröffentlichen Clientbibliotheken in verschiedenen gängigen Programmiersprachen. Diese Bibliotheken bieten eine bessere Entwicklungsumgebung im Vergleich zu REST- oder gRPC-Rohdaten. Eine Anleitung zum Abrufen von Clientbibliotheken für Ihre Serveranwendung finden Sie unter Clientbibliotheken.

Bei den Java-Beispielen in dieser Dokumentation wird davon ausgegangen, dass Sie mit gRPC vertraut sind.

Datenstrukturen

Die Deliveries API verwendet zwei Datenstrukturen, um die Abholung und Lieferung von Lieferungen zu modellieren:

• Das Lieferfahrzeug, das für den Transport der Sendung verwendet wird.
• Die Abholung und Zustellung der Sendung.

Darüber hinaus können Sie Aufgaben verwenden, um Fahrerpausen und geplante Haltestellen den ganzen Tag über zu modellieren.

Lieferfahrzeuge

Lieferfahrzeuge transportieren Lieferungen von einem Depot zu einem Lieferort und von einem Abholort zum Lager. In bestimmten Fällen können sie eine Sendung auch direkt von der Abholstelle zum Lieferort bringen.

Sie können das Driver SDK verwenden, um ein DeliveryVehicle-Objekt in Fleet Engine zu erstellen und Standortaktualisierungen für den Versand und die Flottenverfolgung zu senden.

Tasks

Jedem Fahrzeug sind Aufgaben zugewiesen. Dazu können Abhol- oder Lieferaufgaben, erforderliche Pausen für Fahrer oder geplante Haltestellen an Abgabe- oder Kundenstandorten gehören. Jede Aufgabe muss eine eindeutige Aufgaben-ID haben, kann aber dieselbe Tracking-ID haben. Die Aufgaben und die Reihenfolge, in der sie geplant sind, werden verwendet, um ETA-Fenster für jede Aufgabe zu berechnen.

Mit dem Task-Manager des Driver SDK können Sie Aufgaben in Fleet Engine erstellen.

Versandaufgaben

Versandaufgaben beziehen sich auf die Abholung oder Abgabe der Sendung. Sie müssen eine Verfolgungsnummer oder ID angeben, wenn Sie eine Versandaufgabe erstellen. Sie müssen auch eine Verweildauer angeben, um zusätzliche Zeit für die Erledigung der Aufgabe, die Suche nach Parkplätzen oder den Weg zum Übergabepunkt zu berücksichtigen.

• Erstellen Sie eine Abholaufgabe zum Abholen einer Sendung. Geben Sie dazu den Abholort und die Verfolgungsnummer oder ID an.
• Erstellen Sie eine Lieferaufgabe für die Zustellung einer Sendung, indem Sie den Lieferort und die Verfolgungsnummer oder -ID angeben.

Nichtverfügbarkeitsaufgaben

Erstellen Sie eine Nichtverfügbarkeitsaufgabe für einen Zeitraum, in dem das Fahrzeug nicht für Abholungen oder Lieferungen verfügbar ist. Dies kann eine Pause zum Tanken des Fahrzeugs oder eine Pause für den Fahrer sein. Geben Sie die Länge der Unterbrechung an, wenn Sie die Aufgabe erstellen. Pausen müssen nicht an einem bestimmten Ort eingelegt werden, aber durch die Angabe eines Ortes erhältst du genauere voraussichtliche Ankunftszeitenfenster während des Tages.

Bei einer Nichtverfügbarkeitsaufgabe werden keine Standortinformationen mit einem Endnutzer geteilt. Beispielsweise wird der Standort des Lieferfahrzeugs mithilfe der Flottenverfolgungsbibliothek vor Flottenmanagern verborgen.

Geplante Stoppaufgaben

Erstellen Sie geplante Haltestellenaufgaben, um die Haltestellen zu modellieren, die von einem Lieferfahrzeug angefahren werden. Sie können beispielsweise eine geplante Haltestelle für eine tägliche Haltestelle einer Abholung an einem bestimmten Ort erstellen, unabhängig von anderen Lieferungen oder Abholungen am selben Ort. Sie können auch geplante Haltestellenaufgaben für Sammlungen aus Ablageboxen oder zum Modellieren von Zubringer-Fahrzeugen oder Haltestellen in Servicezentren und Servicepunkten erstellen.

Die spezifischen Felder in den einzelnen Datenstrukturen finden Sie in der API-Referenzdokumentation für DeliveryVehicle (gRPC, REST) und Task (gRPC, REST).

• IDs müssen gültige Unicode-Strings sein.
• IDs dürfen maximal 64 Zeichen lang sein.
• IDs werden gemäß der Unicode-Normalisierungsform C normalisiert.
• IDs dürfen keine der folgenden ASCII-Zeichen enthalten: "/", ":", "\", "?" oder "#".

Im Folgenden finden Sie einige Beispiele für gute Aufgaben-IDs:

• 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
• e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38.
• NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk

Die folgende Tabelle enthält Beispiele für ungültige Aufgaben-IDs:

Lebensdauer eines Fahrzeugs

Das DeliveryVehicle-Objekt steht für ein Lieferfahrzeug für die erste oder letzte Meile. So erstellen Sie ein DeliveryVehicle-Objekt:

• Die Projekt-ID des Google Cloud-Projekts, das das Dienstkonto enthält, mit dem die Fleet Engine APIs aufgerufen werden.
• Eine Fahrzeug-ID des Kunden.

Fahrzeug-IDs müssen für jedes Fahrzeug eindeutig sein. Sie sollten nicht für ein anderes Fahrzeug wiederverwendet werden, es sei denn, es gibt keine aktiven Aufgaben für dieses Fahrzeug.

Prüfen Sie, ob der Fehler NOT_FOUND vorliegt, wenn Sie UpdateDeliveryVehicle aufrufen. Rufen Sie dann gegebenenfalls CreateDeliveryVehicle auf, um ein neues Fahrzeug zu erstellen. Ein DeliveryVehicle-Objekt, das nicht mit UpdateDeliveryVehicle aktualisiert wurde, wird nach sieben Tagen automatisch gelöscht. Wenn Sie CreateDeliveryVehicle mit einem bereits vorhandenen Paar aus Projekt-ID und Fahrzeug-ID aufrufen, wird ein Fehler generiert.

Fahrzeugattribute

Die Entität DeliveryVehicle enthält ein wiederkehrendes Feld von DeliveryVehicleAttribute. Die ListDeliveryVehicles API enthält ein filter-Feld, das die zurückgegebenen DeliveryVehicle-Entitäten auf die Entitäten mit den angegebenen Attributen beschränken kann. DeliveryVehicleAttributes haben keinen Einfluss auf das Fleet Engine-Routingverhalten.

Attribute dürfen keine personenidentifizierbaren oder vertraulichen Informationen enthalten, da dieses Feld für Nutzer sichtbar sein könnte.

Leben einer Aufgabe

Aufgaben in Fleet Engine können mithilfe der gRPC- oder REST-Schnittstellen der Deliveries API erstellt, aktualisiert und abgefragt werden.

Ein Task-Objekt hat ein Statusfeld, mit dem der Fortschritt im Lebenszyklus verfolgt werden kann. Die Werte bewegen sich von OPEN nach CLOSED. Neue Aufgaben werden im Status OPEN erstellt. Dies bedeutet, dass entweder:

• Die Aufgabe wurde noch keinem Lieferfahrzeug zugewiesen.
• Das Lieferfahrzeug hat die der Aufgabe zugewiesene Haltestelle noch nicht passiert.

Eine Aufgabe kann einem Fahrzeug nur zugewiesen werden, wenn es sich im Status OFFEN befindet.

Eine Aufgabe kann abgebrochen werden, indem sie aus der Liste der Fahrzeughaltestellen entfernt wird. Der Status wird dann automatisch auf GESCHLOSSEN gesetzt.

Wenn das Fahrzeug der Aufgabe die Haltestelle des Fahrzeugs der Aufgabe abschließt, aktualisieren Sie das Ergebnisfeld der Aufgabe auf ERFOLGREICH oder FEHLGESCHLAGEN und geben Sie den Zeitstempel des Ereignisses an. Das Aufgabenergebnis kann jederzeit vor oder nach Abschluss der Aufgabe festgelegt werden, aber nur einmal.

In der Bibliothek für das Tracking der JavaScript-Flotte kann dann das Ergebnis der Aufgabe angezeigt werden. Der Aufgabenstatus wird automatisch auf GESCHLOSSEN gesetzt. Weitere Informationen finden Sie unter Flotte mit der JavaScript-Flotten-Tracking-Bibliothek verfolgen.

Wie bei Fahrzeugen werden Aufgaben, die nach sieben Tagen noch nicht aktualisiert wurden, gelöscht. Wenn Sie versuchen, eine Aufgabe mit einer bereits vorhandenen ID zu erstellen, wird ein Fehler zurückgegeben.

Hinweis:Fleet Engine unterstützt das explizite Löschen von Aufgaben nicht. Der Dienst löscht Aufgaben automatisch nach sieben Tagen ohne Aktualisierungen. Wenn Sie Aufgabendaten länger als sieben Tage aufbewahren möchten, müssen Sie diese Funktion selbst implementieren.

Aufgabenattribute

Die Entität Task enthält ein wiederkehrendes Feld mit TaskAttribute, das einen Wert von einem der drei Typen enthalten kann: String, Zahl und boolescher Wert. Die ListTasks API enthält ein filter-Feld, das die zurückgegebenen Task-Entitäten auf die mit den angegebenen Attributen beschränken kann. TaskAttributes haben keinen Einfluss auf das Fleet Engine-Routingverhalten.

Attribute dürfen keine personenidentifizierbaren oder vertraulichen Informationen enthalten, da dieses Feld für Nutzer sichtbar sein könnte.

Lebenszyklus von Fahrzeugen und Aufgaben verwalten

Zur Verwaltung von Fahrzeug- und Aufgabenlebenszyklen in Ihrem System verwenden Sie die Fleet Engine Deliveries API, um Ihre Fahrzeuge und die zugehörigen Aufgaben zu erstellen, zu aktualisieren und zu verfolgen. Ihr internes System fungiert als vertrauenswürdige Quelle der Daten, die die Fleet Engine Deliveries API in Ihrem Namen erweitert.

Gleichzeitig kommuniziert die Treiberanwendung direkt mit der Fleet Engine, um den Gerätestandort und die Routeninformationen zu aktualisieren. Mit diesem Modell kann Fleet Engine den Echtzeitstandort effizient verwalten und direkt an die Tracking-Bibliothek senden, die Sie dann für Kunden verwenden können, die Statusaktualisierungen für ihre Bestellung benötigen.

Angenommen, Sie haben das folgende Szenario:

• Ein Fahrer nähert sich einer Lieferhaltestelle und Fleet Engine sendet den Gerätestandort an die Tracking-Bibliothek. Diese wird von Ihrer Nutzeranwendung verwendet, um den Nutzer über die Nähe seines Pakets zu informieren.
• Nachdem der Fahrer die Lieferung abgeschlossen hat, klickt er in der Treiberanwendung auf die Schaltfläche „Shipment delivered“ (Lieferung zugestellt).
• Dadurch werden die Informationen an Ihr Back-End-System gesendet, das die erforderlichen Schritte zur Unternehmensvalidierung und -überprüfung durchführt.
• Ihr System bestätigt die Aufgabe als ERFOLGREICH und aktualisiert Fleet Engine mithilfe der Deliveries API.

Das folgende Diagramm veranschaulicht diese Prozesse auf allgemeiner Ebene. Außerdem wird die Standardbeziehung zwischen Ihrem System, dem Client und Fleet Engine veranschaulicht.

Clienttoken-Verwaltung

Für alle Standortaktualisierungen, die von der Treiberanwendung stammen und direkt an Fleet Engine gesendet werden, sind Autorisierungstokens erforderlich. Der empfohlene Ansatz für die Verarbeitung von Aktualisierungen vom Client an Fleet Engine besteht darin, der Treiberanwendung ein Token mit begrenztem Umfang bereitzustellen, damit sie nur den Gerätestandort in Fleet Engine aktualisieren kann. Für diese Art von Token verwenden Sie die Dienstkontorolle Nicht vertrauenswürdiger Treibernutzer von Fleet Engine Delivery. Dadurch wird sichergestellt, dass Aufrufe von Mobilgeräten – also Umgebungen mit geringer Vertrauenswürdigkeit – initiiert werden, dem Prinzip der geringsten Berechtigung entsprechen.

Andere Dienstkontorollen

Wenn Sie stattdessen die Treiberanwendungen autorisieren möchten, direkte Aktualisierungen von Fleet Engine vorzunehmen, z. B. für bestimmte Aufgabenaktualisierungen, können Sie die Rolle „Vertrauenswürdiger Treiber“ verwenden, die über die Aktualisierungen der Rolle „Nicht vertrauenswürdiger Treiber“ hinausgehen. Informationen zu einem Modell, das die Rolle „Vertrauenswürdiger Treiber“ verwendet, finden Sie unter Modell vertrauenswürdiger Treiber.

Weitere Informationen zur Verwendung nicht vertrauenswürdiger und vertrauenswürdiger Treiberrollen finden Sie unter Cloud-Projekt einrichten.

Modellieren eines Arbeitstags

In der folgenden Tabelle wird beschrieben, wie ein Arbeitstag in einem Liefer- und Logistikunternehmen für Fahrer auf der ersten oder letzten Meile aussehen könnte. Ihr Unternehmen kann sich in den Details unterscheiden, aber Sie können sehen, wie Sie einen Arbeitstag modellieren könnten.

Informationen zu Standortaktualisierungen

Standortaktualisierungen werden an Fleet Engine gesendet, sobald sich ein Lieferfahrzeug auf dem Weg von einer Haltestelle (einschließlich des Depots) befindet, bis es an der nächsten Haltestelle eintrifft. Da diese Ereignisse nicht automatisch erkannt werden, müssen Sie sie programmatisch kennzeichnen. Verwenden Sie Bibliotheken, die Änderungen der Mobilitätsform erkennen, um das Senden der erforderlichen Benachrichtigungen an Fleet Engine auszulösen.

Standortaktualisierungen sollten ausgesetzt werden, wenn der Fahrer nicht fährt, da die Qualität der Standortsignale drastisch abnimmt, wenn sich jemand in einem Gebäude befindet.

Die Häufigkeit der Standortupdates kann im Driver SDK festgelegt werden. Standardmäßig werden Aktualisierungen alle 10 Sekunden gesendet.

Fahrzeughaltestellen und Lieferorte

Eine Haltestelle ist der Ort, an dem ein Lieferfahrzeug eine Versandaufgabe oder eine andere Aufgabe erledigt. Es ist entweder ein Zugangspunkt, z. B. eine Laderampe, oder ein an einer Straße eingerahmter Ort.

Der Lieferort ist der Ort, an dem die Sendung zugestellt oder abgeholt wird. Für die Fahrt zum und vom Lieferort sind möglicherweise einige Fußwege von der Fahrzeughaltestelle erforderlich.

Wenn ein Fahrer beispielsweise eine Sendung an ein Geschäft in einem Einkaufszentrum liefert, hält das Lieferfahrzeug auf dem Parkplatz des Einkaufszentrums in der Nähe des nächstgelegenen Ladeneingangs. Das ist die Haltestelle des Fahrzeugs. Der Fahrer geht dann von der Haltestelle zu dem Ort im Einkaufszentrum, an dem sich das Geschäft befindet. Dies ist der Lieferort.

Damit Ihre Nutzer die Sendungsverfolgung optimal nutzen können, sollten Sie überlegen, wie Sendungsaufgaben den Fahrzeugstopps zugewiesen werden. Denken Sie daran, dass die Anzahl der verbleibenden Fahrzeughaltestellen für Versandaufgaben dem Nutzer mitgeteilt wird, damit er den Fortschritt der Sendung sehen kann.

Wenn beispielsweise ein Fahrer viele Lieferungen an ein einzelnes Bürogebäude durchführt, empfiehlt es sich, alle Lieferaufgaben einer einzelnen Fahrzeughaltestelle zuzuweisen. Wenn jede Lieferaufgabe einer eigenen Fahrzeughaltestelle zugewiesen ist, wäre die Sendungsverfolgung für die Nutzer weniger hilfreich, da die Nachverfolgung erst verfügbar ist, wenn das Fahrzeug eine begrenzte Anzahl von Fahrzeugstopps vor seinem Ziel erreicht hat. Wenn viele Fahrzeugstopps in kurzer Zeit abgeschlossen werden, hat ein Nutzer nicht viel Zeit, den Fortschritt der Lieferung zu verfolgen.

Mobile SDKs verwenden

Bevor Sie das Treiber-SDK aufrufen, müssen Sie es initialisieren.

Delivery Driver API initialisieren

Du musst das Navigation SDK initialisieren, bevor du die Delivery Driver API im Driver SDK startest. Initialisieren Sie dann die Delivery Driver API, wie im folgenden Beispiel gezeigt:

static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";

NavigationApi.getNavigator(
   this, // Activity.
   new NavigatorListener() {
     @Override
     public void onNavigatorReady(Navigator navigator) {
       DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
         .setNavigator(navigator)
         .setProviderId(PROVIDER_ID)
         .setVehicleId(VEHICLE_ID)
         .setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
         .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
         .setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
         .setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
             Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
         .build));
     }

     @Override
     public void onError(int errorCode) {
       Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
     }
   });

Anwendungsfälle

In diesem Abschnitt wird beschrieben, wie du mit der Deliveries API häufige Anwendungsfälle modellieren kannst.

Eindeutige Entitäts-IDs

Format und Wert der in REST-Aufrufen verwendeten eindeutigen Entitätskennungen sind für Fleet Engine nicht transparent. Verwenden Sie IDs nicht automatisch und dürfen keine personenidentifizierbaren Informationen wie die Telefonnummer des Fahrers enthalten.

Fahrzeug erstellen

Sie können ein Fahrzeug entweder über das Driver SDK oder in der Serverumgebung erstellen.

gRPC

Zum Erstellen eines neuen Fahrzeugs senden Sie einen CreateDeliveryVehicle-Aufruf an Fleet Engine. Verwenden Sie das Objekt CreateDeliveryVehicleRequest, um die Attribute des neuen Lieferfahrzeugs zu definieren. Jeder für das Feld Name angegebene Wert wird gemäß der API-Anleitung für benutzerdefinierte IDs ignoriert. Verwenden Sie das Feld DeliveryVehicleId, um die ID des Fahrzeugs festzulegen.

Beim Erstellen einer DeliveryVehicle können Sie optional zwei Felder angeben:

• Attribute
• Letzter Standort

Alle anderen Felder dürfen nicht festgelegt werden. Andernfalls gibt Fleet Engine einen Fehler zurück, da diese Felder entweder schreibgeschützt sind oder nur über UpdateDeliveryVehicle-Aufrufe aktualisiert werden können.

Wenn Sie ein Fahrzeug erstellen möchten, ohne optionale Felder festzulegen, können Sie das Feld DeliveryVehicle in CreateDeliveryVehicleRequest nicht festlegen.

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek ein Fahrzeug erstellen:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
  .addAttributes(DeliveryVehicleAttribute.newBuilder()
    .setKey("route_number").setValue("1"))  // Opaque to the Fleet Engine
  .build();

// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
  CreateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setDeliveryVehicleId(VEHICLE_ID)     // Vehicle ID assigned by the Provider
      .setDeliveryVehicle(vehicle)
      .build();

// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.

try {
  DeliveryVehicle createdVehicle =
    deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Um ein Fahrzeug aus einer Serverumgebung zu erstellen, führen Sie einen HTTP REST-Aufruf an CreateDeliveryVehicle aus:

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

<id> ist eine eindeutige Kennung für ein Lieferfahrzeug in Ihrer Flotte.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der POST-Textkörper stellt die DeliveryVehicle-Entität dar, die erstellt werden soll. Sie können die folgenden optionalen Felder angeben:

• Attribute
• lastLocation

Beispiel eines curl-Befehls:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
  "attributes": [{"key": "model", "value": "sedan"}],
  "lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM

Fleet Engine ignoriert das Feld name der DeliveryVehicle-Entität gemäß API-Anleitung für benutzerdefinierte IDs. Alle anderen Felder dürfen nicht festgelegt werden. Andernfalls gibt Fleet Engine einen Fehler zurück, da diese Felder entweder schreibgeschützt sind oder nur über UpdateDeliveryVehicle-Aufrufe aktualisiert werden können.

Wenn Sie ein Fahrzeug erstellen möchten, ohne Felder festzulegen, können Sie den Text der POST-Anfrage leer lassen. Das neu erstellte Fahrzeug hat eine Fahrzeug-ID, die aus dem Parameter deliveryVehicleId in der POST-URL extrahiert wird.

Beispiel eines curl-Befehls:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}"

Aufgabe für die Abholung einer Sendung erstellen

Sie können eine Abholaufgabe entweder im Driver SDK oder in der Serverumgebung erstellen.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek eine Aufgabe zur Abholung einer Sendung erstellen:

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

Um eine Aufgabe zur Abholung der Sendung aus einer Serverumgebung zu erstellen, 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. Es darf sich nicht um die Verfolgungsnummer der Sendung handeln. Wenn in Ihrem System keine Aufgaben-IDs vorhanden sind, können Sie eine UUID (Universally Unique Identifier) generieren.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  eingeben	Typ.ABHOLUNG
  Bundesland	State.OPEN
  Tracking-ID	Die Nummer oder die Kennung, die Sie zur Verfolgung einer Sendung verwenden.
  planmäßiger Standort	Der Ort, an dem die Aufgabe ausgeführt werden soll, in diesem Fall der Abholort der Lieferung.
  TaskDuration	Die voraussichtliche Zeit in Sekunden, die es dauert, bis die Sendung am Abholort abgeholt wird.

• Optionale Felder:

  Feld	Wert
  targetTimeWindow	Das Zeitfenster, in dem die Aufgabe abgeschlossen werden soll. Dies wirkt sich derzeit nicht auf das Routingverhalten aus.
  Attribute	Eine Liste benutzerdefinierter Task-Attribute. Jedes Attribut muss einen eindeutigen Schlüssel haben.

Alle anderen Felder in der Entität werden beim Erstellen ignoriert. Fleet Engine gibt eine Ausnahme aus, wenn die Anfrage eine zugewiesene deliveryVehicleId enthält. Aufgaben weisen Sie mit UpdateDeliveryVehicleRequests zu. Weitere Informationen finden Sie unter Einem Fahrzeug Aufgaben zuweisen.

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

Zustellaufgabe für Lieferung erstellen

Sie können eine Sendungszustellung entweder über das Driver SDK oder in der Serverumgebung erstellen.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek eine Sendungszustellungsaufgabe erstellen:

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

Um eine Sendungszustellungsaufgabe aus einer Serverumgebung zu erstellen, 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. Es darf sich nicht um die Verfolgungsnummer der Sendung handeln. Wenn in Ihrem System keine Aufgaben-IDs vorhanden sind, können Sie eine UUID (Universally Unique Identifier) generieren.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  eingeben	Typ.LIEFERUNG
  Bundesland	State.OPEN
  Tracking-ID	Die Nummer oder die Kennung, die Sie zur Verfolgung einer Sendung verwenden.
  planmäßiger Standort	Der Ort, an dem die Aufgabe ausgeführt werden soll, in diesem Fall der Lieferort dieser Sendung.
  TaskDuration	Die voraussichtliche Zeit in Sekunden, die es dauert, bis die Sendung am Lieferort abgegeben wird.

• Optionale Felder:

  Feld	Wert
  targetTimeWindow	Das Zeitfenster, in dem die Aufgabe abgeschlossen werden soll. Dies wirkt sich derzeit nicht auf das Routingverhalten aus.
  Attribute	Eine Liste benutzerdefinierter Task-Attribute. Jedes Attribut muss einen eindeutigen Schlüssel haben.

Alle anderen Felder in der Entität werden beim Erstellen ignoriert. Fleet Engine gibt eine Ausnahme aus, wenn die Anfrage eine zugewiesene deliveryVehicleId enthält. Aufgaben weisen Sie mit UpdateDeliveryVehicleRequests zu. Weitere Informationen finden Sie unter Einem Fahrzeug Aufgaben zuweisen.

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

Aufgaben im Batch erstellen

Sie können einen Batch von Aufgaben aus der Serverumgebung erstellen.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek zwei Aufgaben erstellen, eine für eine Lieferung und eine für die Abholung am selben Ort:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Delivery Task settings
Task deliveryTask = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("delivery-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8312508")  // Task ID assigned by the Provider
      .setTask(deliveryTask)      // Initial state
      .build();

// Pickup Task settings
Task pickupTask = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("pickup-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(pickupTask)        // Initial state
      .build();

// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;

// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
  BatchCreateTasksRequest.newBuilder()
      .setParent(parent)
      .addRequests(createDeliveryTaskRequest)
      .addRequests(createPickupTaskRequest)
      .build();

// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.

try {
  BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
    batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Führen Sie einen HTTP REST-Aufruf an BatchCreateTasks aus, um eine Zustell- und Abholaufgabe aus der Serverumgebung zu erstellen:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine BatchCreateTasksRequest-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  Anfragen	Array<CreateTasksRequest>

• Optionale Felder:

  Feld	Wert
  Header	DeliveryRequestHeader

Jedes CreateTasksRequest-Element in requests muss dieselben Validierungsregeln erfüllen wie eine CreateTask-Anfrage. Die Ausnahme sind, dass die Felder parent und header optional sind. Wenn festgelegt, müssen sie mit den entsprechenden Feldern auf BatchCreateTasksRequest der obersten Ebene identisch sein. Informationen zu spezifischen Validierungsregeln für jede Aufgabe finden Sie unter Abholaufgabe für die Sendung erstellen und Zustellaufgabe für die Lieferung erstellen.

Weitere Informationen finden Sie in der API-Referenzdokumentation zu BatchCreateTasks (gRPC, REST).

Beispiel eines curl-Befehls:

# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "requests" : [
    {
      "taskId": "${DELIVERY_TASK_ID}",
      "task" : {
        "type": "DELIVERY",
        "state": "OPEN",
        "trackingId": "${DELIVERY_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    },
    {
      "taskId": "${PICKUP_TASK_ID}",
      "task" : {
        "type": "PICKUP",
        "state": "OPEN",
        "trackingId": "${PICKUP_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    }
  ]
}
EOM

Geplante Nichtverfügbarkeit

Sie können eine Aufgabe erstellen, die die Nichtverfügbarkeit angibt (z. B. für Pausen des Fahrers oder zum Tanken von Fahrzeugen), entweder über das Driver SDK oder über die Serverumgebung. Eine geplante Aufgabe zur Nichtverfügbarkeit darf keine Tracking-ID enthalten. Optional können Sie einen Standort angeben.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek eine Nichtverfügbarkeitsaufgabe erstellen:

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.UNAVAILABLE)
  .setState(Task.State.OPEN)
  .setTaskDuration(
    Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
  .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

Um eine Nichtverfügbarkeitsaufgabe aus einer Serverumgebung zu erstellen, 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. Wenn in Ihrem System keine Aufgaben-IDs vorhanden sind, können Sie eine UUID (Universally Unique Identifier) generieren.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  eingeben	Typ.UNAVAILABLE
  Bundesland	State.OPEN
  TaskDuration	Die Länge der Pause in Sekunden.

• Optionale Felder:

  Feld	Wert
  planmäßiger Standort	Die Stelle der Unterbrechung, wenn sie an einem bestimmten Ort aufgenommen werden muss.

Alle anderen Felder in der Entität werden beim Erstellen ignoriert. Fleet Engine gibt eine Ausnahme aus, wenn die Anfrage eine zugewiesene deliveryVehicleId enthält. Aufgaben weisen Sie mit UpdateDeliveryVehicleRequests zu. Weitere Informationen finden Sie unter Einem Fahrzeug Aufgaben zuweisen.

Beispiel eines curl-Befehls:

# Set $JWT, $PROJECT_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": "UNAVAILABLE",
  "state": "OPEN",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "300s"
}
EOM

Geplante Stopps

Sie können eine Aufgabe zum geplanten Beenden entweder über das Driver SDK oder in der Serverumgebung erstellen. Eine Aufgabe zum geplanten Stoppen darf keine Tracking-ID enthalten.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek eine Aufgabe für geplante Stopps erstellen:

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.SCHEDULED_STOP)
  .setState(Task.State.OPEN)
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTrip(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

Führen Sie einen HTTP REST-Aufruf an CreateTask aus, um eine geplante Stoppaufgabe aus einer Serverumgebung zu erstellen:

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

<id> ist eine eindeutige Kennung für die Aufgabe. Wenn in Ihrem System keine Aufgaben-IDs vorhanden sind, können Sie eine UUID (Universally Unique Identifier) generieren.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  eingeben	Typ SCHEDULED_STOP
  Bundesland	State.OPEN
  planmäßiger Standort	Die Position der Haltestelle.
  TaskDuration	Die erwartete Länge der Haltestelle in Sekunden.

• Optionale Felder:

  • –

Alle anderen Felder in der Entität werden beim Erstellen ignoriert. Fleet Engine gibt eine Ausnahme aus, wenn die Anfrage eine zugewiesene deliveryVehicleId enthält. Aufgaben weisen Sie mit UpdateDeliveryVehicleRequests zu. Weitere Informationen finden Sie unter Einem Fahrzeug Aufgaben zuweisen.

Beispiel eines curl-Befehls:

# Set $JWT, $PROJECT_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": "SCHEDULED_STOP",
  "state": "OPEN",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "600s"
}
EOM

Das Zielzeitfenster ist das TimeWindow, in dem die Aufgabe ausgeführt werden soll. Wenn Sie beispielsweise den Zustellungsempfängern ein Lieferzeitfenster mitteilen, können Sie dieses Zeitfenster mithilfe des Aufgabenzielzeitfensters erfassen und Warnungen generieren oder die Leistung nach der Fahrt mit dem Feld analysieren.

Das Zielzeitfenster besteht aus einer Start- und einer Endzeit und kann für jeden Aufgabentyp festgelegt werden. Das Zielzeitfenster hat derzeit keinen Einfluss auf das Routingverhalten.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek ein Aufgabenzeitfenster festlegen:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Rufen Sie UpdateTask auf, um ein Aufgabenzeitfenster mit HTTP festzulegen:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow

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

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  targetTimeWindow	Das Zeitfenster, in dem die Aufgabe abgeschlossen werden soll. Dies wirkt sich derzeit nicht auf das Routingverhalten aus

• Optionale Felder:

  • –

Alle anderen Felder in der Entität werden bei der Aktualisierung ignoriert.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Sichtbarkeitskonfiguration für Aufgaben-Tracking festlegen

Die Sichtbarkeit der Daten in der Sendungsverfolgungsbibliothek und der Daten, die von einem Aufruf an GetTaskTrackingInfo zurückgegeben werden, kann pro Aufgabe gesteuert werden, indem ein TaskTrackingViewConfig für die Aufgabe festgelegt wird. Weitere Informationen finden Sie unter Aktive Fahrzeugaufgaben. Dies kann beim Erstellen oder Aktualisieren der Aufgabe erfolgen. Im Folgenden finden Sie ein Beispiel für das Aktualisieren der Aufgabe mit dieser Konfiguration:

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek die Konfiguration der Aufgaben-Tracking-Ansicht festlegen:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}

REST

Rufen Sie UpdateTask auf, um das Konfigurationsfenster für die Aufgaben-Tracking-Ansicht mit HTTP festzulegen:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig

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

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  TaskTrackingViewConfig	Die Konfiguration für das Aufgaben-Tracking, mit der festgelegt wird, welche Datenelemente unter welchen Umständen für Endnutzer sichtbar sind.

• Optionale Felder:

  • –

Alle anderen Felder in der Entität werden bei der Aktualisierung ignoriert.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

Einem Fahrzeug Aufgaben zuweisen

Aufgaben werden einem Lieferfahrzeug zugewiesen, indem die Aufgabenreihenfolge für das Fahrzeug aktualisiert wird. Die Aufgabenreihenfolge für ein Fahrzeug wird durch die Liste der Haltestellen für das Lieferfahrzeug bestimmt. Jeder Fahrzeughaltestelle können eine oder mehrere Aufgaben zugewiesen werden.

Beim Aktualisieren der Aufgabenreihenfolge für eine Aufgabe, die zuvor einem anderen Fahrzeug zugewiesen war, wird ein Fehler generiert.

Wenn Sie eine Sendung von einem Fahrzeug an ein anderes übertragen möchten, schließen Sie die ursprüngliche Aufgabe und erstellen Sie sie neu, bevor Sie sie dem neuen Fahrzeug zuweisen.

Aufgabensortierung aktualisieren

Sie können die Reihenfolge der Ausführung von Aufgaben, die einem Fahrzeug zugewiesen sind, entweder über das Driver SDK oder über die Serverumgebung aktualisieren. Die beiden Methoden sollten nicht miteinander kombiniert werden, um Race-Bedingungen zu vermeiden.

Wenn Sie die Aufgabenreihenfolge aktualisieren, werden auch Aufgaben einem Fahrzeug zugewiesen, wenn sie zuvor noch keinem Fahrzeug zugewiesen waren. Außerdem werden Aufgaben geschlossen, die zuvor einem Fahrzeug zugewiesen und aus der aktualisierten Reihenfolge ausgelassen wurden. Wenn eine Aufgabe einem anderen Fahrzeug zugewiesen wird, wenn sie zuvor bereits einem anderen Fahrzeug zugewiesen war, wird ein Fehler generiert. Schließen Sie zuerst die vorhandene Aufgabe und erstellen Sie dann eine neue Aufgabe, bevor Sie sie dem neuen Fahrzeug zuweisen.

Die Aufgabenreihenfolge kann jederzeit aktualisiert werden.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek die Aufgabenreihenfolge für das Fahrzeug aktualisieren:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.NEW)))
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Um die Aufgabenreihenfolge für ein Fahrzeug aus einer Serverumgebung zu aktualisieren, führen Sie einen HTTP REST-Aufruf an „UpdateDeliveryVehicle“ aus:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments

<id> ist eine eindeutige Kennung für ein Lieferfahrzeug in Ihrer Flotte, für das Sie die Aufgabenreihenfolge aktualisieren möchten. Es ist die Kennung, die Sie beim Erstellen des Fahrzeugs angegeben haben.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  VerbleibendeVehicleJourneySegmente	Eine Liste der Reisesegmente für Aufgaben in der Reihenfolge, in der sie ausgeführt werden sollen. Die erste Aufgabe in der Liste wird zuerst ausgeführt.
  verbleibendeVehicleJourneySegments[i].stop	Haltestelle für Aufgabe i in der Liste.
  verbleibendeVehicleJourneySegments[i].stop.plannedLocation	Der geplante Standort für die Haltestelle.
  verbleibendeVehicleJourneySegments[i].stop.tasks	Eine Liste der Aufgaben, die an dieser Fahrzeughaltestelle auszuführen sind.
  verbleibendeVehicleJourneySegments[i].stop.state	Status.NEU

• Optionale Felder:

  • –

Alle anderen Felder in der Entität werden bei der Aktualisierung ignoriert.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Fleet Engine muss benachrichtigt werden, wenn ein Fahrzeug von einer Haltestelle abfährt oder die Navigation beginnt. Sie können Fleet Engine entweder über das Driver SDK oder über die Serverumgebung benachrichtigen. Die beiden Methoden sollten nicht kombiniert werden, um Race-Bedingungen zu vermeiden und eine Single Source of Truth zu erhalten.

gRPC

Das folgende Beispiel zeigt, wie Sie die Java gRPC-Bibliothek verwenden, um Fleet Engine darüber zu informieren, dass ein Fahrzeug auf der Route zur nächsten Haltestelle ist.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Next stop marked as ENROUTE
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ENROUTE)))
    // All other stops marked as NEW
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();


// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Wenn Sie die Fleet Engine darüber informieren möchten, dass ein Fahrzeug aus einer Serverumgebung zur nächsten Haltestelle unterwegs ist, führen Sie einen HTTP REST-Aufruf an „UpdateDeliveryVehicle“ aus:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments

<id> ist eine eindeutige Kennung für das Lieferfahrzeug in Ihrer Flotte, für das Sie die Aufgabenreihenfolge aktualisieren möchten. Es ist die Kennung, die Sie beim Erstellen des Fahrzeugs angegeben haben.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfeld:

  Feld	Wert
  VerbleibendeVehicleJourneySegmente	Liste der verbleibenden Fahrzeughaltestellen, deren Status als State.NEW gekennzeichnet sind. Der Bundesstaat der ersten Haltestelle auf der Liste muss als State.ENROUTE gekennzeichnet sein.

• Optionale Felder:

  • –

Alle anderen Felder in der Entität werden für die Benachrichtigung ignoriert.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ENROUTE",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Der Fleetmotor muss benachrichtigt werden, wenn ein Fahrzeug an einer Haltestelle eintrifft. Sie können Fleet Engine entweder über das Driver SDK oder über die Serverumgebung benachrichtigen. Die beiden Methoden sollten nicht kombiniert werden, um Race-Bedingungen zu vermeiden und eine Single Source of Truth zu erhalten.

gRPC

Das folgende Beispiel zeigt, wie Sie die Java gRPC-Bibliothek verwenden, um Fleet Engine zu informieren, dass ein Fahrzeug an einer Haltestelle eingetroffen ist:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Marking the arrival at stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Wenn Sie die Fleet Engine über die Ankunft eines Fahrzeugs an einer Haltestelle aus einer Serverumgebung informieren möchten, führen Sie einen HTTP REST-Aufruf an „UpdateDeliveryVehicle“ aus:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments

<id> ist eine eindeutige Kennung für das Lieferfahrzeug in Ihrer Flotte, für das Sie die Aufgabenreihenfolge aktualisieren möchten. Es ist die Kennung, die Sie beim Erstellen des Fahrzeugs angegeben haben.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  VerbleibendeVehicleJourneySegmente	Die Haltestelle, an der Sie angekommen sind, hat den Status „State.ARRIVED“, gefolgt von einer Liste der verbleibenden Fahrzeughaltestellen, deren Status als State.NEW gekennzeichnet ist.

• Optionale Felder:

  • –

Alle anderen Felder in der Entität werden bei der Aktualisierung ignoriert.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ARRIVED",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Der Fleet-Motor muss benachrichtigt werden, wenn ein Fahrzeug anhält. Dadurch werden alle mit der Haltestelle verbundenen Aufgaben in den Status GESCHLOSSEN gesetzt. Sie können Fleet Engine entweder über das Driver SDK oder über die Serverumgebung benachrichtigen. Die beiden Methoden sollten nicht miteinander kombiniert werden, um Race-Bedingungen zu vermeiden und eine Single Source of Truth zu erhalten.

gRPC

Das folgende Beispiel zeigt, wie Sie die Java gRPC-Bibliothek verwenden, um Fleet Engine darüber zu informieren, dass ein Fahrzeug einen Halt erreicht hat.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // This stop has been completed and is commented out to indicate it
    // should be removed from the list of vehicle journey segments.
    // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
    //    .setStop(VehicleStop.newBuilder()
    //        .setPlannedLocation(LocationInfo.newBuilder()
    //            .setPoint(LatLng.newBuilder()
    //                .setLatitude(37.7749)
    //                .setLongitude(122.4194)))
    //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
    //        .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    // The next stop could be marked as ENROUTE if the vehicle has begun
    // its journey to the next stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // no need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Wenn Sie Fleet Engine über den Abschluss eines Stopps in einer Serverumgebung informieren möchten, führen Sie einen HTTP REST-Aufruf an „UpdateDeliveryVehicle“ aus:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments

<id> ist eine eindeutige Kennung für das Lieferfahrzeug in Ihrer Flotte, für das Sie die Aufgabenreihenfolge aktualisieren möchten. Es ist die Kennung, die Sie beim Erstellen des Fahrzeugs angegeben haben.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  Verbleibende Fahrzeugsegmente	Die angefahrene Haltestelle sollte nicht mehr in der Liste der verbleibenden Fahrzeughaltestellen enthalten sein.

• Optionale Felder:

  • –

Alle anderen Felder in der Entität werden bei der Aktualisierung ignoriert.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}",
            "taskDuration": "120s"
          }
        ]
      }
    }
  ]
}
EOM

Dies ist ein Beispiel für die Aktualisierung einer Aufgabe über gRPC.

REST

Dies ist ein Beispiel für die Aktualisierung einer Aufgabe über REST.

Zum Schließen einer Aufgabe, die einem Fahrzeug zugewiesen wurde, benachrichtigen Sie Fleet Engine, dass das Fahrzeug die Haltestelle, an der die Aufgabe stattfindet, abgeschlossen hat, oder entfernen Sie das Fahrzeug aus der Liste der Fahrzeughalte. Dazu können Sie die Liste der verbleibenden Fahrzeughaltestellen genauso wie beim Aktualisieren der Aufgabenreihenfolge für ein Fahrzeug festlegen.

Wenn einer Aufgabe noch kein Fahrzeug zugewiesen wurde und sie geschlossen werden muss, setzen Sie die Aufgabe auf den Status GESCHLOSSEN. Sie können eine GESCHLOSSENE Aufgabe jedoch nicht wieder öffnen.

Das Abschließen einer Aufgabe bedeutet weder Erfolg noch Misserfolg. Es zeigt an, dass die Aufgabe nicht mehr als in Bearbeitung gilt. Für die Flottenverfolgung ist es wichtig, das tatsächliche Ergebnis einer Aufgabe anzugeben, damit ein Lieferergebnis dargestellt werden kann.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setState(Task.State.CLOSED) // It's only possible to directly CLOSE a
  .build();                    // task which is NOT assigned to a vehicle.

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("state"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state

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

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  Bundesland	Status.GESCHLOSSEN

• Optionale Felder:

  Feld	Wert
  Aufgabenergebnis	Result.SUCCEEDED (Ergebnis.ERFOLGREICH) oder Ergebnis fehlgeschlagen
  TaskResultTime (Aufgabe)	Der Zeitpunkt, zu dem die Aufgabe abgeschlossen wurde.
  TaskResultLocation (Aufgabe)	Der Ort, an dem die Aufgabe abgeschlossen wurde. In der Fleet Engine wird standardmäßig der letzte Fahrzeugstandort verwendet, sofern dies nicht manuell vom Anbieter überschrieben wird.

Alle anderen Felder in der Entität werden bei der Aktualisierung ignoriert.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "state": "CLOSED",
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)"
}
EOM

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek ein Aufgabenergebnis auf SUCCEEDED festlegen und den Ort festlegen, an dem die Aufgabe abgeschlossen wurde:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskOutcome(TaskOutcome.SUCCEEDED)
  .setTaskOutcomeTime(now())
  .setTaskOutcomeLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation

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

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Feld	Wert
  Aufgabenergebnis	Result.SUCCEEDED (Ergebnis.ERFOLGREICH) oder Ergebnis fehlgeschlagen
  TaskResultTime (Aufgabe)	Der Zeitstempel, der angibt, wann das Ergebnis der Aufgabe festgelegt wurde (vom Anbieter). Dies ist der Zeitpunkt, zu dem die Aufgabe abgeschlossen wurde.

• Optionale Felder:

  Feld	Wert
  TaskResultLocation (Aufgabe)	Der Ort, an dem die Aufgabe abgeschlossen wurde. In der Fleet Engine wird standardmäßig der letzte Fahrzeugstandort verwendet, sofern dies nicht manuell vom Anbieter überschrieben wird.

Alle anderen Felder in der Entität werden bei der Aktualisierung ignoriert.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)",
  "taskOutcomeLocation": {
    "point": {
      "latitude": -6.195139,
      "longitude": 106.820826
    }
  }
}
EOM

Sendung umleiten

Nachdem eine Versandaufgabe erstellt wurde, kann ihr geplanter Standort nicht mehr geändert werden. Wenn Sie eine Sendung umleiten möchten, schließen Sie die Versandaufgabe, ohne ein Ergebnis festzulegen, und erstellen Sie dann eine neue Aufgabe mit dem aktualisierten geplanten Standort. Nachdem Sie die neue Aufgabe erstellt haben, weisen Sie sie demselben Fahrzeug zu. Weitere Informationen finden Sie unter Versandaufgabe schließen und Aufgabe zuweisen.

Feeder und Lieferfahrzeuge verwenden

Wenn Sie Zubringerfahrzeuge für den Transport von Lieferungen zu Lieferfahrzeugen im Laufe des Tages verwenden, modellieren Sie die Übertragung von Sendungen als geplante Haltestellenaufgabe für das Lieferfahrzeug. Damit eine genaue Standortverfolgung sichergestellt ist, weisen Sie einer übertragenen Sendung erst dann eine Lieferaufgabe zu, nachdem sie auf das Lieferfahrzeug verladen wurde. Weitere Informationen finden Sie unter Geplante Haltestelle.

Versandstatus des Geschäfts und andere Meta-Informationen

Wenn eine Versandaufgabe abgeschlossen ist, werden der Aufgabenstatus und das Ergebnis in der Aufgabe aufgezeichnet. Vielleicht möchten Sie aber auch andere versandspezifische Metadaten aktualisieren. Wenn Sie andere Metainformationen speichern möchten, auf die Sie außerhalb des Fleet Engine-Dienstes verweisen können, verwenden Sie die mit der Aufgabe verknüpfte Tracking-ID als Schlüssel in einer externen Tabelle.

Weitere Informationen finden Sie unter Lebensdauer einer Aufgabe.

Fahrzeug suchen

Sie können ein Fahrzeug entweder über das Driver SDK oder in der Serverumgebung suchen.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek nach einem Fahrzeug suchen:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder()  // No need for the header
    .setName(name)
    .build();

try {
  DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Wenn Sie ein Fahrzeug aus einer Serverumgebung abrufen möchten, führen Sie einen HTTP REST-Aufruf an „GetVehicle“ aus:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>

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

<vehicleId> ist die ID des Fahrzeugs, das gesucht werden soll.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss leer sein.

Wenn die Suche erfolgreich ist, enthält der Antworttext eine Fahrzeugentität.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"

Aufgaben suchen

Sie können eine Aufgabe in einer Serverumgebung nachschlagen. Das Driver SDK unterstützt die Suche nach einer Aufgabe nicht.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek nach einer Aufgabe suchen:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
    .setName(taskName)
    .build();

try {
  Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Wenn Sie eine Aufgabe aus einer Serverumgebung abrufen möchten, führen Sie einen HTTP REST-Aufruf an „GetTask“ aus:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>

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

<taskId> ist die ID der Aufgabe, die nachgeschlagen werden soll.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Der Anfragetext muss leer sein.

Wenn die Suche erfolgreich ist, enthält der Antworttext eine Aufgabenentität.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

Informationen zur Sendungsaufgabe anhand der Tracking-ID abrufen

Sie können Informationen zu Versandaufgaben auf folgende Arten abrufen, die jeweils einen eigenen Zweck haben:

• durch eine Aufgaben-ID: wird von Nutzern wie Flottenoperatoren verwendet, die Zugriff auf die vollständige Ansicht der Aufgabendaten haben.
• durch eine Tracking-ID: wird von Ihrer Clientsoftware verwendet, um Endnutzern begrenzte Informationen zur Verfügung zu stellen, z. B. wann ein Paket bei ihnen ankommt.

In diesem Abschnitt wird beschrieben, wie Sie Informationen zu Aufgaben anhand einer Tracking-ID abrufen. Wenn Sie eine Aufgabe anhand der Aufgaben-ID suchen möchten, fahren Sie mit Aufgaben suchen fort.

Wenn Sie Informationen anhand einer Tracking-ID abrufen möchten, haben Sie folgende Möglichkeiten:

• Lookups mit Java unter Verwendung von gRPC
• Suchen mit HTTP

Lookup-Anforderungen

• Mit einer Sendungsverfolgungs-ID bereitgestellte Versandinformationen entsprechen den Sichtbarkeitsregeln unter Sichtbarkeit beobachteter Standorte steuern.

• Mit Fleet Engine können Sie Versandinformationen anhand der Tracking-ID abrufen. Das Driver SDK unterstützt keine Informationssuche nach Tracking-ID. Dazu verwenden Sie mit Fleet Engine entweder eine Server- oder eine Browserumgebung.

• Verwenden Sie möglichst eng gefasstes Token, um Sicherheitsrisiken zu begrenzen. Wenn Sie beispielsweise ein Delivery Consumer Token verwenden, geben alle Aufrufe der Fleet Engine Deliveries API nur Informationen zurück, die für diesen Endnutzer relevant sind, z. B. das Versandunternehmen oder den Empfänger einer Sendung. Alle anderen Informationen in den Antworten werden entfernt. Weitere Informationen zu Tokens findest du unter JSON Web Token (JWT) für die Autorisierung erstellen.

Lookups mit Java unter Verwendung von gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek Informationen zu einer Versandaufgabe anhand ihrer Tracking-ID abrufen.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Lookups mit HTTP

Um eine Versandaufgabe in einem Browser nachzuschlagen, führen Sie einen HTTP REST-Aufruf an GetTaskTrackingInfo aus:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>

<tracking_id> ist die der Aufgabe zugeordnete Tracking-ID.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory ausgegeben wird.

Wenn die Suche erfolgreich ist, enthält der Antworttext die Entität taskTrackingInfo.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

Aufgaben auflisten

Sie können Aufgaben aus einer Server- oder Browserumgebung auflisten. Das Auflisten von Aufgaben wird vom Driver SDK nicht unterstützt.

Das Auflisten von Aufgaben erfordert umfassenden Zugriff auf Aufgaben. Das Auflisten von Aufgaben ist nur für vertrauenswürdige Nutzer gedacht. Verwenden Sie Delivery Fleet Reader oder Delivery Super User Authentication Tokens, wenn Sie Anfragen für Listenaufgaben stellen.

Bei den aufgeführten Aufgaben wurden die folgenden Felder entfernt:

• VehicleStop.planned_location
• VehicleStop.state
• VehicleStop.TaskInfo.taskId

Aufgeführte Aufgaben können nach den meisten Aufgabeneigenschaften gefiltert werden. Informationen zur Syntax der Filterabfrage finden Sie unter AIP-160. Die folgende Liste enthält gültige Aufgabenattribute, die Sie zum Filtern verwenden können:

• Attribute
• delivery_vehicle_id (Liefer-ID)
• Bundesland
• geplanter_Ort
• Taskdauer
• Aufgabe_Ergebnis
• Ort der Aufgabe_Ergebnis
• Task_outcome_location_source
• ergebnis_zeit
• Tracking-ID
• eingeben

Verwenden Sie die folgenden Feldformate, die auf Google API-Verbesserungsvorschlägen basieren:

Eine vollständige Liste der Operatoren für Filterabfragen finden Sie unter AIP-160.

Wenn keine Filterabfrage angegeben ist, werden alle Aufgaben aufgelistet.

Aufgabenlisten sind paginiert. In Anfragen zum Auflisten von Aufgaben kann eine Seitengröße angegeben werden. Wenn eine Seitengröße angegeben ist, ist die Anzahl der zurückgegebenen Aufgaben nicht größer als die angegebene Seitengröße. Wenn keine Seitengröße vorhanden ist, wird ein angemessener Standardwert verwendet. Wenn die angeforderte Seitengröße einen internen Maximalwert überschreitet, wird der interne Maximalwert verwendet.

Eine Aufgabenliste kann ein Token zum Lesen der nächsten Ergebnisseite enthalten. Verwenden Sie das Seitentoken mit einer Anfrage, die ansonsten mit der vorherigen Anfrage identisch ist, um die nächste Aufgabenseite abzurufen. Wenn das zurückgegebene Seitentoken leer ist, können keine weiteren Aufgaben abgerufen werden.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek Aufgaben für eine deliveryVehicleId und ein Aufgabenattribut auflisten. Eine erfolgreiche Antwort kann trotzdem leer sein. Bei einer leeren Antwort sind der bereitgestellten deliveryVehicleId keine Aufgaben zugeordnet.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
    .build();

try {
  ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Wenn Sie Aufgaben über einen Browser auflisten möchten, senden Sie einen HTTP REST-Aufruf an ListTasks:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks

Um einen Filter auf die aufgeführten Aufgaben anzuwenden, fügen Sie einen URL-Parameter "filter" mit einer URL-maskierten Filterabfrage als Wert ein.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Wenn die Suche erfolgreich ist, enthält der Antworttext Daten mit der folgenden Struktur:

// JSON representation
{
  "tasks": [
    {
      object (Task)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Eine erfolgreiche Antwort kann trotzdem leer sein. Eine leere Antwort bedeutet, dass keine Aufgaben gefunden wurden, die den angegebenen Filterkriterien entsprechen.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

Lieferfahrzeuge auflisten

Sie können Lieferfahrzeuge aus einer Server- oder Browserumgebung auflisten. Das Driver SDK unterstützt keine Einträge für Lieferfahrzeuge.

Das Auflisten von Lieferfahrzeugen erfordert einen umfassenden Zugriff auf Lieferfahrzeuge und ist nur für vertrauenswürdige Nutzer gedacht. Wenn Anfragen zur Liste von Lieferfahrzeugen gestellt werden, verwenden Sie die Authentifizierungstokens für Lieferflotten- oder Liefer-Superuser-Authentifizierungs-Tokens.

Bei aufgeführten Lieferfahrzeugen werden die folgenden Felder aufgrund ihrer Auswirkung auf die Antwortgröße entfernt:

• Aktuelles Routensegment
• Verbleibende Fahrzeugsegmente

Sie können Listen von Lieferfahrzeugen nach ihrer attributes-Property filtern. Wenn Sie beispielsweise ein Attribut mit dem Schlüssel my_key und dem Wert my_value abfragen möchten, verwenden Sie attributes.my_key = my_value. Wenn Sie mehrere Attribute abfragen möchten, führen Sie Abfragen mit den logischen Operatoren AND und OR wie in attributes.key1 = value1 AND attributes.key2 = value2 zusammen. Eine vollständige Beschreibung der Syntax von Filterabfragen finden Sie unter AIP-160.

Mit dem Anfrageparameter viewport können Sie aufgelistete Lieferfahrzeuge nach Standort filtern. Der Anfrageparameter viewport definiert Darstellungsbereiche mit zwei Begrenzungskoordinaten: high (Nordost) und low (Südwesten) mit Breiten- und Längengrad. Anfragen werden abgelehnt, wenn sie einen hohen Breitengrad aufweisen, der geografisch niedriger ist als ein niedriger Breitengrad.

Listen mit Lieferfahrzeugen werden standardmäßig in Seiten unterteilt. Die Seitengröße muss dabei angemessen sein. Wenn Sie eine Seitengröße angeben, gibt die Anfrage nur die Anzahl der Fahrzeuge zurück, die durch das Limit festgelegt sind, oder weniger. Wenn die angeforderte Seitengröße einen internen Maximalwert überschreitet, wird das interne Maximum verwendet. Die Standard- und die maximale Seitengröße sind jeweils 100 Fahrzeuge.

Eine Liste der Lieferfahrzeuge kann ein Token zum Lesen der nächsten Ergebnisseite enthalten. Ein Seitentoken ist nur in einer Antwort vorhanden, wenn mehr Seiten von Lieferfahrzeugen zum Abrufen verfügbar sind. Um die nächste Seite mit Aufgaben abzurufen, verwenden Sie das Seitentoken mit einer Anfrage, die ansonsten mit der vorherigen Anfrage identisch ist.

gRPC

Das folgende Beispiel zeigt, wie Sie die Java gRPC-Bibliothek verwenden, um Lieferfahrzeuge in einer bestimmten Region mit einem bestimmten Attribut aufzulisten. Eine erfolgreiche Antwort kann trotzdem leer sein. In diesem Fall befinden sich derzeit keine Fahrzeuge mit dem angegebenen Attribut im angegebenen Darstellungsbereich.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
  ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setViewport(
            Viewport.newBuilder()
              .setHigh(LatLng.newBuilder()
                  .setLatitude(37.45)
                  .setLongitude(-122.06)
                  .build())
              .setLow(LatLng.newBuilder()
                  .setLatitude(37.41)
                  .setLongitude(-122.11)
                  .build())
      .setFilter("attributes.my_key = my_value")
      .build();

try {
  ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
      deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
          break;

      case PERMISSION_DENIED:
          break;
  }
  return;
}

REST

Wenn Sie Aufgaben über einen Browser auflisten möchten, senden Sie einen HTTP REST-Aufruf an ListDeliveryVehicles:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles

Um einen Filter auf die aufgeführten Aufgaben anzuwenden, fügen Sie einen URL-Parameter "filter" mit einer URL-maskierten Filterabfrage als Wert ein.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine-Token-Factory erstellt wurde.

Wenn die Suche erfolgreich ist, enthält der Antworttext Daten mit der folgenden Struktur:

// JSON representation
{
  "deliveryVehicles": [
    {
      object (DeliveryVehicle)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Eine erfolgreiche Antwort kann trotzdem leer sein. In diesem Fall wurden keine Lieferfahrzeuge gefunden, die der angegebenen Filterabfrage und dem angegebenen Darstellungsbereich entsprechen.

Beispiel eines curl-Befehls:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"

Flottenverfolgung

Sie haben zwei Möglichkeiten, die Fleet Engine Deliveries API zu verwenden, um die Flottenverfolgung zu aktivieren:

• Bevorzugt:Verwenden Sie die JavaScript-Flotten-Tracking-Bibliothek. Mit der Bibliothek können Sie die Standorte von Fahrzeugen und relevanten Standorten visualisieren, die in Fleet Engine erfasst wurden. Sie enthält eine JavaScript-Kartenkomponente, die ein Drop-in-Ersatz für das standardmäßige google.maps.Map-Objekt ist, sowie Datenkomponenten zur Verbindung mit der Fleet Engine. So können Sie in Ihrer Web- oder mobilen App eine anpassbare, animierte Flottenverfolgung bereitstellen.

• Implementieren Sie zusätzlich zur Fleet Engine Deliveries API eine eigene Flottenverfolgung.

Logging

Sie können eine Option aktivieren, damit Fleet Engine RPC-Logs an Cloud Logging senden kann. Weitere Informationen finden Sie unter Logging.

Wie unter Deliveries API einbinden und in den Autorisierungshinweisen für einzelne Anwendungsfälle beschrieben, erfordert ein Aufruf von Fleet Engine eine Authentifizierung mit JSON Web Tokens, die mit Dienstkonto-Anmeldedaten signiert wurden. Die Dienstkonten, die zum Erstellen dieser Tokens verwendet werden, können eine oder mehrere Rollen haben, wobei jede Rolle einen anderen Satz von Berechtigungen gewährt.

Weitere Informationen finden Sie unter Authentifizierung und Autorisierung.

Fehlerbehebung

Robustheit

Fleet Engine gilt nicht als „Source of Truth“. Sie sind dafür verantwortlich, den Zustand Ihres Systems bei Bedarf wiederherzustellen, ohne sich auf Fleet Engine verlassen zu müssen.

Verlorener Status in Fleet Engine

Implementieren Sie bei der Arbeit mit Fleet Engine Clients, damit sich das System bei einem Fehler selbst repariert. Wenn Fleet Engine beispielsweise versucht, ein Fahrzeug zu aktualisieren, kann es mit einem Fehler antworten, dass das Fahrzeug nicht vorhanden ist. Der Client sollte das Fahrzeug dann im neuen Zustand neu erstellen. Das kommt nur selten vor. Das System muss dafür robust sein.

Im äußerst unwahrscheinlichen Szenario eines katastrophalen Ausfalls der Fleet Engine müssen Sie möglicherweise die meisten oder alle Fahrzeuge und Aufgaben neu erstellen. Wenn die Erstellungsrate zu hoch wird, können einige Anfragen aufgrund von Kontingentproblemen wieder fehlschlagen, da Kontingentprüfungen vorhanden sind, um DoS-Angriffe (Denial of Service) zu vermeiden. Verlangsamen Sie in diesem Fall die Neuerstellungsrate mithilfe einer Backoff-Strategie für Wiederholungen.

Verlorener Status in der Fahrer-App

Wenn die Treiber-App abstürzt, muss sie den aktuellen Status im Driver SDK neu erstellen. Die Anwendung sollte versuchen, Aufgaben neu zu erstellen, um sicherzustellen, dass sie vorhanden sind und ihren aktuellen Status wiederherstellen. Die Anwendung sollte außerdem die Liste der Haltestellen für das Driver SDK neu erstellen und explizit festlegen.

Beachten Sie, dass diese Wiederherstellungen autonom erfolgen müssen, ohne sich auf Informationen von Fleet Engine zu verlassen, mit Ausnahme von Fehlern, die angeben, ob und wann eine Entität bereits in der Datenbank vorhanden ist. Wenn eine Entität bereits vorhanden ist, kann dieser Fehler absorbiert und die Entität anhand ihrer ID aktualisiert werden.

FAQs

Was passiert, wenn ein Fahrer wegen einer Aufgabe nicht in der richtigen Reihenfolge anhält?

In diesem Fall sollten Sie zuerst die Reihenfolge der Aufgaben aktualisieren und dann wie gewohnt fortfahren. Dabei markieren Sie die Ankunft an der Haltestelle, die Aufgabenerledigung usw. Andernfalls kann das System inkonsistent werden. ETAs können falsch sein und unerwartete Fehler werden gemeldet.