Erste Schritte mit Fleet Engine for Fleet Performance

Mit der Fleet Engine Deliveries API können Sie Ihre Flottenaktivitäten für die erste und letzte Meile von Lieferungen modellieren. Sie können diese API mithilfe des Driver SDK für Android und iOS oder direkt über HTTP REST- oder gRPC-Aufrufe verwenden.

Ersteinrichtung

Die Fleet Engine Deliveries API wird in der 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

Prüfen Sie nach dem Erstellen der Dienstkonten, ob die Einrichtung abgeschlossen ist und Sie ein Lieferfahrzeug erstellen können. Durch eine sofortige Überprüfung der Einrichtung stellen Sie sicher, dass häufige Autorisierungsprobleme behoben wurden, die beim Einrichten Ihres Projekts auftreten können. Es gibt zwei Möglichkeiten, die Einrichtung zu überprüfen:

• Testen Sie zwei wichtige Teile der Einrichtung: Signieren Sie mit Autorisierungstoken und erstellen Sie ein Testfahrzeug mit dem gcloud-Befehlszeilendienstprogramm. Weitere Informationen finden Sie im Leitfaden Einrichtung überprüfen.

• Testen Sie Ihre Einrichtung mit den Authentifizierungsskripts von Fleet Engine.

Clientbibliotheken

Verwenden Sie die Clientbibliotheken in verschiedenen gängigen Programmiersprachen, um die Entwicklererfahrung im Hinblick auf unformatierten gRPC oder REST zu verbessern. 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 Fleet Engine Deliveries API verwendet zwei Datenstrukturen, um die Abholung und Zustellung von Sendungen zu modellieren:

• Das Lieferfahrzeug, das für den Transport der Sendung verwendet wird.
• Die Aufgaben zum Abholen der Sendung und zu den Zustellaufgaben.

Außerdem verwenden Sie Aufgaben, um Fahrpausen und geplante Haltestellen für den ganzen Tag zu modellieren.

Lieferfahrzeuge

Lieferfahrzeuge befördern Lieferungen von einem Depot zu einem Lieferort und von einem Abholort zum Depot. In bestimmten Fällen können sie eine Sendung auch direkt vom Abholort zum Lieferort transportieren.

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

Hinweis: Sie können DeliveryVehicle-Objekten bis zu 500 Aufgaben und 300 verbleibende Fahrzeugreisesegmente zuweisen.

Aufgaben

Für die Aktionen, die ein Fahrzeug im Laufe des Tages ausführt, weisen Sie je nach Art der Aktion Aufgaben zu:

• Weisen Sie für Abholungen und Lieferungen Versandaufgaben zu.
• Weisen Sie für Zeiten, in denen keine Fahrer verfügbar sind, z. B. erforderliche Pausen, Aufgaben zur Nichtverfügbarkeit zu.
• Weisen Sie für Aufgaben, die nicht mit dem Auto unterwegs sind, an Abgabeboxen oder Kundenstandorten Aufgaben für geplante Haltestellen zu.

Jede zugewiesene Aufgabe muss eine eindeutige Aufgaben-ID haben. Aufgaben können jedoch dieselbe Tracking-ID haben. Wenn Fleet Engine die ETA-Fenster für jede Aufgabe berechnet, verwendet es alle Aufgaben und die Reihenfolge, in der sie geplant sind, um Schätzungen vorzunehmen. Weitere Informationen zu Aufgaben-IDs finden Sie in den Richtlinien für Aufgaben-IDs.

Verwenden Sie den Task-Manager des Driver SDK, um Aufgaben in Fleet Engine zu erstellen.

Versandaufgaben

Erstellen Sie Versandaufgaben für die Abholung und Zustellung einer Sendung und geben Sie die folgenden Informationen an:

• Der Ort der Abholung oder Lieferung.
• Eine Verfolgungsnummer oder ID.
• Eine Verweildauer, um zusätzliche Zeit für die Erledigung der Aufgabe, die Suche nach Parkplätzen oder den Weg zum Übergabeort einzuplanen.
• Eine eindeutige Aufgaben-ID. Weitere Informationen finden Sie in den Richtlinien für Aufgaben-IDs.

Weitere Informationen finden Sie unter folgenden Links:

Android

• Abholaufgabe für die Lieferung erstellen
• Zustellaufgabe erstellen

iOS

• GMTD DeliveryTaskManager
• GMTSTaskType

Nichtverfügbarkeitsaufgaben

Aufgaben zur Nichtverfügbarkeit beziehen sich auf Zeiträume, in denen ein Fahrzeug nicht für Abholungen oder Lieferungen verfügbar ist, z. B. Pausen zum Tanken des Fahrzeugs oder Pausen der Fahrerruhe.

Erstellen Sie eine Nichtverfügbarkeitsaufgabe mit den folgenden Informationen:

• Die Länge der Unterbrechung.
• Optional: die Stelle, an der die Unterbrechung eingefügt wurde Sie müssen keinen bestimmten Standort angeben, erhalten aber den ganzen Tag über genauere voraussichtliche Ankunftszeiten.

Hinweis: Während einer Aufgabe zur Nichtverfügbarkeit werden keine Standortinformationen an die Endnutzer der Versandverfolgungsbibliothek weitergegeben. Sie ist jedoch für Flottenmanager mit der Flottenverfolgungsbibliothek verfügbar.

Weitere Informationen finden Sie unter folgenden Links:

Android

• Geplante Nichtverfügbarkeit

iOS

• GMTD DeliveryTaskManager
• GMTSTaskType

Geplante Stopp-Aufgaben

Erstellen Sie geplante Haltestellenaufgaben, um die Haltestellen zu modellieren, die ein Lieferfahrzeug machen muss. Erstellen Sie beispielsweise eine geplante Haltestelle für eine tägliche Haltestelle für die Abholung an einem bestimmten Ort, unabhängig von anderen Lieferungen oder Abholungen am selben Standort. Sie können auch geplante Haltestellenaufgaben für Sammlungen aus Dropboxen oder für das Modellieren von Umstiegen zwischen Zubringern und Fahrzeugen oder Haltestellen an Servicezentren und Servicepunkten erstellen.

Weitere Informationen finden Sie unter folgenden Links:

Android

• Geplante Haltestellen

iOS

• GMTD DeliveryTaskManager
• GMTSTaskType

Richtlinien für Aufgaben-IDs

Beachten Sie beim Erstellen von Aufgaben-IDs die folgenden Inhalts- und Formatrichtlinien:

• Eindeutige Aufgaben-IDs erstellen
• Geben Sie keine personenidentifizierbaren Informationen oder Klartextdaten preis.
• Verwenden Sie gültige Unicode-Strings.
• Maximal 64 Zeichen zulässig.
• Folgende ASCII-Zeichen dürfen nicht enthalten sein: "/", ":", "\", "?" oder "#".
• Normalisieren Sie gemäß der Unicode-Normalisierungsform C.

Tipp :Sie können Aufgaben-IDs mit einem beliebigen programmatischen Mechanismus erstellen. Google empfiehlt die Verwendung eines UUID-Tools in Version 4.

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 nicht unterstützte Aufgaben-IDs:

Nicht unterstützte Aufgaben-IDs	Grund
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680	Verstößt gegen Anforderungen an personenidentifizierbare Informationen und Zeichen: Kommas, Punkte, Doppelpunkte und Schrägstriche.
JohnDoe-577b484da26f-Cupertino-SantaCruz	Verstößt gegen Anforderungen an personenidentifizierbare Informationen.
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a	Verstößt gegen Anforderungen an personenidentifizierbare Informationen und Zeichen: Leerzeichen, Kommas und Anführungszeichen. Er darf nicht länger als 64 Zeichen sein.

Weitere Ressourcen

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

Lebensdauer eines Fahrzeugs

Das DeliveryVehicle-Objekt steht für ein Lieferfahrzeug auf der ersten oder letzten Meile. Sie erstellen ein DeliveryVehicle-Objekt mit:

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

Verwenden Sie eindeutige Fahrzeug-IDs für jedes Fahrzeug. Verwenden Sie eine Fahrzeug-ID nur dann, wenn keine aktiven Aufgaben für das ursprüngliche Fahrzeug vorhanden sind.

Fleet Engine löscht DeliveryVehicle-Objekte, die nicht über UpdateDeliveryVehicle aktualisiert wurden, nach sieben Tagen automatisch. So prüfen Sie, ob ein Fahrzeug vorhanden ist:

1. Ruf UpdateDeliveryVehicle an.
2. Wenn Sie die Fehlermeldung NOT_FOUND erhalten, rufen Sie CreateDeliveryVehicle auf, um das Fahrzeug neu zu erstellen. Wenn beim Anruf ein Fahrzeug zurückgegeben wird, kann es weiterhin aktualisiert werden.

Hinweis :Wenn Sie CreateDeliveryVehicle mit einem bereits vorhandenen Paar aus Projekt-ID und Fahrzeug-ID aufrufen, wird eine Fehlermeldung angezeigt.

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 diejenigen mit den angegebenen Attributen beschränken kann. DeliveryVehicleAttribute wirkt sich nicht auf das Routingverhalten von Fleet Engine aus.

Geben Sie in Attributen keine personenidentifizierbaren Informationen oder vertraulichen Informationen an, da dieses Feld für Nutzer sichtbar sein kann.

Das Leben einer Aufgabe

Sie können Aufgaben in Fleet Engine mit den gRPC- oder REST-Schnittstellen der Deliveries API erstellen, aktualisieren und abfragen.

Ein Task-Objekt hat ein Statusfeld, in dem der Fortschritt während des Lebenszyklus verfolgt werden kann. Die Werte ändern sich von ÖFFNEN zu GESCHLOSSEN. 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 erreicht.

Richtlinien für Aufgaben

Sie können einem Fahrzeug nur dann eine Aufgabe zuweisen, wenn es sich im Status OFF befindet.

Sie können eine Aufgabe abbrechen, indem Sie sie aus der Liste der Fahrzeughaltestellen entfernen. Dadurch wird der Aufgabenstatus automatisch auf CLOSED gesetzt.

Wenn das Fahrzeug, das für die Aufgabe verantwortlich ist, den Stopp des Projekts erreicht hat, gilt Folgendes:

1. Aktualisieren Sie das Ergebnisfeld der Aufgabe auf ERFOLGREICH oder FEHLGESCHLAGEN.

   Hinweis: Sie können das Ergebnis der Aufgabe jederzeit vor oder nach Abschluss der Aufgabe festlegen, aber nur einmal.

2. Geben Sie den Zeitstempel des Ereignisses an.

   Die JavaScript-Flottenverfolgungsbibliothek zeigt dann das Ergebnis der Aufgabe an und der Aufgabenstatus wird automatisch auf GESCHLOSSEN festgelegt. Weitere Informationen finden Sie unter Flotten mit der JavaScript-Flottenverfolgungsbibliothek verfolgen.

Wie bei Fahrzeugen löscht Fleet Engine Aufgaben, die nach sieben Tagen nicht aktualisiert wurden, und 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 nach sieben Tagen automatisch 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 von TaskAttribute, das einen Wert von einem der drei Typen haben kann: String, Zahl oder boolescher Wert. Die ListTasks API enthält ein filter-Feld, mit dem zurückgegebene Task-Entitäten auf diejenigen mit den angegebenen Attributen beschränkt werden können. Aufgabenattribute haben keinen Einfluss auf das Fleet Engine-Routingverhalten.

Attribute dürfen keine personenidentifizierbaren Informationen oder andere vertrauliche Informationen enthalten, da diese für Nutzer sichtbar sein könnten.

Fahrzeug- und Aufgabenlebenszyklus verwalten

Zur Erinnerung: Ihr internes System fungiert als vertrauenswürdige Quelle für Daten, die die Fleet Engine Deliveries API in Ihrem Namen erweitert.

Wenn Sie den Fahrzeug- und Aufgabenlebenszyklus in Ihrem System verwalten möchten, verwenden Sie die Fleet Engine Deliveries API, um Ihre Fahrzeuge und die zugehörigen Aufgaben zu erstellen, zu aktualisieren und zu verfolgen.

Gleichzeitig kommuniziert die Treiberanwendung direkt mit Fleet Engine, um den Gerätestandort und die Routeninformationen zu aktualisieren. Mit diesem Modell kann Fleet Engine den Echtzeitstandort effizient verwalten. Der Standort wird direkt an die Tracking-Bibliothek gesendet, über die Sie dann die Kunden über den Status ihrer Bestellung informieren können.

Angenommen, Sie haben das folgende Szenario:

• Ein Fahrer nähert sich einer Lieferstation. Die Treiberanwendung sendet ihren Standort an Fleet Engine.
• Fleet Engine sendet den Gerätestandort an die Tracking-Bibliothek. Diese wird von Ihrer Nutzeranwendung verwendet, um den Nutzer auf die Nähe eines Pakets aufmerksam zu machen.
• Nachdem der Fahrer die Sendung abgeschlossen hat, klickt er in der Treiberanwendung auf die Schaltfläche „Shipment delivered“ (Lieferung zugestellt).
• Durch die Aktion "Lieferung zugestellt" werden die Informationen an Ihr Backend-System gesendet, das die erforderlichen Schritte zur Unternehmensvalidierung und -überprüfung durchführt.
• Ihr System bestätigt die Aufgabe als ERFOLGREICHT und aktualisiert Fleet Engine mithilfe der Deliveries API.

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

Clienttokens verwalten

Standortaktualisierungen, die von der Treiberanwendung stammen und direkt an Fleet Engine gesendet werden, erfordern Autorisierungstokens. Hier ist der empfohlene Ansatz, um Aktualisierungen vom Client an Fleet Engine zu verarbeiten:

1. Generieren Sie das Token mit der Dienstkontorolle Fleet Engine Delivery Nicht vertrauenswürdiger Treibernutzer.

2. Stellen Sie der Treiberanwendung ein Token mit eingeschränktem Gültigkeitsbereich zur Verfügung. Mit diesem Bereich kann er nur den Gerätestandort in Fleet Engine aktualisieren.

Dieser Ansatz sorgt dafür, dass bei Aufrufen von Mobilgeräten – als Low-Trust-Umgebungen – das Prinzip der geringsten Berechtigung eingehalten wird.

Andere Dienstkontorollen

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

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

Einen Arbeitstag modellieren

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

Uhrzeit	Aktivitäten	Modellierung
Innerhalb von 24 Stunden nach Tagesbeginn	Der Disponent weist die Lieferungen an Lieferfahrzeuge oder -routen zu.	Sie können in Fleet Engine Aufgaben für Lieferungen, Abholungen, Pausen und andere im Voraus erstellen. Sie können beispielsweise eine Aufgabe für die Abholung der Sendung, eine Aufgabe für die Lieferung, eine geplante Nichtverfügbarkeit oder eine geplante Haltestelle erstellen. Weisen Sie einem Fahrzeug Aufgaben zu, sobald die Pakete und die Reihenfolge, in der sie zugestellt werden sollen, festgelegt wurden.
Tagesbeginn	Der Fahrer meldet sich in der Driver App an und startet den Tag im Depot.	Initialisieren Sie die Delivery Driver API. Erstellen Sie das Lieferfahrzeug nach Bedarf in Fleet Engine.
	Der Fahrer lädt die Sendungen auf das Lieferfahrzeug und scannt sie.	Wenn Versandzustellungsaufgaben nicht im Voraus erstellt wurden, erstellen Sie Versandzustellungsaufgaben beim Scannen.
	Der Fahrer bestätigt die Reihenfolge der auszuführenden Aufgaben.	Wenn diese nicht vorab erstellt wurden, musst du Aufgaben für die Abholung der Sendung, geplante Nichtverfügbarkeit und geplante Haltestellen erstellen.
	Der Fahrer verlässt das Depot und übergibt die nächsten zu erledigenden Aufgaben.	Weisen Sie dem Fahrzeug alle Aufgaben oder einen Teil von Aufgaben zu, indem Sie deren Abschlussreihenfolge festlegen.
	Der Fahrer liefert eine Sendung.	Nachdem du an der Lieferstelle angekommen bist, kannst du Aktionen für ein Fahrzeug, das an einer Haltestelle ankommt, ausführen. Nachdem die Sendung zugestellt wurde, schließe die Lieferaufgabe und gegebenenfalls den Versandstatus des Geschäfts und andere Metainformationen. Nachdem Sie alle Aufgaben an der Haltestelle abgeschlossen haben und bevor Sie zur nächsten Haltestelle fahren, führen Sie Aktionen in Bezug auf das Fahrzeug beendet an einer Haltestelle und Fahrzeug auf dem Weg zur nächsten Haltestelle aus.
	Der Fahrer trifft auf ein Zubringer, um weitere Lieferungen auf das Lieferfahrzeug zu übergeben.	Der Treffpunkt für einen Umstieg zwischen Feeder- und Lieferfahrzeugen sollte als geplante Haltestelle modelliert werden. Nach dem Übertragen und Scannen der Sendungen können Sie Zustellaufgaben erstellen, falls diese noch nicht erstellt wurden. Aktualisieren Sie dann die Reihenfolge der Aufgabenerledigung. Dazu weisen Sie einem Fahrzeug Aufgaben zu und aktualisieren die Aufgabenreihenfolge.
	Der Fahrer wird über eine Abholanfrage benachrichtigt.	Nachdem Sie die Abholanfrage angenommen haben, erstellen Sie eine Abholaufgabe für die Sendung. Aktualisieren Sie dann die Reihenfolge der Aufgabenausführung, indem Sie einem Fahrzeug Aufgaben zuweisen und die Aufgabenreihenfolge aktualisieren.
12:00 Uhr	Der Fahrer macht eine Mittagspause.	Wenn ein Standort mit der Nichtverfügbarkeitsaufgabe verknüpft ist, behandeln Sie ihn wie jede andere Aufgabe. Aktionen für ein Fahrzeug ausführen, das an einer Haltestelle ankommt, das Fahrzeug an einer Haltestelle hält und ein Fahrzeug auf der Route zur nächsten Haltestelle unterwegs ist. Andernfalls sind bis zum Ende der Werbeunterbrechung keine weiteren Maßnahmen erforderlich. Entfernen Sie die Aufgabe. Bestätigen Sie dazu die nächsten und verbleibenden Aufgaben und aktualisieren Sie die Aufgabenreihenfolge.
	Der Fahrer holt eine Sendung ab.	Dies wird wie eine Auslieferungshaltestelle modelliert. Aktionen für ein Fahrzeug, das an einer Haltestelle ankommt, und für das Schließen einer Aufgabe gilt, und optional das Speichern des Versandstatus und anderer Metainformationen. Nachdem Sie alle Aufgaben an der Haltestelle abgeschlossen haben und bevor Sie zur nächsten Haltestelle fahren, führen Sie Aktionen in Bezug auf das Fahrzeug beendet an einer Haltestelle und Fahrzeug auf dem Weg zur nächsten Haltestelle aus. Hinweis: Für eine korrekte Abrechnung muss für alle Abholungen eine entsprechende Lieferaufgabe vorhanden sein. Wenn die Abholung an einen anderen Ort auf der gleichen Route des Fahrers an diesem Tag geliefert werden soll, empfehlen wir, diese Lieferaufgabe wie jede andere Lieferaufgabe auf der Route zu modellieren. Wenn der Fahrer den Abholer zurück ins Depot bringt, empfehlen wir, eine Lieferaufgabe am Zielort zu erstellen.
	Der Fahrer hält einen geplanten Halt an, um Sendungen aus einer Ablagebox abzuholen.	Diese Haltestelle wird genauso modelliert wie jede andere Abholstelle. Aktionen für ein Fahrzeug, das an einer Haltestelle ankommt und eine Aufgabe schließt, ausführen Nachdem Sie alle Aufgaben an der Haltestelle abgeschlossen haben und die Fahrt zur nächsten Haltestelle gestartet haben, führen Sie Aktionen in Bezug auf das Fahrzeug beendet an einer Haltestelle und Fahrzeug auf dem Weg zur nächsten Haltestelle aus.
	Der Fahrer erhält eine Benachrichtigung, dass eine Sendung an einen anderen Ort umgeleitet wird.	Legen Sie den ursprünglichen Status der Lieferaufgabe auf ABGESCHLOSSEN fest und erstellen Sie eine neue Lieferaufgabe für den neuen Lieferort. Weitere Informationen finden Sie unter Sendung umleiten.
	Der Fahrer hat versucht, ein Paket zuzustellen, konnte dies jedoch nicht.	Dies wird ähnlich wie ein erfolgreicher Auslieferungsstopp modelliert, wobei die Bereitstellungsaufgabe als abgeschlossen gekennzeichnet wird. Aktionen für ein Fahrzeug, das an einer Haltestelle ankommt, ausführen Wenn die Sendung nicht zugestellt werden konnte, schließe die Aufgabe und gegebenenfalls den Versandstatus des Geschäfts und andere Meta-Informationen. Nachdem Sie alle Aufgaben an der Haltestelle abgeschlossen haben und bevor Sie zur nächsten Haltestelle fahren, führen Sie Aktionen in Bezug auf das Fahrzeug beendet an einer Haltestelle und Fahrzeug auf dem Weg zur nächsten Haltestelle aus.
	Der Fahrer wurde benachrichtigt, eine Sendung zurückzuhalten (nicht zuzustellen).	Nachdem die Benachrichtigung empfangen und bestätigt wurde, setzen Sie den Aufgabenstatus auf ABGESCHLOSSEN.
	Der Fahrer wurde benachrichtigt, als Nächstes eine bestimmte Sendung zuzustellen, wodurch die vergebene Lieferbestellung geändert wurde.	Aktualisieren Sie die Aufgabenreihenfolge.
	Der Fahrer liefert eine Sendung außerhalb der Bestellung.	Aktualisieren Sie die Aufgabenreihenfolge und fahren Sie dann wie gewohnt fort.
	Der Fahrer liefert mehrere Sendungen an einen einzigen Standort.	Dies wird ähnlich modelliert wie eine einzelne Lieferhaltestelle. Nach der Ankunft an der Haltestelle können Sie Aktionen für ein Fahrzeug, das an einer Haltestelle ankommt, ausführen. Nachdem du jede Sendung zugestellt hast, schließe alle Aufgaben und optional den Versandstatus des Geschäfts und andere Meta-Informationen. Nachdem Sie alle Aufgaben an der Haltestelle abgeschlossen haben und bevor Sie zur nächsten Haltestelle fahren, führen Sie Aktionen in Bezug auf das Fahrzeug beendet an einer Haltestelle und Fahrzeug auf dem Weg zur nächsten Haltestelle aus.
Tagesende	Der Fahrer kehrt ins Depot zurück.	Wenn der Fahrer ins Depot zurückkehrt und die Sendungen auf seiner Route abgeholt wurden, müssen Sie auch jedes Paket als Lieferaufgabe erstellen und schließen, um eine korrekte Abrechnung zu gewährleisten. Dazu können Sie das Warenlager wie jede andere Lieferhaltestelle modellieren. Wenn das Depot nicht als Lieferhaltestelle verwendet wird, können Sie es optional als geplante Haltestelle modellieren. Wenn Sie die Haltestelle modellieren, können Ihre Fahrer die Route zurück zum Depot sehen und wissen, wann Sie voraussichtlich ankommen.

So funktionieren Standortaktualisierungen

Um mit Fleet Engine die beste Leistung zu erzielen, sollten Sie einen Stream von Fahrzeugstandortaktualisierungen bereitstellen. Verwenden Sie eine der folgenden Methoden, um diese Aktualisierungen bereitzustellen:

1. Verwenden Sie das Driver SDK für Android oder iOS – die einfachste Option.
2. Benutzerdefinierten Code verwenden: Dies ist nützlich, wenn Standorte über Ihr Back-End weitergeleitet werden oder wenn Sie andere Geräte als Android oder iOS verwenden.

Unabhängig davon, wie Sie Aktualisierungen des Fahrzeugstandorts bereitstellen, ist Ihr Back-End für die Aktualisierung von Fleet Engine verantwortlich, wenn sich ein Lieferfahrzeug auf dem Weg zu einer Haltestelle (einschließlich des Depots) befindet und an einer Haltestelle ankommt. Fleet Engine erkennt diese Ereignisse nicht automatisch.

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 eine an einer Straße gelegene Stelle.

Der Lieferort ist der Ort, an den die Sendung geliefert oder abgeholt wird. Für die An- und Abreise 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 Geschäftseingangs. Das ist die Haltestelle des Fahrzeugs. Der Fahrer geht dann von der Fahrzeughaltestelle zu dem Ort im Einkaufszentrum, in dem sich das Geschäft befindet. Dies ist der Lieferort.

Damit deine Nutzer die Sendungsverfolgung optimal nutzen können, solltest du überlegen, wie Sendungsaufgaben den Fahrzeughaltestellen zugewiesen werden. Denk daran, dass die Anzahl der verbleibenden Fahrzeughaltestellen für Versandaufgaben dem Nutzer mitgeteilt wird, damit er den Fortschritt der Sendung nachvollziehen kann.

Wenn ein Fahrer beispielsweise 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 Ihre Nutzer weniger hilfreich, da die Sendungsverfolgung erst verfügbar ist, wenn sich das Fahrzeug innerhalb einer begrenzten Anzahl von Fahrzeughaltestellen vor seinem Ziel befindet. Wenn viele Fahrzeughalte innerhalb kurzer Zeit abgeschlossen werden, hat der Nutzer nicht viel Zeit, um den Fortschritt der Lieferung zu verfolgen.

Mobile SDKs verwenden

Bevor Sie das Driver 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 initialisiert hast. 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));
     }
   });

Hinweis:Das Driver SDK enthält APIs für verschiedene Branchen, einschließlich Auslieferungen. Verwenden Sie zum Reduzieren der Gesamtgröße des Binärprogramms ProGuard oder ein anderes Optimierungstool, um den nicht verwendeten Code zu entfernen.

Anwendungsfälle

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

Eindeutige Entitäts-IDs

Format und Wert der in REST-Aufrufen verwendeten eindeutigen Entitätskennungen sind für Fleet Engine intransparent. Verwenden Sie keine automatisch inkrementellen IDs und achten Sie darauf, dass sie keine personenidentifizierbaren Informationen wie die Telefonnummer des Fahrers enthält.

Fahrzeug erstellen

Sie können ein Fahrzeug entweder über das Driver SDK oder aus einer Serverumgebung mit gRPC oder REST erstellen.

gRPC

Um ein neues Fahrzeug zu erstellen, senden Sie einen CreateDeliveryVehicle-Aufruf an Fleet Engine. Verwende 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. Die ID des Fahrzeugs sollte im Feld DeliveryVehicleId festgelegt werden.

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

• Attribute
• LastLocation
• Typ

Legen Sie keine anderen Felder fest. In diesem Fall gibt Fleet Engine einen Fehler zurück, da diese Felder entweder schreibgeschützt sind oder nur mit einem Aufruf von UpdateDeliveryVehicle aktualisiert werden können.

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

Das folgende Beispiel zeigt, wie die Java gRPC-Bibliothek zum Erstellen eines Fahrzeugs verwendet wird:

    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 ausgestellt wird.

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

• Attribute
• lastLocation
• Typ

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äß der API-Anleitung für benutzerdefinierte IDs. Legen Sie keine anderen Felder fest. In diesem Fall gibt Fleet Engine einen Fehler zurück, da diese Felder entweder schreibgeschützt sind oder nur mit einem Aufruf von UpdateDeliveryVehicle aktualisiert werden können.

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

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 „Abholung einer Sendung“ erstellen

Sie können eine Aufgabe für die Abholung der Sendung entweder über das Driver SDK oder aus einer Serverumgebung mit gRPC oder REST erstellen.

gRPC

Das folgende Beispiel zeigt, wie Sie die Java gRPC-Bibliothek verwenden, um eine Aufgabe für die Abholung der Sendung zu 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

Wenn Sie eine Abholungsaufgabe aus einer Serverumgebung erstellen möchten, senden Sie einen HTTP REST-Aufruf an CreateTask:

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

<id> ist eine eindeutige Kennung für die Aufgabe. Es darf sich nicht um die Tracking-Nummer der Sendung handeln. Wenn Sie in Ihrem System keine Aufgaben-IDs haben, 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 ausgestellt wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  Typ	Type.PICKUP
  state	State.OPEN
  trackingId	Die Nummer oder die Kennung, mit der Sie eine Sendung verfolgen.
  plannedLocation	Der Standort, an dem die Aufgabe ausgeführt werden soll, in diesem Fall der Abholort der Sendung.
  taskDuration	Die voraussichtliche Zeit in Sekunden, die benötigt wird, um die Sendung am Abholort abzuholen.

• Optionale Felder:

  Field	Wert
  targetTimeWindow	Das Zeitfenster, in dem die Aufgabe abgeschlossen werden soll. Dies hat keinen Einfluss auf das Routingverhalten.
  Attribute	Eine Liste benutzerdefinierter Aufgabenattribute. 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 werden mit UpdateDeliveryVehicleRequest zugewiesen. Weitere Informationen finden Sie unter Einem Fahrzeug Aufgaben zuweisen und UpdateDeliveryVehicleRequest.

Beispiel eines curl-Befehls:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "PICKUP",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Aufgabe für die Zustellung einer Sendung erstellen

Sie können eine Sendungszustellungsaufgabe entweder über das Driver SDK oder aus einer Serverumgebung mit gRPC oder REST erstellen.

gRPC

Das folgende Beispiel zeigt, wie die Java gRPC-Bibliothek zum Erstellen einer Sendungszustellungsaufgabe verwendet wird:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

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

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Wenn Sie eine Sendungszustellungsaufgabe mit gRPC oder REST aus einer Serverumgebung erstellen möchten, führen Sie einen HTTP REST-Aufruf an CreateTask aus:

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

<id> ist eine eindeutige Kennung für die Aufgabe. Es darf sich nicht um die Tracking-Nummer der Sendung handeln. Wenn Sie in Ihrem System keine Aufgaben-IDs haben, 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 ausgestellt wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  Typ	Type.DELIVERY
  state	State.OPEN
  trackingId	Die Nummer oder die Kennung, mit der Sie eine Sendung verfolgen.
  plannedLocation	Der Ort, an dem die Aufgabe ausgeführt werden soll, in diesem Fall der Lieferort für diese Sendung.
  taskDuration	Die voraussichtliche Zeit in Sekunden, die es dauert, bis die Sendung am Lieferort abgegeben wird.

• Optionale Felder:

  Field	Wert
  targetTimeWindow	Das Zeitfenster, in dem die Aufgabe abgeschlossen werden soll. Dies hat keinen Einfluss auf das Routingverhalten.
  Attribute	Eine Liste benutzerdefinierter Aufgabenattribute. 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 werden mit UpdateDeliveryVehicleRequest zugewiesen. Weitere Informationen finden Sie unter Einem Fahrzeug Aufgaben zuweisen und UpdateDeliveryVehicleRequest.

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

Batch-Erstellungsaufgaben

Mit gRPC oder REST können Sie einen Batch von Aufgaben aus einer Serverumgebung erstellen.

gRPC

Das folgende Beispiel zeigt, wie die Java gRPC-Bibliothek verwendet wird, um zwei Aufgaben zu erstellen, eine für eine Lieferung und eine für eine 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

Wenn Sie eine Zustell- und Abholaufgabe aus einer Serverumgebung erstellen möchten, führen Sie einen HTTP-REST-Aufruf an BatchCreateTasks aus:

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 ausgestellt wird.

Der Anfragetext muss eine BatchCreateTasksRequest-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  Anfragen	Array<CreateTasksRequest>

• Optionale Felder:

  Field	Wert
  Header	„DeliveryRequestHeader“

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

Weitere Informationen finden Sie in der API-Referenzdokumentation für 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 Fahrerausfälle oder Tanken), entweder über das Driver SDK oder aus einer Serverumgebung mit gRPC oder REST. Eine geplante Aufgabe zur Nichtverfügbarkeit darf keine Tracking-ID enthalten. Optional können Sie einen Standort angeben.

gRPC

Das folgende Beispiel zeigt, wie die Java gRPC-Bibliothek zum Erstellen einer Nichtverfügbarkeitsaufgabe verwendet wird:

    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

Führen Sie einen HTTP REST-Aufruf an CreateTask aus, um eine Nichtverfügbarkeitsaufgabe 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 Sie in Ihrem System keine Aufgaben-IDs haben, 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 ausgestellt wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  Typ	Type.UNAVAILABLE
  state	State.OPEN
  taskDuration	Die Länge der Unterbrechung in Sekunden.

• Optionale Felder:

  Field	Wert
  plannedLocation	Die Stelle der Unterbrechung, wenn sie an einer bestimmten Stelle 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 werden mit UpdateDeliveryVehicleRequest zugewiesen. Weitere Informationen finden Sie unter Einem Fahrzeug Aufgaben zuweisen und UpdateDeliveryVehicleRequest.

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 Haltestellen

Sie können eine geplante Stoppaufgabe entweder über das Driver SDK oder über eine Serverumgebung mit gRPC oder REST erstellen. Ein geplanter Stopp-Task darf keine Tracking-ID enthalten.

gRPC

Das folgende Beispiel zeigt, wie Sie die Java gRPC-Bibliothek verwenden, um eine Aufgabe für geplante Stopps zu 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 Sie in Ihrem System keine Aufgaben-IDs haben, 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 ausgestellt wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  Typ	Type.SCHEDULED_STOP
  state	State.OPEN
  plannedLocation	Die Position der Haltestelle.
  taskDuration	Die erwartete Dauer des Stopps in Sekunden.

• Optionale Felder:

  • Keine

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 werden mit UpdateDeliveryVehicleRequest zugewiesen. Weitere Informationen finden Sie unter Einem Fahrzeug Aufgaben zuweisen und UpdateDeliveryVehicleRequest.

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

Zielfenster festlegen

Das Zielzeitfenster ist das TimeWindow-Element, in dem die Aufgabe abgeschlossen werden soll. Wenn Sie den Empfängern der Zustellung beispielsweise ein Zeitfenster für die Zustellung mitteilen, können Sie dieses Zeitfenster mithilfe des Zielzeitfensters der Aufgabe erfassen und Benachrichtigungen generieren oder mithilfe des Felds die Leistung nach der Fahrt analysieren.

Das Zielzeitfenster besteht aus einer Start- und einer Endzeit und kann für jeden Aufgabentyp festgelegt werden. Das Zeitfenster hat 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 über 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 ausgestellt wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  targetTimeWindow	Das Zeitfenster, in dem die Aufgabe abgeschlossen werden soll. Diese Einstellung hat keinen Einfluss auf das Routingverhalten

• Optionale Felder:

  • Keine

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

Konfiguration für die Sichtbarkeit von Aufgaben-Tracking festlegen

Die Sichtbarkeit der Daten in der Bibliothek für die Sendungsverfolgung und der von einem Aufruf an GetTaskTrackingInfo zurückgegebenen Daten kann für einzelne Aufgaben durch Festlegen einer TaskTrackingViewConfig für die Aufgabe gesteuert werden. Weitere Informationen finden Sie unter Aufgaben im aktiven Fahrzeug. Dies kann beim Erstellen oder Aktualisieren der Aufgabe erfolgen. Im folgenden Beispiel wird die Aufgabe mit dieser Konfiguration aktualisiert:

gRPC

Das folgende Beispiel zeigt, wie die Java gRPC-Bibliothek verwendet wird, um die Konfiguration der Aufgaben-Tracking-Ansicht festzulegen:

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 über 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 ausgestellt wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  taskTrackingViewConfig	Die Konfiguration für das Aufgaben-Tracking, die angibt, welche Datenelemente unter welchen Umständen für Endnutzer sichtbar sind.

• Optionale Felder:

  • Keine

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

Sie weisen einem Lieferfahrzeug Aufgaben zu, indem Sie die Aufgabenreihenfolge für das Fahrzeug aktualisieren. Die Aufgabenreihenfolge für ein Fahrzeug wird anhand der Liste der Haltestellen für das Lieferfahrzeug bestimmt. Sie können jeder Fahrzeughaltestelle eine oder mehrere Aufgaben zuweisen. Weitere Informationen finden Sie unter Aufgabenreihenfolge aktualisieren.

Wenn Sie eine Sendung von einem Fahrzeug auf ein anderes übertragen möchten, schließen Sie die ursprüngliche Aufgabe und erstellen Sie sie neu, bevor Sie sie dem neuen Fahrzeug zuweisen. Wenn Sie die Aufgabenreihenfolge für eine Aufgabe aktualisieren, die bereits einem anderen Fahrzeug zugewiesen ist, erhalten Sie eine Fehlermeldung.

Aufgabenreihenfolge aktualisieren

Sie können die Aufgaben aktualisieren, die einem Fahrzeug zugewiesen sind und die entweder über das Driver SDK oder die Serverumgebung ausgeführt werden. Verwenden Sie nicht beide Methoden, um Race-Bedingungen zu vermeiden und eine Single Source of Truth zu verwalten.

Wenn Sie die Aufgabenreihenfolge für ein Fahrzeug aktualisieren, geschieht auch Folgendes:

• Weist Aufgaben zu, die für das Fahrzeug neu sind.
• Schließt alle Aufgaben, die dem Fahrzeug zuvor zugewiesen waren, aber nicht in der aktualisierten Reihenfolge sind.

Wenn Sie eine Sendung von einem Fahrzeug auf ein anderes übertragen möchten, schließen Sie die ursprüngliche Aufgabe. Erstellen Sie sie dann neu, bevor Sie ihr das neue Fahrzeug zuweisen. Wenn Sie die Aufgabenreihenfolge für eine Aufgabe aktualisieren, die bereits einem anderen Fahrzeug zugewiesen ist, erhalten Sie eine Fehlermeldung.

Sie können die Aufgabenreihenfolge jederzeit aktualisieren.

gRPC

Das folgende Beispiel zeigt, wie die Java gRPC-Bibliothek verwendet wird, um die Aufgabenreihenfolge für das Fahrzeug zu 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

Wenn Sie die Aufgabenreihenfolge für ein Fahrzeug aus einer Serverumgebung aktualisieren 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 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 ausgestellt wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  remainingVehicleJourneySegments	Eine Liste der Journey-Segmente 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	Geplanter Ort für die Haltestelle.
  verbleibendeVehicleJourneySegments[i].stop.tasks	Eine Liste der Aufgaben, die an dieser Fahrzeughaltestelle auszuführen sind.
  remainingVehicleJourneySegments[i].stop.state	State.NEW

• Optionale Felder:

  • Keine

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

Beispiel eines curl-Befehls:

Hinweis :Mit diesem Befehl werden alle remainingVehicleJourneySegments überschrieben, die bereits im Lieferfahrzeug festgelegt wurden.

# 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

Fahrzeug ist auf dem Weg zur nächsten Haltestelle

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 eine Serverumgebung mit gRPC oder REST benachrichtigen. Verwenden Sie nicht beide Methoden, um Race-Bedingungen zu vermeiden und eine Single Source of Truth zu erhalten.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek Fleet Engine informieren, dass ein Fahrzeug auf dem Weg 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 Fleet Engine benachrichtigen möchten, dass ein Fahrzeug von einer Serverumgebung zur nächsten Haltestelle fährt, senden Sie einen HTTP REST-Aufruf an UpdateDeliveryVehicle:

`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 ausgestellt wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfeld:

  Field	Wert
  remainingVehicleJourneySegments	Liste der verbleibenden Fahrzeughaltestellen, deren Status als State.NEW gekennzeichnet ist. Der Bundesstaat der ersten Haltestelle auf der Liste muss als State.ENROUTE gekennzeichnet sein.

• Optionale Felder:

  • Keine

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

Beispiel eines curl-Befehls:

Hinweis :Mit diesem Befehl werden alle remainingVehicleJourneySegments überschrieben, die bereits im Lieferfahrzeug festgelegt wurden.

# 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

Fahrzeugstandort aktualisieren

Wenn Sie das Driver SDK nicht verwenden, um den Standort des Fahrzeugs zu aktualisieren, können Sie den Standort des Fahrzeugs direkt an Fleet Engine aufrufen. Für jedes aktive Fahrzeug erwartet Fleet Engine mindestens einmal pro Minute und höchstens einmal alle fünf Sekunden ein Standortupdate.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek den Standort eines Fahrzeugs in Fleet Engine aktualisieren:

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 myDeliveryVehicle = DeliveryVehicle.newBuilder()
    .setLastLocation(DeliveryVehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(myDeliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("last_location"))
      .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 den Standort eines Fahrzeugs in Fleet Engine mithilfe von HTTP REST aktualisieren möchten, rufen Sie UpdateDeliveryVehicle auf:

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

<id> ist eine eindeutige Kennung für das Lieferfahrzeug in Ihrer Flotte bzw. das Lieferfahrzeug, das Sie 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 ausgestellt wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfeld:

  Field	Wert
  lastLocation.supplementalLocation	Der Standort des Fahrzeugs.
  lastLocation.supplementalLocationTime	Der letzte bekannte Zeitstempel, an dem sich das Fahrzeug befand.
  lastLocation.supplementalLocationSensor	Sollte mit CUSTOMER_SUPPLIED_LOCATION ausgefüllt sein.

• Optionale Felder:

  Field	Wert
  lastLocation.supplementalLocationAccuracy	Genauigkeit des angegebenen Standorts in Metern.

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
{
  "lastLocation": {
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
  }
}
EOM

Fahrzeug kommt an einer Haltestelle an

Fleet Engine muss benachrichtigt werden, wenn ein Fahrzeug an einer Haltestelle ankommt. Sie können Fleet Engine entweder über das Driver SDK oder über eine Serverumgebung mit gRPC oder REST benachrichtigen. Verwenden Sie nicht beide Methoden, um Race-Bedingungen zu vermeiden und eine Single Source of Truth zu erhalten.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek Fleet Engine 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 in einer Serverumgebung über die Ankunft eines Fahrzeugs an einer Haltestelle informieren möchten, senden Sie einen HTTP REST-Aufruf an UpdateDeliveryVehicle:

`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 ausgestellt wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  remainingVehicleJourneySegments	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:

  • Keine

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

Beispiel eines curl-Befehls:

Hinweis :Mit diesem Befehl werden alle remainingVehicleJourneySegments überschrieben, die bereits im Lieferfahrzeug festgelegt wurden.

# 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

Fahrzeug hält an

Fleet Engine muss benachrichtigt werden, wenn ein Fahrzeug anhält. Dadurch werden alle mit der Haltestelle verbundenen Aufgaben auf den Status CLOSED gesetzt. Sie können Fleet Engine entweder über das Driver SDK oder über eine Serverumgebung mit gRPC oder REST benachrichtigen. Verwenden Sie nicht beide Methoden, um Race-Bedingungen zu vermeiden und eine Single Source of Truth zu erhalten.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek Fleet Engine informieren, dass ein Fahrzeug eine Haltestelle 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, senden Sie einen HTTP REST-Aufruf an UpdateDeliveryVehicle:

`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 ausgestellt wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  remaining_vehicle_journey_segments	Die Haltestelle sollte nicht mehr in der Liste der verbleibenden Fahrzeughaltestellen enthalten sein.

• Optionale Felder:

  • Keine

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

Beispiel eines curl-Befehls:

Hinweis :Mit diesem Befehl werden alle remainingVehicleJourneySegments überschrieben, die bereits im Lieferfahrzeug festgelegt wurden.

    # 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}"
              }
            ]
          }
        }
      ]
    }
    EOM

Aufgaben aktualisieren

Die meisten Aufgabenfelder sind unveränderlich. Sie können jedoch Status, Aufgabenergebnis, Zeit des Aufgabenergebnisses, Ort der Aufgabenergebnisse und Attribute ändern, indem Sie die Aufgabenentität direkt aktualisieren. Wenn beispielsweise eine Aufgabe keinem Fahrzeug zugewiesen wurde, können Sie die Aufgabe schließen, indem Sie den Status direkt aktualisieren.

gRPC

Dies ist ein Beispiel für das Aktualisieren einer Aufgabe über gRPC.

REST

Dies ist ein Beispiel für das Aktualisieren einer Aufgabe über REST.

Aufgaben schließen

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

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

Das Schließen einer Aufgabe ist kein Hinweis auf Erfolg oder 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 angezeigt werden kann.

gRPC

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) // You can only directly CLOSE a
  .build();                    // task that 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;
}

REST

Wenn Sie eine Aufgabe in einer Serverumgebung als geschlossen markieren möchten, führen Sie einen HTTP REST-Aufruf an UpdateTask aus:

`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 ausgestellt wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  state	State.CLOSED

• Optionale Felder:

  Field	Wert
  taskOutcome	Result.SUCCEEDED (ERFOLGREICH) oder ergebnis.FEHLGESCHLAGEN
  taskOutcomeTime	Die Zeit, zu der die Aufgabe abgeschlossen wurde.
  taskOutcomeLocation	Der Standort, an dem die Aufgabe abgeschlossen wurde. In Fleet Engine ist dies standardmäßig der letzte Fahrzeugstandort, sofern er 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

Aufgabenergebnis und Ergebnisort festlegen

Das Schließen einer Aufgabe weist weder auf Erfolg noch Misserfolg hin, sondern weist darauf hin, 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 angezeigt werden kann und die Dienste ordnungsgemäß abgerechnet werden. Nachdem dieser Wert festgelegt wurde, können Sie das Ergebnis der Aufgabe nicht mehr ändern. Sie können jedoch die Zeit und den Ort der Aufgabenergebnisse ändern, nachdem sie festgelegt wurden.

Für Aufgaben, die sich im Status CLOSED (GESCHLOSSEN) befinden, kann das Ergebnis entweder auf SUCCEEDED (Erfolgreich) oder FAILED (FEHLGESCHLAGEN) gesetzt werden. Fleet Engine berechnet nur Lieferaufgaben mit dem Status ERFOLGREICH.

Beim Markieren des Ergebnisses einer Aufgabe füllt Fleet Engine den Ort des Aufgabenergebnisses automatisch mit dem letzten bekannten Fahrzeugstandort aus. Sie können dieses Verhalten überschreiben.

gRPC

Sie können den Speicherort des Aufgabenergebnisses festlegen, wenn Sie das Ergebnis festlegen. Wenn der Standort festgelegt ist, kann Fleet Engine ihn nicht auf den Standardwert des letzten Fahrzeugstandorts setzen. Sie können auch den von Fleet Engine festgelegten Speicherort für Aufgabenergebnisse auch später überschreiben. Von Ihnen angegebene Speicherorte für Aufgabenergebnisse werden von Fleet Engine nie überschrieben. Sie können keinen Speicherort für Aufgabenergebnisse für eine Aufgabe festlegen, für die kein Aufgabenergebnis festgelegt ist. Sie können sowohl das Aufgabenergebnis als auch den Speicherort des Aufgabenergebnisses in derselben Anfrage festlegen.

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek ein Aufgabenergebnis auf SUCCEEDED und den Standort 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;
}

REST

Wenn Sie eine Aufgabe in einer Serverumgebung als abgeschlossen markieren möchten, führen Sie einen HTTP REST-Aufruf an UpdateTask aus:

`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 ausgestellt wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  taskOutcome	Result.SUCCEEDED (ERFOLGREICH) oder ergebnis.FEHLGESCHLAGEN

• Optionale Felder:

  Field	Wert
  taskOutcomeLocation	Der Standort, an dem die Aufgabe abgeschlossen wurde. Wenn nichts festgelegt ist, wird von Fleet Engine standardmäßig der letzte Fahrzeugstandort verwendet.
  taskOutcomeTime	Der Zeitstempel für den Zeitpunkt, an dem die Aufgabe abgeschlossen wurde.

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. Um eine Sendung umzuleiten, 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.

Zustell- und Lieferfahrzeuge verwenden

Wenn Sie Zubringerfahrzeuge für den Transport von Lieferungen zu Lieferfahrzeugen im Tagesverlauf verwenden, modellieren Sie die Übertragung von Sendungen als geplante Haltestelle für das Lieferfahrzeug. Damit eine genaue Standortverfolgung sichergestellt ist, weisen Sie einer übergebenen Sendung erst dann eine Lieferaufgabe zu, nachdem sie auf das Lieferfahrzeug geladen 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. Möglicherweise möchten Sie jedoch andere spezifische Metadaten für die Sendung aktualisieren. Zum Speichern anderer Metainformationen, 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.

Nach Fahrzeug suchen

Sie können ein Fahrzeug entweder über das Driver SDK oder über eine Serverumgebung mit gRPC oder REST ermitteln.

gRPC

Das folgende Beispiel zeigt, wie die Java gRPC-Bibliothek für die Suche nach einem Fahrzeug verwendet wird:

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 ausgestellt wird.

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 mithilfe von gRPC oder REST eine Aufgabe aus einer Serverumgebung abrufen. Das Driver SDK unterstützt das Suchen nach einer Aufgabe nicht.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek eine 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 aufgerufen 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 ausgestellt wird.

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 Sendungs-ID abrufen

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

• Nach Aufgaben-ID: Wird von Nutzern wie Flottenbetreibern verwendet, die Zugriff auf die vollständige Ansicht der Aufgabendaten haben.
• Über eine Tracking-ID: Wird von Ihrer Clientsoftware verwendet, um einem Endnutzer begrenzte Informationen bereitzustellen, z. B. wann ein Paket in seinem Haus erwartet wird.

In diesem Abschnitt wird beschrieben, wie Sie Aufgabeninformationen über eine Tracking-ID abrufen. Wenn Sie eine Aufgabe anhand der Aufgaben-ID suchen möchten, gehen Sie zu Aufgabe suchen.

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

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

Lookup-Anforderungen

• Versandinformationen, die über eine Tracking-ID zur Verfügung gestellt werden, entsprechen den Sichtbarkeitsregeln, die unter Sichtbarkeit von beobachteten Standorten steuern beschrieben sind.

• Mit Fleet Engine können Sie Versandinformationen anhand der Sendungsverfolgungs-ID abrufen. Das Driver SDK unterstützt die Informationssuche über Tracking-IDs nicht. Dazu verwenden Sie entweder eine Server- oder eine Browserumgebung.

• Verwenden Sie möglichst kleine Tokens, 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 Sendungsaufgabe anhand der 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

Wenn Sie eine Versandaufgabe über einen Browser aufrufen möchten, 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 Tracking-ID, die der Aufgabe zugewiesen ist.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine Token Factory ausgestellt 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 über eine Server- oder Browserumgebung auflisten. Das Driver SDK unterstützt das Auflisten von Aufgaben nicht.

Für das Auflisten von Aufgaben ist umfassenden Zugriff auf Tasks erforderlich. Das Auflisten von Aufgaben ist nur für vertrauenswürdige Nutzer gedacht. Verwenden Sie für Anfragen zu Listenaufgaben die „Delivery Fleet Reader“ oder „Delivery Super User Authentication Tokens“.

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 Filterabfragesyntax finden Sie unter AIP-160. Die folgende Liste enthält gültige Aufgabenattribute, die Sie zum Filtern verwenden können:

• Attribute
• delivery_vehicle_id
• state
• planned_location
• task_duration
• task_outcome
• task_outcome_location
• task_outcome_location_source
• task_outcome_time
• tracking_id
• Typ

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

Feldtyp	Format	Beispiel
Zeitstempel	RFC-3339	task_outcome_time = 2022-03-01T11:30:00-08:00
Dauer	Anzahl der Sekunden, gefolgt von einem s	task_duration = 120s
Enum	String	state = CLOSED AND type = PICKUP
Standort	point.latitude und point.longitude	planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

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 für Listenaufgaben 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.

Hinweis: Das Filtern nach Aufgabenattributen kann die Abruflatenz erheblich erhöhen und sollte mit Vorsicht verwendet 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 immer noch leer sein. Eine leere Antwort bedeutet, dass der bereitgestellten DeliveryVehicleId keine Tasks zugeordnet sind.

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 „filter“-URL-Parameter mit einer URL-Escaping-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 ausgestellt wird.

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

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

Eine erfolgreiche Antwort kann immer noch leer sein. Eine leere Antwort gibt an, 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 über eine Server- oder Browserumgebung auflisten. Das Driver SDK unterstützt keine Einträge für Lieferfahrzeuge.

Das Auflisten von Lieferfahrzeugen erfordert umfassenden Zugriff auf Lieferfahrzeuge und ist nur für vertrauenswürdige Nutzer gedacht. Verwende „Delivery Fleet Reader“ oder „Delivery Super User Authentication Tokens“, wenn du Anfragen für Listenlieferungsfahrzeuge stellst.

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

• CurrentRouteSegment
• RemainingVehicleJourneySegments

Sie können die Liste der Lieferfahrzeuge nach ihrer attributes-Eigenschaft 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. Um mehrere Attribute abzufragen, verknüpfen Sie Abfragen mit den logischen AND- und OR-Operatoren wie in attributes.key1 = value1 AND attributes.key2 = value2. 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 mithilfe von zwei Begrenzungskoordinaten: ein Paar aus Breiten- und Längengradkoordinaten high (Nordost) und low (Südwest). Anfragen werden abgelehnt, wenn sie einen hohen Breitengrad enthalten, der geografisch niedriger als ein niedriger Breitengrad ist.

Hinweis :Wenn Sie weder eine Filterabfrage noch einen Darstellungsbereich angeben, enthält die Antwort alle Lieferfahrzeuge.

Die Listen der Lieferfahrzeuge werden standardmäßig auf einer angemessenen Seitengröße angeordnet. Wenn Sie eine Seitengröße angeben, gibt die Anfrage nur die Anzahl der Fahrzeuge zurück, die durch das Limit festgelegt ist, oder weniger. Wenn die angeforderte Seitengröße einen internen Maximalwert überschreitet, wird der interne Maximalwert verwendet. Die Standard- und die maximale Seitengröße beträgt 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 immer noch leer sein. In diesem Fall befinden sich noch 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 „filter“-URL-Parameter mit einer URL-Escaping-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 ausgestellt wird.

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

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

Eine erfolgreiche Antwort kann immer noch 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, die in Fleet Engine erfasst werden, visualisieren. Sie enthält eine JavaScript-Kartenkomponente, die ein Drop-in-Ersatz für ein standardmäßiges „google.maps.Map“-Objekt ist, sowie Datenkomponenten für die Verbindung mit Fleet Engine. Mit dieser Komponente können Sie eine anpassbare, animierte Flottenverfolgung über eine Web- oder mobile App bereitstellen.

• Implementieren Sie mithilfe der Fleet Engine Deliveries API Ihre eigene Flottenverfolgung.

Der Schlüssel besteht darin, Flottenaufgaben anhand der Tracking-ID abzurufen.

Logging

Sie können Fleet Engine so einrichten, dass RPC-Logs an Cloud Logging gesendet werden. Weitere Informationen finden Sie unter Logging.

Autorisierungsrollen und Tokens

Wie unter Fahrzeug- und Aufgabenlebenszyklus verwalten und in den Autorisierungshinweisen für einzelne Anwendungsfälle beschrieben, ist für Aufrufe von Fleet Engine eine Authentifizierung mit JSON Web Tokens erforderlich, die mit Dienstkonto-Anmeldedaten signiert wurden. Die Dienstkonten, die zum Ausstellen 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.

Häufige Probleme beheben

In den folgenden Abschnitten finden Sie weitere Informationen, falls Probleme auftreten.

Robustheit

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

Verlorener Status in Fleet Engine

Implementieren Sie bei der Arbeit mit Fleet Engine Clients, damit das System sich selbst heilt, wenn ein Fehler auftritt. Wenn Fleet Engine beispielsweise versucht, ein Fahrzeug zu aktualisieren, wird möglicherweise ein Fehler zurückgegeben, der darauf hinweist, dass das Fahrzeug nicht vorhanden ist. Der Kunde sollte das Fahrzeug dann im neuen Zustand neu erstellen. Dieses Problem tritt nur selten auf. Ihr System sollte aber stabil genug sein, um es zu bewältigen.

Im äußerst unwahrscheinlichen Szenario eines katastrophalen Ausfalls von 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 noch einmal fehlschlagen, da Kontingentprüfungen eingerichtet sind, um DoS-Angriffe (Denial of Service) zu vermeiden. Verlangsamen Sie in diesem Fall die Neuerstellungsrate mithilfe einer Backoff-Strategie für neue Versuche.

Verloren-Status in der Fahrer-App

Wenn die Treiber-App abstürzt, muss die App 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 wiederhergestellt werden. Die Anwendung sollte außerdem die Liste der Haltestellen für das Driver SDK neu erstellen und explizit festlegen.

Hinweis: Diese Wiederherstellungen müssen autonom erfolgen, ohne Informationen von Fleet Engine zu verwenden. Ausgenommen sind Fehler, 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.

Häufig gestellte Fragen

Was passiert, wenn ein Fahrer in einer falschen Reihenfolge bei einer Aufgabe anhält?

Aktualisieren Sie in diesem Fall zuerst die Reihenfolge der Aufgaben und fahren Sie dann wie gewohnt fort. Markieren Sie in diesem Fall die Ankunft an der Haltestelle, den Abschluss der Aufgabe und andere Details. Andernfalls kann das System inkonsistent werden, voraussichtliche Ankunftszeiten werden falsch und unerwartete Fehler werden gemeldet.