Erste Schritte mit Fleet Engine für die Sendungsverfolgung

Modellieren Sie Ihre Flottenaktivitäten für die erste und letzte Meile von Lieferungen mit der Fleet Engine Deliveries API. Sie können diese API mit dem 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 Web Tokens 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 von Dienstkonten, ob die Einrichtung abgeschlossen ist und Sie ein Lieferfahrzeug erstellen können. Wenn Sie die Einrichtung sofort verifizieren, stellen Sie sicher, dass Sie häufige Autorisierungsprobleme behoben haben, die bei der Einrichtung Ihres Projekts auftreten können. Es gibt zwei Möglichkeiten, die Konfiguration zu überprüfen:

• Teste zwei wichtige Teile deiner Einrichtung: das Signieren von Autorisierungstokens und das Erstellen eines Testfahrzeugs mit dem gcloud-Befehlszeilendienstprogramm. Weitere Informationen finden Sie in der Anleitung Einrichtung überprüfen.

• Testen Sie Ihre Einrichtung mit den Fleet Engine-Auth-Beispielskripts.

Clientbibliotheken

Verwenden Sie die Clientbibliotheken in mehreren gängigen Programmiersprachen, um die Entwicklung im Vergleich zu gRPC oder REST im Rohformat zu verbessern. Eine Anleitung zum Abrufen von Clientbibliotheken für Ihre Serveranwendung finden Sie unter Clientbibliotheken.

In 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 zum Transport der Sendung verwendet wird.
• Die Aufgaben zur Abholung und Lieferung von Lieferungen.

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

Lieferfahrzeuge

Lieferfahrzeuge transportieren Lieferungen von einem Depot zu einem Lieferort und von einem Abholort zum Depot. In bestimmten Fällen kann eine Sendung auch direkt vom Abholort zum Lieferort transportiert werden.

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

Aufgaben

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

• Weisen Sie für Abholungen und Lieferungen Versandaufgaben zu.
• Wenn Fahrer nicht verfügbar sind, z. B. bei erforderlichen Pausen, weisen Sie Nichtverfügbarkeitsaufgaben zu.
• Für Aufgaben, die nicht fahren, an Briefkästen oder Kundenstandorten, weisen Sie geplante Haltestellenaufgaben 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, werden alle Aufgaben und die Reihenfolge, in der sie geplant sind, für Schätzungen verwendet. 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 Abholung und Zustellung einer Sendung und geben Sie die folgenden Informationen an:

• Der Ort der Abholung oder Lieferung.
• Eine Tracking-Nummer oder -ID.
• Eine Verweildauer, um zusätzliche Zeit zu berücksichtigen, um die Aufgabe zu erledigen, nach einem Parkplatz zu suchen oder zu Fuß zum Übergabeort zu gehen.
• Eine eindeutige Aufgaben-ID. Siehe Richtlinien für Aufgaben-ID.

Weitere Informationen finden Sie unter folgenden Links:

Android

• Abholaufgabe erstellen
• Versandaufgabe erstellen

iOS

• GMTD DeliveryTaskManager
• GMTSTaskType

Nicht verfügbare Aufgaben

Nichtverfügbarkeitsaufgaben umfassen Zeiträume, in denen ein Fahrzeug nicht zum Abholen oder Lieferservice verfügbar ist, z. B. Pausen zum Tanken des Fahrzeugs oder Ruhepausen für Fahrer.

Erstellen Sie eine Nichtverfügbarkeitsaufgabe mit den folgenden Informationen:

• Die Länge der Pause.
• Optional den Ort der Unterbrechung. Sie müssen keinen bestimmten Standort angeben, aber dadurch erhalten Sie genauere voraussichtliche Ankunftszeiten für den ganzen Tag.

Hinweis :Bei Nichtverfügbarkeitsaufgaben werden keine Standortinformationen an die Endnutzer der Sendungsverfolgungsbibliothek weitergegeben. Sie ist jedoch für Flottenmanager verfügbar, die die Fleet Tracking Library verwenden.

Weitere Informationen finden Sie unter folgenden Links:

Android

• Geplante Nichtverfügbarkeit

iOS

• GMTD DeliveryTaskManager
• GMTSTaskType

Geplante Aufgaben zum Stoppen

Erstellen Sie geplante Haltestellenaufgaben, um die Haltestellen zu modellieren, die ein Lieferfahrzeug machen muss. Sie können beispielsweise eine geplante Haltestellenaufgabe für eine täglich geplante Abholstation an einem bestimmten Ort erstellen, unabhängig von anderen Lieferungen oder Abholungen am selben Ort. Sie können auch geplante Haltestellenaufgaben für Sammlungen von Briefkästen erstellen oder Umsteigestationen für Zubringerfahrzeuge oder Haltestellen in Service- und Servicezentren modellieren.

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.
• Verwenden Sie höchstens 64 Zeichen.
• Die folgenden ASCII-Zeichen dürfen nicht enthalten sein: „/“, ":", "\", "?" oder "#".
• Führen Sie eine Normalisierung gemäß der Unicode-Normalisierungsform C durch.

Tipp :Sie können Aufgaben-IDs mit einem beliebigen programmatischen Mechanismus erstellen. Google empfiehlt die Verwendung eines UUID-Tools 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 personenidentifizierbare Informationen und Zeichenanforderungen: 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 personenidentifizierbare Informationen und Zeichenanforderungen: Leerzeichen, Kommas und Anführungszeichen. Mehr als 64 Zeichen.

Weitere Ressourcen

Informationen zu den spezifischen Feldern, die in den einzelnen Datenstrukturen enthalten sind, 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 Fahrzeug-ID des Kunden.

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

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

1. Rufen Sie UpdateDeliveryVehicle an.
2. Wenn Sie einen NOT_FOUND-Fehler erhalten, rufen Sie CreateDeliveryVehicle auf, um das Fahrzeug neu zu erstellen. Wenn durch den Anruf ein Fahrzeug zurückgegeben wird, kann es noch aktualisiert werden.

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

Fahrzeugtypen

Die Entität VehicleType enthält ein optionales Feld von VehicleType mit einer Category-Enum, die Sie als AUTO, TWO_WHEELER, BICYCLE oder PEDESTRIAN angeben können. Wenn Sie das Feld nicht festlegen, wird es standardmäßig auf AUTO gesetzt.

Bei allen Routen für Fahrzeuge wird die entsprechende RouteTravelMode für den Fahrzeugtyp verwendet.

Fahrzeugattribute

Die Entität DeliveryVehicle enthält ein wiederkehrendes Feld von DeliveryVehicleAttribute. Die ListDeliveryVehicles API enthält das Feld filter, mit dem die zurückgegebenen DeliveryVehicle-Entitäten auf Entitäten mit den angegebenen Attributen beschränkt werden können. DeliveryVehicleAttribute wirkt sich nicht auf das Routingverhalten von Fleet Engine aus.

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

Lebensdauer einer Aufgabe

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

Ein Task-Objekt hat ein Statusfeld, um seinen Fortschritt während seines Lebenszyklus zu verfolgen. Die Werte wechseln von OFFEN zu GESCHLOSSEN. Neue Aufgaben werden im Status OPEN erstellt, was bedeutet, dass entweder:

• Die Aufgabe wurde noch keinem Lieferfahrzeug zugewiesen.
• Das Lieferfahrzeug hat den der Aufgabe zugewiesenen Fahrzeugstopp noch nicht passiert.

Richtlinien für Aufgaben

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

Wenn Sie eine Aufgabe abbrechen möchten, entfernen Sie sie aus der Liste der Fahrzeughalte. Dadurch wird der Aufgabenstatus automatisch auf GESCHLOSSEN.

Wenn das Fahrzeug der Aufgabe den Fahrzeugstopp der Aufgabe beendet:

1. Aktualisieren Sie das Ergebnisfeld der Aufgabe in SUCCEEDED oder FAILED.

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

2. Geben Sie den Zeitstempel des Ereignisses an.

   Die JavaScript-Bibliothek für die Sendungsverfolgung zeigt dann das Ergebnis der Aufgabe an und der Aufgabenstatus wird automatisch auf CLOSED gesetzt. Weitere Informationen findest du unter Lieferung mit der JavaScript-Bibliothek „Shipment Tracking“ verfolgen.

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

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

Fahrzeug- und Aufgabenlebenszyklus verwalten

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

Wenn Sie Fahrzeug- und Aufgabenlebenszyklen in Ihrem System verwalten möchten, können Sie mit der Fleet Engine Deliveries API Ihre Fahrzeuge und die zugehörigen Aufgaben erstellen, aktualisieren und verfolgen.

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

Angenommen, Sie haben folgendes Szenario:

• Ein Fahrer nähert sich einer Lieferstation. Die Treiberanwendung sendet ihren Standort an die Fleet Engine.
• Fleet Engine sendet den Gerätestandort an die Tracking-Bibliothek, mit der Ihre Nutzeranwendung den Nutzer über die Nähe seines Pakets benachrichtigt.
• Nachdem der Fahrer den Versand abgeschlossen hat, klickt er in der Fahreranwendung auf die Schaltfläche „Lieferung zugestellt“.
• Die Aktion "Lieferung zugestellt" sendet die Informationen an Ihr Back-End-System, das die erforderlichen Validierungs- und Verifizierungsschritte für das Unternehmen ausführt.
• Ihr System bestätigt die Aufgabe als ERFOLGREICH und aktualisiert Fleet Engine mit der Deliveries API.

Das folgende Diagramm veranschaulicht diese Prozesse im Allgemeinen. Außerdem wird die Standardbeziehung zwischen Ihrem System, dem Client und Fleet Engine aufgezeigt.

Client-Tokens verwalten

Für Standortaktualisierungen, die von der Treiberanwendung stammen und direkt an Fleet Engine gesendet werden, sind Autorisierungstokens erforderlich. Dies ist der empfohlene Ansatz für die Verarbeitung von Aktualisierungen vom Client auf Fleet Engine:

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

2. Stellen Sie der Treiberanwendung ein Token von begrenztem Umfang bereit. In diesem Bereich kann der Gerätestandort nur in Fleet Engine aktualisiert werden.

Dieser Ansatz sorgt dafür, dass Aufrufe von Mobilgeräten, die als Low-Trust-Umgebungen betrachtet werden, dem Prinzip der geringsten Berechtigung entsprechen.

Andere Dienstkontorollen

Wenn Sie die Treiberanwendungen stattdessen autorisieren möchten, direkte Flet Engine-Updates über die durch die Rolle „Nicht vertrauenswürdigen Treiber“ beschränkten hinaus auszuführen, z. B. für bestimmte Aufgabenupdates, können Sie die Rolle „Vertrauenswürdiger Treiber“ verwenden. Weitere Informationen zu einem Modell, das die Rolle „Vertrauenswürdiger Treiber“ verwendet, finden Sie unter Modell vertrauenswürdiger Treiber.

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

Einen Arbeitstag vorbilden

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

Uhrzeit	Aktivitäten	Modellierung
Innerhalb von 24 Stunden nach Tagesbeginn	Der Disponent weist Lieferungen den Lieferfahrzeugen oder -routen zu.	Sie können Aufgaben für Lieferungen, Abholungen, Pausen und andere Aufgaben im Voraus in Fleet Engine erstellen. Sie können beispielsweise Aufgaben zur Abholung der Sendung, Aufgabe zur Sendungszustellung, Geplante Nichtverfügbarkeit oder Geplanten Stopp erstellen. Weisen Sie einem Fahrzeug Aufgaben zu, sobald die Gruppe von Lieferpaketen und die Reihenfolge, in der sie geliefert werden sollen, festgelegt sind.
Tagesbeginn	Der Fahrer beginnt den Tag am Depot, indem er sich in der Driver App anmeldet.	Initialisieren Sie die Delivery Driver API. Erstellen Sie das Lieferfahrzeug nach Bedarf in Fleet Engine.
	Der Fahrer lädt Sendungen auf das Lieferfahrzeug und scannt sie.	Wenn Aufgaben zur Versandzustellung nicht vorab erstellt wurden, erstellen Sie Aufgaben für die Versandzustellung zum Zeitpunkt des Scans.
	Der Fahrer bestätigt die Reihenfolge der auszuführenden Aufgaben.	Wenn sie nicht im Voraus erstellt wurden, erstellen Sie Aufgaben zur Abholung der Sendung, geplante Nichtverfügbarkeit und geplante Haltestellen.
	Der Fahrer verlässt das Depot und geht zur nächsten Anzahl von Aufgaben ein.	Weisen Sie dem Fahrzeug alle Aufgaben oder eine Teilmenge von Aufgaben zu, indem Sie deren Abschlussreihenfolge festlegen.
	Der Fahrer stellt eine Sendung zu.	Nachdem Sie an der Lieferhaltestelle angekommen sind, führen Sie Aktionen für ein Fahrzeug, das an einer Haltestelle ankommt aus. Nachdem du die Sendung zugestellt hast, schließe die Lieferaufgabe und optional den Versandstatus des Geschäfts und andere Metainformationen. Nachdem Sie alle Aufgaben an der Haltestelle erledigt haben und bevor Sie zur nächsten Haltestelle fahren, führen Sie Aktionen wie beendet eine Haltestelle und die Route zur nächsten Haltestelle aus.
	Fahrer trifft auf Zustellfahrzeug, um zusätzliche Sendungen auf das Lieferfahrzeug zu übertragen.	Der Treffpunkt für einen Umstieg zwischen Zubringer- und Lieferfahrzeugen sollte als geplante Haltestelle modelliert werden. Nachdem Sie die Sendungen übertragen und gescannt haben, erstellen Sie Zustellaufgaben, falls diese noch nicht erstellt wurden. Aktualisieren Sie dann die Reihenfolge der Aufgaben, indem Sie einem Fahrzeug Aufgaben zuweisen und die Aufgabenreihenfolge aktualisieren.
	Der Fahrer wird über eine Abholanfrage benachrichtigt.	Nachdem Sie die Abholanfrage angenommen haben, erstellen Sie eine Abholung des Pakets. Aktualisieren Sie dann die Reihenfolge der Aufgabenausführung, indem Sie Aufgaben einem Fahrzeug zuweisen und die Aufgabenreihenfolge aktualisieren.
12:00 Uhr	Fahrer macht Mittagspause.	Wenn ein Standort der Nichtverfügbarkeitsaufgabe zugeordnet ist, behandeln Sie ihn wie jede andere Aufgabe. Aktionen ausführen, die sich auf ein Fahrzeug beziehen, das an einer Haltestelle ankommt, das Fahrzeug an einer Haltestelle anhält und auf dem Weg zur nächsten Haltestelle ist. Andernfalls sind bis zum Ende der Pause keine weiteren Maßnahmen erforderlich. Entfernen Sie die Aufgabe. Bestätigen Sie dazu die nächste und die verbleibenden Aufgaben und aktualisieren Sie die Aufgabenreihenfolge.
	Der Fahrer holt eine Sendung ab.	Dies wird wie ein Lieferstopp modelliert. Aktionen im Zusammenhang mit einem an einer Haltestelle ankommenden Fahrzeug, Schließen einer Aufgabe und optional Speichern des Versandstatus und anderer Metainformationen ausführen. Nachdem Sie alle Aufgaben an der Haltestelle abgeschlossen haben und bevor Sie zur nächsten Haltestelle fahren, führen Sie Aktionen wie beendete Stopps durch das Fahrzeug und Fahren zur nächsten Haltestelle aus. Hinweis: Damit die Abrechnung korrekt ist, müssen alle Abholungen eine entsprechende Lieferaufgabe haben. Wenn die Abholung an einem anderen Tag auf derselben Route des Fahrers an einen anderen Ort auf der Route geliefert werden soll, empfehlen wir, diese Lieferaufgabe wie jede andere Lieferaufgabe auf der Route zu modellieren. Wenn der Fahrer die Abholung zurück zum Depot bringt, empfehlen wir, am Zielort des Depots einen Lieferauftrag zu erstellen.
	Der Fahrer hält an einem planmäßigen Stopp die Lieferungen aus einer Ablagebox ab.	Dieser Wert wird wie bei jedem anderen Abholstopp modelliert. Aktionen im Zusammenhang mit einem an einer Haltestelle ankommenden Fahrzeug und Schließen einer Aufgabe ausführen. Nachdem Sie alle Aufgaben an der Haltestelle abgeschlossen und begonnen haben, zur nächsten Haltestelle zu fahren, führen Sie Aktionen wie beendete Haltestelle und Fahren zur nächsten Haltestelle aus.
	Der Fahrer wird benachrichtigt, 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 versuchte, ein Paket zuzustellen, konnte das aber nicht tun.	Dies wird ähnlich wie ein erfolgreicher Bereitstellungsstopp modelliert, wodurch die Bereitstellungsaufgabe als abgeschlossen markiert wird. Aktionen ausführen, die sich auf ein an einer Haltestelle ankommendes Fahrzeug beziehen. Wenn die Sendung nicht zugestellt werden kann, schließe die Aufgabe und füge optional den Versandstatus des Geschäfts und andere Metainformationen hinzu. Nachdem Sie alle Aufgaben an der Haltestelle abgeschlossen haben und bevor Sie zur nächsten Haltestelle fahren, führen Sie Aktionen wie beendete Stopps durch das Fahrzeug und Fahren 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 aufgefordert, eine bestimmte Lieferung als Nächstes zuzustellen. Dadurch änderte sich die zugesagte Lieferreihenfolge.	Aktualisieren Sie die Aufgabenreihenfolge.
	Der Fahrer entscheidet, eine Lieferung außerordentlich zu liefern.	Aktualisieren Sie die Aufgabenreihenfolge und fahren Sie dann wie gewohnt fort.
	Der Fahrer liefert mehrere Lieferungen an einen Ort.	Dies ähnelt dem Modell einer einzelnen Lieferstation. Nachdem Sie an der Haltestelle angekommen sind, führen Sie Aktionen für ein an einer Haltestelle ankommendes Fahrzeug aus. Nachdem du jede Sendung zugestellt hast, schließe jede Aufgabe und optional 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 wie beendete Stopps durch das Fahrzeug und Fahren zur nächsten Haltestelle aus.
Tagesende	Der Fahrer kehrt zum Depot zurück.	Wenn der Fahrer mit der Abholung des Pakets zum Depot zurückkehrt, müssen Sie auch jedes Paket als Zustellaufgabe erstellen und schließen, um eine korrekte Abrechnung zu gewährleisten. Dazu können Sie das Depot wie jede andere Lieferstation modellieren. Wenn das Depot nicht als Lieferstopp verwendet wird, können Sie es dennoch optional als planmäßige Haltestelle modellieren. Durch die Modellierung der Haltestelle können Ihre Fahrer die Route zurück zum Depot sehen und die voraussichtliche Ankunftszeit sehen.

So funktionieren Standortupdates

Die beste Leistung erzielen Sie mit Fleet Engine, wenn Sie einen Stream von Aktualisierungen des Fahrzeugstandorts bereitstellen. Verwenden Sie eine der folgenden Möglichkeiten, um diese Aktualisierungen bereitzustellen:

1. Verwenden Sie das Driver SDK – Android, iOS – die einfachste Option.
2. Verwenden Sie benutzerdefinierten Code. Dies ist nützlich, wenn Standorte über Ihr Back-End weitergeleitet werden oder 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 ein Lieferfahrzeug auf dem Weg zu einer Haltestelle ist (einschließlich des Depots) und wenn es an einer Haltestelle ankommt. Fleet Engine erkennt diese Ereignisse nicht automatisch.

Haltestellen und Lieferorte

Ein Fahrzeugstopp ist der Ort, an dem ein Lieferfahrzeug eine Versandaufgabe oder eine andere Aufgabe erledigt. Es handelt sich entweder um einen Zugangspunkt, z. B. eine Ladestation oder einen gesperrten Ort.

Der Lieferort ist der Ort, an dem die Sendung geliefert oder abgeholt wird. Der Weg zum und vom Lieferort kann einige Fußwege von der Haltestelle aus erfordern.

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

Damit Ihre Nutzer die Sendungsverfolgung optimal nutzen können, sollten Sie berücksichtigen, wie Versandaufgaben Fahrzeugstopps zugewiesen werden. Außerdem wird die Anzahl der verbleibenden Fahrzeugstopps für Versandaufgaben an den Nutzer gemeldet, damit er sich den Fortschritt seiner Sendung ansehen kann.

Wenn beispielsweise ein Fahrer viele Lieferungen an ein einzelnes Bürogebäude vornimmt, sollten Sie alle Lieferaufgaben einer einzigen Fahrzeughaltestelle zuweisen. Wenn jede Lieferaufgabe einer eigenen Fahrzeughaltestelle zugewiesen ist, ist die Sendungsverfolgung für Ihre Nutzer weniger hilfreich, da die Sendungsverfolgung erst verfügbar ist, wenn sich das Fahrzeug innerhalb einer begrenzten Anzahl von Fahrzeugstopps vor seinem Ziel befindet. Wenn viele Fahrzeugstopps in kurzer Zeit abgeschlossen werden, bleibt dem Nutzer nicht viel Zeit, den Fortschritt der Lieferung zu verfolgen.

Mobile SDKs verwenden

Bevor Sie Aufrufe an das Treiber-SDK senden, muss es initialisiert werden.

Delivery Driver API initialisieren

Bevor Sie die Delivery Driver API im Driver SDK initialisieren, müssen Sie das Navigation SDK initialisieren. 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 mehrere Branchen, einschließlich Übermittlungen. Verwenden Sie ProGuard oder ein anderes Optimierungstool, um den nicht verwendeten Code zu entfernen, um die binäre Gesamtgröße zu verringern.

Anwendungsfälle

In diesem Abschnitt wird beschrieben, wie Sie mit der Deliveries API häufige Anwendungsfälle modellieren können.

Eindeutige Entitätskennungen

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

Fahrzeug erstellen

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

gRPC

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

Beim Erstellen eines DeliveryVehicle können Sie die folgenden Felder optional 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 nicht konfigurieren.

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

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

<id> ist eine eindeutige Kennzeichnung 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 ausgegeben wird.

Der POST-Textkörper stellt die zu erstellende DeliveryVehicle-Entität dar. 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 Entität DeliveryVehicle 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 Parameter deliveryVehicleId 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 zum Abholen einer Sendung erstellen

Sie können eine Aufgabe zur Abholung der Sendung entweder über das Driver SDK oder in einer Serverumgebung mit gRPC oder REST erstellen.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek eine Abholaufgabe zur Abholung 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 in einer Serverumgebung eine Aufgabe zur Abholung einer Sendung 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 Kennzeichnung für die Aufgabe. Es darf sich nicht um die Tracking-Nummer für die Sendung handeln. Wenn in Ihrem System keine Aufgaben-IDs vorhanden sind, können Sie eine UUID (Universally Unique Identifier) generieren.

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

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  Typ	Type.PICKUP
  state	State.OPEN
  trackingId	Die Nummer oder Kennung, die Sie zur Verfolgung einer Sendung verwenden.
  plannedLocation	Der Ort, an dem die Aufgabe abgeschlossen werden soll, in diesem Fall der Abholort der Sendung.
  taskDuration	Die erwartete Zeit in Sekunden, die für die Abholung der Sendung am Abholort benötigt wird.

• Optionale Felder:

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

Alle anderen Felder in der Entität werden bei der Erstellung ignoriert. Fleet Engine gibt eine Ausnahme aus, wenn die Anfrage eine zugewiesene deliveryVehicleId enthält. Aufgaben weisen Sie mit UpdateDeliveryVehicleRequest zu. Weitere Informationen findest du 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 Sendungszustellung erstellen

Erstellen Sie eine Aufgabe für die Sendungszustellung entweder über das Driver SDK oder über eine Serverumgebung mit gRPC oder REST.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

Führen Sie einen HTTP-REST-Aufruf an CreateTask aus, um eine Aufgabe für die Sendungszustellung aus einer Serverumgebung mit gRPC oder REST zu erstellen:

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

<id> ist eine eindeutige Kennzeichnung für die Aufgabe. Es darf sich nicht um die Tracking-Nummer für die Sendung handeln. Wenn in Ihrem System keine Aufgaben-IDs vorhanden sind, können Sie eine UUID (Universally Unique Identifier) generieren.

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

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  Typ	Type.DELIVERY
  state	State.OPEN
  trackingId	Die Nummer oder Kennung, die Sie zur Verfolgung einer Sendung verwenden.
  plannedLocation	Der Ort, an dem die Aufgabe abgeschlossen werden soll, in diesem Fall der Lieferort für diese Sendung.
  taskDuration	Die erwartete Zeit in Sekunden, die die Abgabe der Sendung am Lieferort benötigt.

• Optionale Felder:

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

Alle anderen Felder in der Entität werden bei der Erstellung ignoriert. Fleet Engine löst eine Ausnahme aus, wenn die Anfrage eine zugewiesene deliveryVehicleId enthält. Aufgaben weisen Sie mit UpdateDeliveryVehicleRequest zu. Weitere Informationen findest du 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

Aufgaben im Batch erstellen

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

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek zwei Aufgaben erstellen, eine für eine Lieferung und eine für 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

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

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

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine Token Factory ausgegeben 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 der obersten BatchCreateTasksRequest-Ebene identisch sein. Weitere Informationen zu spezifischen Validierungsregeln für jede Aufgabe finden Sie unter Aufgaben zur Abholung im Paket erstellen 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, die Nichtverfügbarkeit anzeigt (z. B. für Fahrerpausen oder Fahrzeugbefüllung), entweder über das Driver SDK oder in einer Serverumgebung mit gRPC oder REST erstellen. Eine geplante Nichtverfügbarkeitsaufgabe darf keine Tracking-ID enthalten. Optional können Sie einen Standort angeben.

gRPC

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

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String parent = "providers/" + PROJECT_ID;
    Task task = Task.newBuilder()
      .setType(Task.Type.UNAVAILABLE)
      .setState(Task.State.OPEN)
      .setTaskDuration(
        Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
      .build();

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

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

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

REST

Um eine Nichtverfügbarkeitsaufgabe in einer Serverumgebung zu erstellen, führen Sie einen HTTP-REST-Aufruf an CreateTask aus:

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

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

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

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

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

• Optionale Felder:

  Field	Wert
  plannedLocation	Der Ort der Unterbrechung, wenn sie an einem bestimmten Ort stattfinden muss.

Alle anderen Felder in der Entität werden bei der Erstellung ignoriert. Fleet Engine löst eine Ausnahme aus, wenn die Anfrage eine zugewiesene deliveryVehicleId enthält. Aufgaben weisen Sie mit UpdateDeliveryVehicleRequest zu. Weitere Informationen findest du 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 in einer Serverumgebung mit gRPC oder REST erstellen. Eine geplante Stoppaufgabe darf keine Tracking-ID enthalten.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek eine geplante Stoppaufgabe 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

Wenn Sie eine geplante Stoppaufgabe in 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 Kennzeichnung für die Aufgabe. Wenn in Ihrem System keine Aufgaben-IDs vorhanden sind, können Sie eine UUID (Universally Unique Identifier) generieren.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> ein Token ist, das von einer Fleet Engine Token Factory ausgegeben 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 Länge der Haltestelle in Sekunden.

• Optionale Felder:

  • Ohne

Alle anderen Felder in der Entität werden bei der Erstellung ignoriert. Fleet Engine löst eine Ausnahme aus, wenn die Anfrage eine zugewiesene deliveryVehicleId enthält. Aufgaben weisen Sie mit UpdateDeliveryVehicleRequest zu. Weitere Informationen findest du 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

Zielzeitfenster festlegen

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

Das Zielzeitfenster besteht aus einer Start- und einer Endzeit und kann für jeden Aufgabentyp festgelegt werden. Das Zielzeitfenster 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 Zeitfenster für Aufgaben mithilfe von HTTP festzulegen:

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

<id> ist eine eindeutige Kennzeichnung 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 ausgegeben wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  targetTimeWindow	Das Zeitfenster, in dem die Aufgabe abgeschlossen werden sollte. Diese Einstellung wirkt sich nicht auf das Routingverhalten aus

• Optionale Felder:

  • Ohne

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 festlegen

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

Rufen Sie UpdateTask auf, um das Konfigurationsfenster der Aufgaben-Tracking-Ansicht über HTTP festzulegen:

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

<id> ist eine eindeutige Kennzeichnung 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 ausgegeben 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 die Endnutzer sichtbar sind.

• Optionale Felder:

  • Ohne

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 durch die Liste der Fahrzeughaltestellen 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 umstellen möchten, schließen Sie die ursprüngliche Aufgabe und erstellen Sie sie dann 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 Auftragsaufgaben, die einem Fahrzeug zugewiesen sind, entweder über das Driver SDK oder die Serverumgebung aktualisieren. Verwenden Sie nicht beide Methoden, um Race-Bedingungen zu vermeiden und eine Single Source of Truth aufrechtzuerhalten.

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

• Dem Fahrzeug werden neue Aufgaben zugewiesen.
• Schließt alle Aufgaben, die dem Fahrzeug zuvor zugewiesen waren, aber nicht die aktualisierte Reihenfolge haben.

Wenn Sie eine Sendung von einem Fahrzeug auf ein anderes umstellen möchten, schließen Sie die ursprüngliche Aufgabe und erstellen Sie sie dann 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.

Sie können die Aufgabenreihenfolge jederzeit aktualisieren.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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 Kennzeichnung 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 ausgegeben wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  remainingVehicleJourneySegments	Eine Liste von Journeysegmenten für Aufgaben in der Reihenfolge, in der sie ausgeführt werden sollen. Die erste Aufgabe in der Liste wird zuerst ausgeführt.
  VerbleibendeFahrzeugreisesegmente[i].stop	Haltestelle für Aufgabe i in der Liste.
  verbleibende VehicleJourneySegments[i].stop.plannedLocation	Die geplante Position der Haltestelle.
  verbleibende VehicleJourneySegments[i].stop.tasks	Eine Liste der Aufgaben, die an dieser Haltestelle auszuführen sind.
  remainingVehicleJourneySegments[i].stop.state	State.NEW

• Optionale Felder:

  • Ohne

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 für das 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 an einer Haltestelle abfährt oder die Navigation startet. 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 aufrechtzuerhalten.

gRPC

Das folgende Beispiel zeigt, wie Fleet Engine mithilfe der Java gRPC-Bibliothek darüber informiert wird, 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 kommt, 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 Kennzeichnung 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 ausgegeben wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfeld:

  Field	Wert
  remainingVehicleJourneySegments	Liste der verbleibenden Fahrzeughalte, wobei deren Status als State.NEW gekennzeichnet ist. Für die erste Haltestelle auf der Liste muss der Status State.ENROUTE angegeben sein.

• Optionale Felder:

  • Ohne

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

Beispiel eines curl-Befehls:

Hinweis :Mit diesem Befehl werden alle remainingVehicleJourneySegments überschrieben, die bereits für das Auslieferungsfahrzeug 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 zum Aktualisieren des Fahrzeugstandorts verwenden, können Sie Fleet Engine direkt mit dem Standort des Fahrzeugs aufrufen. Für jedes aktive Fahrzeug erwartet Flleet Engine mindestens einmal pro Minute und höchstens einmal alle 5 Sekunden eine Standortaktualisierung.

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

Rufen Sie UpdateDeliveryVehicle auf, um den Standort eines Fahrzeugs in Fleet Engine mithilfe von HTTP REST zu aktualisieren:

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

<id> ist eine eindeutige Kennzeichnung für das Lieferfahrzeug in deiner Flotte oder das du den Standort aktualisieren möchtest. 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 ausgegeben wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfeld:

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

• 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 landet an einer Haltestelle

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 aufrechtzuerhalten.

gRPC

Das folgende Beispiel zeigt, wie Sie mit der Java gRPC-Bibliothek Fleet Engine benachrichtigen, dass ein Fahrzeug an einer Haltestelle angekommen 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

Um Fleet Engine über die Ankunft eines Fahrzeugs an einer Haltestelle aus einer Serverumgebung zu informieren, 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 Kennzeichnung 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 ausgegeben wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  remainingVehicleJourneySegments	Die Haltestelle, an der Sie angekommen sind, deren Status auf „State.ARRIVED“ festgelegt ist, gefolgt von einer Liste der verbleibenden Fahrzeughalte, deren Status als State.NEW gekennzeichnet ist.

• Optionale Felder:

  • Ohne

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 für das 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 verknüpften Aufgaben in den Status CLOSED (GESCHLOSSEN) 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 aufrechtzuerhalten.

gRPC

Im folgenden Beispiel wird gezeigt, wie Sie Fleet Engine mithilfe der Java gRPC-Bibliothek darüber informieren, dass ein Fahrzeug eine Haltestelle beendet 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

Um Fleet Engine über den Abschluss eines Stopps von einer Serverumgebung zu informieren, führen Sie einen HTTP-REST-Aufruf an UpdateDeliveryVehicle aus:

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

<id> ist eine eindeutige Kennzeichnung 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 ausgegeben wird.

Der Anfragetext muss eine DeliveryVehicle-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  remaining_vehicle_journey_segments	Die von Ihnen beendete Haltestelle sollte nicht mehr in der Liste der verbleibenden Fahrzeughalte enthalten sein.

• Optionale Felder:

  • Ohne

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 für das 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 den Status, das Aufgabenergebnis, die Zeit für das Aufgabenergebnis, den Ort des Aufgabenergebnisses und Attribute ändern, indem Sie die Aufgabenentität direkt aktualisieren. Wenn beispielsweise eine Aufgabe noch keinem Fahrzeug zugewiesen wurde, können Sie die Aufgabe schließen, indem Sie den Status direkt aktualisieren.

gRPC

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

REST

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

Aufgabe schließen

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

Wenn eine Aufgabe noch keinem Fahrzeug zugewiesen wurde und geschlossen werden muss, setzen Sie die Aufgabe in den Status CLOSED (GESCHLOSSEN). Sie können eine GESCHLOSSENE Aufgabe jedoch nicht wieder öffnen.

Das Schließen einer Aufgabe weist nicht auf Erfolg oder Misserfolg hin. Es zeigt an, dass die Aufgabe nicht mehr als in Bearbeitung angesehen wird. Für die Sendungsverfolgung ist es wichtig, das tatsächliche Ergebnis einer Aufgabe anzugeben, damit das 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

Führen Sie einen HTTP-REST-Aufruf an UpdateTask aus, um eine Aufgabe von einer Serverumgebung aus als geschlossen zu markieren:

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

<id> ist eine eindeutige Kennzeichnung 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 ausgegeben wird.

Sie müssen eine Task-Entität in den Anfragetext einfügen:

• Pflichtfelder:

  Field	Wert
  state	State.CLOSED

• Optionale Felder:

  Field	Wert
  taskOutcome	Result.SUCCEEDED oder Result.FAILED
  taskOutcomeTime	Die Uhrzeit, zu der die Aufgabe abgeschlossen wurde.
  taskOutcomeLocation	Der Ort, an dem die Aufgabe abgeschlossen wurde. In Fleet Engine wird standardmäßig der letzte Fahrzeugstandort verwendet, sofern dies nicht manuell vom Anbieter überschrieben wird.

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

Beispiel eines curl-Befehls:

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

Aufgabenergebnis und Ergebnisort festlegen

Das Schließen einer Aufgabe weist nicht auf Erfolg oder Misserfolg hin, sondern weist darauf hin, dass die Aufgabe nicht mehr als in Bearbeitung angesehen wird. Für die Sendungsverfolgung ist es wichtig, das tatsächliche Ergebnis einer Aufgabe anzugeben, damit das Lieferergebnis angezeigt werden kann und die Dienste ordnungsgemäß abgerechnet werden. Nachdem Sie das Aufgabenergebnis festgelegt haben, können Sie es nicht mehr ändern. Sie können jedoch die Zeit und den Ort des Aufgabenergebnisses ändern, nachdem sie festgelegt wurden.

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

Beim Markieren des Ergebnisses einer Aufgabe fügt Fleet Engine automatisch den letzten bekannten Fahrzeugstandort für den Aufgabenergebnisort ein. Sie können dieses Verhalten überschreiben.

gRPC

Sie haben die Möglichkeit, den Ort des Aufgabenergebnisses festzulegen, wenn Sie das Ergebnis festlegen. Wenn Sie den Standort festlegen, kann Fleet Engine ihn nicht auf die Standardeinstellung des letzten Fahrzeugstandorts setzen. Sie können auch den von Fleet Engine festgelegten Standort für das Aufgabenergebnis überschreiben. Fleet Engine überschreibt niemals einen von Ihnen angegebenen Speicherort für Aufgabenergebnisse. Sie können keinen Ort für das Aufgabenergebnis für eine Aufgabe festlegen, für die kein Aufgabenergebnis festgelegt ist. Sie können in ein und derselben Anfrage sowohl das Aufgabenergebnis als auch die Position des Aufgabenergebnisses festlegen.

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

Führen Sie einen HTTP-REST-Aufruf an UpdateTask aus, um eine Aufgabe von einer Serverumgebung als abgeschlossen zu markieren:

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

<id> ist eine eindeutige Kennzeichnung 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 ausgegeben wird.

Der Anfragetext muss eine Task-Entität enthalten:

• Pflichtfelder:

  Field	Wert
  taskOutcome	Result.SUCCEEDED oder Result.FAILED

• Optionale Felder:

  Field	Wert
  taskOutcomeLocation	Der Ort, an dem die Aufgabe abgeschlossen wurde. Wenn die Richtlinie nicht konfiguriert ist, verwendet Fleet Engine standardmäßig den letzten Fahrzeugstandort.
  taskOutcomeTime	Der Zeitstempel, der angibt, wann 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

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

Zubringer- und Lieferfahrzeuge verwenden

Wenn Sie Feeder für den ganztägigen Transport von Lieferungen an Lieferfahrzeuge verwenden, modellieren Sie die Übergabe von Sendungen als geplante Stoppaufgabe für das Lieferfahrzeug. Damit eine genaue Standortverfolgung gewährleistet werden kann, solltest du für eine übertragene Sendung erst dann eine Lieferaufgabe zuweisen, nachdem sie auf das Lieferfahrzeug verladen wurde. Weitere Informationen finden Sie unter Geplante Haltestelle.

Versandstatus des Geschäfts und andere Metainformationen

Wenn eine Versandaufgabe abgeschlossen ist, werden der Aufgabenstatus und das Ergebnis in der Aufgabe aufgezeichnet. Es empfiehlt sich jedoch, andere für die Sendung spezifische Meta-Informationen zu 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.

Fahrzeug suchen

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

REST

Führen Sie einen HTTP-REST-Aufruf an GetVehicle aus, um ein Fahrzeug aus einer Serverumgebung zu suchen:

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

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

<vehicleId> ist die ID des Fahrzeugs, nach dem 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 ausgegeben 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}"

Nach einer Aufgabe suchen

Sie können eine Aufgabe aus einer Serverumgebung mit gRPC oder REST abrufen. Das Driver SDK unterstützt die Suche 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 nachschlagen 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 Kennzeichnung für die Aufgabe.

<taskId> ist die ID der nachzuschlagenden 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 ausgegeben 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 zu Versandaufgaben anhand der Tracking-ID abrufen

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

• durch eine Aufgaben-ID: wird von Nutzern wie Flottenbetreibern verwendet, die Zugriff auf die vollständige Ansicht der Aufgabendaten haben.
• Durch eine Tracking-ID: wird von Ihrer Clientsoftware verwendet, um Endnutzern eingeschränkte Informationen bereitzustellen, z. B. wann ein Paket bei sich zu Hause erwartet wird.

In diesem Abschnitt wird erläutert, wie Sie Aufgabeninformationen anhand einer Tracking-ID abrufen können. Wenn Sie eine Aufgabe anhand der Aufgaben-ID suchen möchten, gehen Sie zu Aufgabe suchen.

Sie haben folgende Möglichkeiten, Informationen anhand einer Tracking-ID abzurufen:

• Lookups mit Java mithilfe von gRPC
• Lookups mit HTTP

Lookup-Anforderungen

• Versandinformationen, die über eine Sendungsverfolgungs-ID bereitgestellt werden, entsprechen den Sichtbarkeitsregeln, die unter Sichtbarkeit von beobachteten Standorten steuern angegeben sind.

• Verwenden Sie Fleet Engine, um Versandinformationen anhand der Sendungsverfolgungs-ID abzurufen. Das Treiber-SDK unterstützt keine Informationssuche anhand der Tracking-ID. Für die Ausführung mit Fleet Engine verwenden Sie entweder eine Server- oder Browserumgebung.

• Verwenden Sie so wenig Token wie möglich, um Sicherheitsrisiken zu minimieren. Wenn Sie beispielsweise ein Delivery Consumer Token verwenden, geben alle Fleet Engine Deliveries API-Aufrufe 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 finden Sie unter JSON-Webtoken (JWT) für Autorisierung erstellen.

Lookups mit Java unter Verwendung von gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Lookups mit HTTP

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

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

<tracking_id> ist die mit der Aufgabe verknüpfte Tracking-ID.

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

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

Beispiel eines curl-Befehls:

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

Aufgaben auflisten

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

Wenn Sie Aufgaben auflisten, wird ein umfassender Zugriff auf Aufgaben angefordert. Das Auflisten von Aufgaben ist nur für vertrauenswürdige Nutzer vorgesehen. Verwenden Sie „Delivery Fleet Reader“ oder „Delivery Super User Authentication Tokens“ für Anfragen zu Listenaufgaben.

In aufgeführten Aufgaben wurden die folgenden Felder entfernt:

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

Aufgelistete Aufgaben können nach den meisten Aufgabeneigenschaften gefiltert werden. Informationen zur Syntax von Filterabfragen 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 basierend auf den Google API-Verbesserungsvorschlägen die folgenden Feldformate:

Feldtyp	Format	Beispiel
Zeitstempel	RFC-3339	task_outcome_time = 2022-03-01T11:30:00-08:00
Dauer	Anzahl der Sekunden, gefolgt von 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 Filterabfrageoperatoren finden Sie unter AIP-160.

Wenn keine Filterabfrage angegeben ist, werden alle Aufgaben aufgelistet.

Aufgabenlisten sind paginiert. Eine Seitengröße kann in Anfragen vom Typ „Aufgaben auflisten“ 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 Seite mit Aufgaben 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 daher 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 weiterhin leer sein. Eine leere Antwort gibt an, dass der angegebenen deliveryVehicleId keine Aufgaben 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

Führen Sie einen HTTP-REST-Aufruf an ListTasks aus, um Aufgaben über einen Browser aufzulisten:

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

Um einen Filter auf die aufgeführten Aufgaben anzuwenden, fügen Sie den URL-Parameter "filter" mit einer Filterabfrage mit URL-Escaping 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 ausgegeben wird.

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

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

Eine erfolgreiche Antwort kann 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 aus einer 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. Verwenden Sie „Delivery Fleet Reader“ oder „Delivery Super User Authentication Tokens“ für Anfragen zu Listenlieferfahrzeugen.

In den aufgeführten Lieferfahrzeugen wurden die folgenden Felder aufgrund ihrer Auswirkungen auf die Antwortgröße entfernt:

• CurrentRouteSegment
• RemainingVehicleJourneySegments

Du kannst die Liste der Lieferfahrzeuge nach ihrer attributes-Property filtern. Wenn Sie beispielsweise ein Attribut mit dem Schlüssel my_key und dem Wert my_value abfragen möchten, verwenden Sie attributes.my_key = my_value. Wenn Sie mehrere Attribute abfragen möchten, verknüpfen Sie Abfragen mithilfe der logischen Operatoren AND und OR wie in attributes.key1 = value1 AND attributes.key2 = value2. Eine vollständige Beschreibung der Filterabfragesyntax 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: einem Paar aus Breiten- und Längengradkoordinaten high (northeast) und low (Südwest). Anfragen werden abgelehnt, wenn sie einen hohen Breitengrad enthalten, der geografisch niedriger ist als ein niedriger Breitengrad.

Hinweis :Wenn Sie keine Filterabfrage oder keinen Darstellungsbereich angeben, enthält die Antwort alle Lieferfahrzeuge.

Listen mit Fahrzeugen werden standardmäßig mit einer angemessenen Seitengröße paginiert. Wenn Sie eine Seitengröße angeben, gibt die Anfrage nur die durch das Limit angegebene Anzahl von Fahrzeugen oder weniger zurück. Wenn die angeforderte Seitengröße einen internen Maximalwert überschreitet, wird der interne Maximalwert verwendet. Die Standard- und die maximale Seitengröße sind jeweils 100 Fahrzeuge.

Eine Liste der Lieferfahrzeuge kann ein Token zum Lesen der nächsten Ergebnisseite enthalten. Ein Seitentoken ist nur in einer Antwort vorhanden, wenn mehr Seiten mit Lieferfahrzeugen abgerufen werden können. Verwenden Sie das Seitentoken mit einer Anfrage, die ansonsten mit der vorherigen Anfrage identisch ist, um die nächste Seite mit Aufgaben abzurufen.

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 keine Fahrzeuge mit dem angegebenen Attribut bereits 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

Führen Sie einen HTTP-REST-Aufruf an ListDeliveryVehicles aus, um Aufgaben über einen Browser aufzulisten:

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

Wenn Sie einen Filter auf die aufgeführten Aufgaben anwenden möchten, fügen Sie den URL-Parameter „Filter“ mit einer Filterabfrage mit URL-Escaping 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 ausgegeben wird.

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

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

Eine erfolgreiche Antwort kann 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"

Sendungsverfolgung

Sie haben zwei Möglichkeiten, die Fleet Engine Deliveries API zur Aktivierung der Sendungsverfolgung zu verwenden:

• Bevorzugt:Verwenden Sie die JavaScript-Bibliothek für die Sendungsverfolgung. Mit der Bibliothek können Sie den Standort von Fahrzeugen sowie die Standorte von Interesse visualisieren, die in Fleet Engine erfasst werden. Es enthält eine JavaScript-Kartenkomponente, die ein Drop-in-Ersatzobjekt für ein google.maps.Map-Objekt ist, sowie Datenkomponenten zum Herstellen einer Verbindung mit Fleet Engine. Mit dieser Komponente können Sie eine anpassbare, animierte Sendungsverfolgung über Ihre Web- oder mobile App bereitstellen.

• Implementieren Sie zusätzlich zur Fleet Engine Deliveries API Ihre eigene Sendungsverfolgung.

Wichtig ist, Versandaufgaben anhand der Sendungsverfolgungs-ID zu ermitteln.

Wenn Sie eine Delivery Consumer Role verwenden, geben Aufrufe der Fleet Engine Deliveries API nur Informationen zurück, die für einen Spediteur oder Empfänger relevant sind. Alle anderen Informationen in den Antworten werden entfernt. Für die Authentifizierung der Endnutzer sind Sie selbst verantwortlich. Außerdem werden Standortinformationen basierend auf der bereits ausgeführten Aufgabe gefiltert. Bei einer Nichtverfügbarkeitsaufgabe werden keine Standortinformationen an Endnutzer weitergegeben.

Logging

Sie können Fleet Engine so einstellen, 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 an 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

Falls Probleme auftreten, finden Sie in den folgenden Abschnitten Hilfe.

Robustheit

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

Verlorener Status in Fleet Engine

Implementieren Sie bei der Arbeit mit Fleet Engine Clients, damit sich das System im Falle eines Fehlers von selbst heilt. 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. Auch wenn dieses Problem selten auftritt, sollten Sie darauf achten, dass Ihr System stabil genug ist, um das Problem 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 wieder fehlschlagen, da Kontingentprüfungen vorhanden sind, um DoS-Angriffe (Denial of Service) zu vermeiden. Verlangsamen Sie in diesem Fall die Neuerstellungsrate mithilfe einer Backoff-Strategie für Wiederholungsversuche.

Verloren-Status in der Treiber-App

Wenn die Treiber-App abstürzt, muss sie den aktuellen Status im Treiber-SDK neu erstellen. Die Anwendung sollte versuchen, Aufgaben neu zu erstellen, damit sie vorhanden sind und ihren aktuellen Status wiederherstellen können. Die App sollte auch die Liste der Haltestellen für das Driver SDK neu erstellen und explizit festlegen.

Hinweis: Diese Wiederherstellungen müssen autonom durchgeführt werden, ohne sich auf Informationen von Fleet Engine zu stützen. 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 mit ihrer ID aktualisiert werden.

Häufig gestellte Fragen

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

Aktualisieren Sie in diesem Fall zuerst die Reihenfolge der Aufgaben und fahren Sie dann wie gewohnt fort. Markieren Sie dabei die Ankunft an der Haltestelle, den Abschluss der Aufgabe und andere Details. Andernfalls kann es zu Inkonsistenzen im System, falschen ETAs und unerwarteten Fehlern kommen.