Mit der On-Demand Rides and Deliveries API von Fleet Engine können Sie Fahrten und den Fahrzeugstatus für Ihre Trip- und Order Progress-Anwendungen verwalten. Er verarbeitet Transaktionen zwischen dem Driver SDK, dem Consumer SDK und Ihrem Back-End-Dienst, der über gRPC- oder REST-Aufrufe mit der Fleet Engine kommunizieren kann.
Voraussetzungen
Achten Sie für die Entwicklung darauf, dass Sie das Cloud SDK (gcloud) installieren und bei Ihrem Projekt authentifiziert sind.
shell
gcloud auth login
Sie sollten eine Erfolgsmeldung wie die folgende sehen:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Prüfen Sie, ob die Fleet Engine APIs der On-demand Rides and Deliveries-Lösung richtig konfiguriert sind.
shell
gcloud --project=project-id services enable fleetengine.googleapis.com
Wenn dieser Befehl zu einem Fehler führt, wenden Sie sich an Ihren Projektadministrator und Ihren Google-Supportmitarbeiter, um Zugriff zu erhalten.
Logging
Die Fleet Engine kann Logeinträge über erhaltene API-Aufrufe in Google Cloud Platform-Logs schreiben. In der Cloud Logging-Dokumentation finden Sie eine Übersicht zum Lesen und Analysieren von Logs.
Für Projekte, die vor dem 10. Februar 2022 erstellt wurden, ist Logging möglicherweise nicht standardmäßig aktiviert. Weitere Informationen finden Sie in der Logging-Dokumentation.
Clientbibliotheken
Wir veröffentlichen Clientbibliotheken in verschiedenen gängigen Programmiersprachen. Diese Bibliotheken bieten eine bessere Entwicklungsumgebung im Vergleich zu Roh-REST oder gRPC. Eine Anleitung zum Abrufen von Clientbibliotheken für Ihre Serveranwendung finden Sie unter Clientbibliotheken.
Die Java-Beispiele in dieser Dokumentation setzen voraus, dass Sie mit gRPC vertraut sind.
Authentifizierung und Autorisierung
Die von „Trip“ und „Order Progress“ bereitgestellten Funktionen können über die Google Cloud Console konfiguriert werden. Für diese APIs und SDKs sind JSON Web Tokens erforderlich, die mit Dienstkonten signiert wurden, die in der Cloud Console erstellt wurden.
Cloud-Projekt einrichten
Erstellen Sie zum Einrichten Ihres Cloud-Projekts zuerst das Projekt und dann Dienstkonten.
So erstellen Sie Ihr Google Cloud-Projekt:
- Erstellen Sie mit der Google Cloud Console ein Google Cloud-Projekt.
- Aktiviere im Dashboard „APIs und Dienste“ die Local Rides and Deliveries API.
Dienstkonten sind mit einer oder mehreren Rollen verknüpft. Sie werden verwendet, um JSON-Webtokens zu erstellen, die je nach Rollen unterschiedliche Berechtigungen gewähren. Um Missbrauch zu verhindern, können Sie in der Regel mehrere Dienstkonten mit jeweils den erforderlichen Mindestrollen erstellen.
Für „Trip and Order Progress“ werden die folgenden Rollen verwendet:
Rolle | Beschreibung |
---|---|
Fleet Engine Consumer SDK-Nutzer
roles/fleetengine.consumerSdkUser |
Gewährt die Berechtigung zum Suchen nach Fahrzeugen und zum Abrufen von Informationen zu Fahrzeugen und Fahrten. Tokens, die von einem Dienstkonto mit dieser Rolle erstellt wurden, werden in der Regel von Mobilgeräten Ihrer Nutzer-App für Mitfahrdienste oder Lieferdienste verwendet. |
Fleet Engine Driver SDK-Nutzerroles/fleetengine.driverSdkUser |
Gewährt die Berechtigung zum Aktualisieren von Fahrzeugstandorten und -routen sowie zum Abrufen von Informationen zu Fahrzeugen und Fahrten. Tokens, die von einem Dienstkonto mit dieser Rolle erstellt werden, werden in der Regel von den Mobilgeräten Ihrer Mitfahrdienst- oder Lieferfahrer-App verwendet. |
Fleet Engine Service-Superuser roles/fleetengine.serviceSuperUser |
Gewährt die Berechtigung für alle APIs und APIs für Fahrten mit Fahrzeugen und Fahrten. Tokens, die von einem Dienstkonto mit dieser Rolle erstellt wurden, werden in der Regel von Ihren Back-End-Servern verwendet. |
Erstellen Sie beispielsweise für jede der drei Rollen ein Dienstkonto und weisen Sie ihnen die entsprechenden Rollen zu.
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
Die Treiber- und Consumer SDKs basieren auf diesen Standardrollen.
Alternativ können Sie benutzerdefinierte Rollen erstellen, mit denen ein beliebiger Satz von Berechtigungen gebündelt werden kann. Im Treiber- und im Consumer SDK werden Fehlermeldungen angezeigt, wenn eine erforderliche Berechtigung fehlt. Daher empfehlen wir dringend, die oben beschriebenen Standardrollen zu verwenden und keine benutzerdefinierten Rollen zu verwenden.
Wenn Sie JWT-Tokens für nicht vertrauenswürdige Clients erstellen müssen, können Sie Nutzer in der Rolle „Ersteller von Dienstkonto-Tokens“ mit gcloud-Befehlszeilentools erstellen.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Dabei ist my-user@example.com
die E-Mail-Adresse, die zur Authentifizierung bei gcloud verwendet wird (gcloud auth list
--format='value(account)'
).
Fleet Engine-Authentifizierungsbibliothek
Fleet Engine verwendet JSON Web Tokens (JWTs), um den Zugriff auf Fleet Engine APIs einzuschränken. Die neue Authentifizierungsbibliothek von Fleet Engine, die auf GitHub verfügbar ist, vereinfacht die Erstellung von Fleet Engine-JWTs und signiert sie sicher.
Die Bibliothek bietet folgende Vorteile:
- Vereinfacht das Erstellen von Fleet Engine Tokens.
- Bietet andere Tokensignaturmechanismen als die Verwendung von Dateien mit Anmeldedaten (z. B. die Identität eines Dienstkontos).
- Hängt signierte Tokens an ausgehende Anfragen an, die von einem gRPC-Stub oder GAPIC-Client gesendet wurden.
JSON-Webtoken (JWT) für die Autorisierung erstellen
Wenn Sie die Fleet Engine-Authentifizierungsbibliothek nicht verwenden, müssen JSON-Webtokens (JWTs) direkt in Ihrer Codebasis erstellt werden. Dazu benötigen Sie ein tiefgreifendes Verständnis von JWTs und deren Beziehung zu Fleet Engine. Aus diesem Grund empfehlen wir dringend, die Nutzung der Fleet Engine-Authentifizierungsbibliothek zu nutzen.
Innerhalb von Fleet Engine bieten JSON Web Tokens (JWTs) eine kurzlebige Authentifizierung und sorgen dafür, dass Geräte nur Fahrzeuge, Fahrten oder Aufgaben ändern können, für die sie autorisiert sind. JWTs enthalten einen Header und einen Anforderungsabschnitt. Der Header-Abschnitt enthält Informationen wie den zu verwendenden privaten Schlüssel (von Dienstkonten erhalten) und den Verschlüsselungsalgorithmus. Der Claim-Abschnitt enthält Informationen wie die Erstellungszeit des Tokens, die Lebensdauer des Tokens, Dienste, auf die es Zugriff beansprucht, und andere Autorisierungsinformationen, um den Zugriff herabzustufen, z. B. die Fahrzeug-ID.
Ein JWT-Header enthält die folgenden Felder:
Field | Beschreibung |
---|---|
alg | Der zu verwendende Algorithmus. „RS256“. |
typ | Der Typ des Tokens. „JWT“. |
Kind | Die ID des privaten Schlüssels Ihres Dienstkontos. Sie finden diesen Wert im Feld „private_key_id“ der JSON-Datei Ihres Dienstkontos. Achten Sie darauf, einen Schlüssel von einem Dienstkonto mit der richtigen Berechtigungsstufe zu verwenden. |
Ein Bereich für JWT-Anforderungen enthält die folgenden Felder:
Field | Beschreibung |
---|---|
iss | Die E-Mail-Adresse Ihres Dienstkontos. |
sub | Die E-Mail-Adresse Ihres Dienstkontos. |
aud | SERVICE_NAME Ihres Dienstkontos, in diesem Fall https://fleetengine.googleapis.com/ |
iat | Der Zeitstempel für die Erstellung des Tokens, angegeben in Sekunden seit dem 1. Januar 1970 um 00:00:00 Uhr (UTC). Warten Sie 10 Minuten für eine Verzerrung. Wenn der Zeitstempel zu weit in der Vergangenheit oder in der Zukunft liegt, meldet der Server möglicherweise einen Fehler. |
exp | Der Zeitstempel für den Ablauf des Tokens, angegeben in Sekunden seit dem 1. Januar 1970 um 00:00:00 Uhr (UTC). Die Anfrage schlägt fehl, wenn der Zeitstempel mehr als eine Stunde in der Zukunft liegt. |
authorization | Je nach Anwendungsfall kann „vehicleid“ oder „tripid“ enthalten sein. |
Das Erstellen eines JWT-Tokens bezieht sich auf das Signieren. Eine Anleitung und Codebeispiele zum Erstellen und Signieren des JWT finden Sie unter Dienstkontoautorisierung ohne OAuth. Anschließend können Sie ein signiertes Token an gRPC-Aufrufe oder andere Methoden für den Zugriff auf Fleet Engine anhängen.
JWT-Anforderungen
Füge beim Erstellen der JWT-Nutzlast eine zusätzliche Anforderung im Autorisierungsbereich hinzu. Dabei muss der Schlüssel vehicleid
oder tripid
auf den Wert der Fahrzeug-ID oder Fahrt-ID gesetzt sein, für die der Aufruf erfolgt.
Im Driver SDK wird immer die vehicleid
-Anforderung verwendet, unabhängig davon, ob es sich um eine Fahrt oder ein Fahrzeug handelt. Das Fleet Engine-Back-End stellt vor der Änderung sicher, dass das Fahrzeug der angeforderten Fahrt zugeordnet ist.
Das Consumer SDK verwendet immer die tripid
-Anforderung.
Der Mitfahrdienst oder Lieferanbieter muss vehicleid
oder tripid
mit einem „*“ verwenden, um alle Fahrzeuge und Fahrten abzugleichen. Das JWT kann beide Tokens enthalten, auch wenn es nicht erforderlich ist. Das kann die Implementierung der Tokensignatur vereinfachen.
JWT-Anwendungsfälle
Das folgende Beispiel zeigt ein Token für Anbieterserver:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
Das folgende Beispiel zeigt ein Token für eine Consumer-App:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
Das folgende Beispiel zeigt ein Token für die Driver-App:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- Geben Sie im Header für das Feld
kid
die ID des privaten Schlüssels Ihres Dienstkontos an. Sie finden diesen Wert im Feldprivate_key_id
der JSON-Datei Ihres Dienstkontos. - Geben Sie in den Feldern
iss
undsub
die E-Mail-Adresse Ihres Dienstkontos an. Sie finden diesen Wert im Feldclient_email
der JSON-Datei Ihres Dienstkontos. - Geben Sie für das Feld
aud
https://SERVICE_NAME/ an. - Verwenden Sie für das Feld
iat
den Zeitstempel der Erstellung des Tokens, angegeben als Sekunden seit dem 1. Januar 1970, 00:00:00 Uhr (UTC). Warten Sie 10 Minuten für eine Verzerrung. Wenn der Zeitstempel zu weit in der Vergangenheit oder in der Zukunft liegt, meldet der Server möglicherweise einen Fehler. - Verwenden Sie für das Feld
exp
den Zeitstempel für den Ablauf des Tokens in Sekunden seit 00:00:00 Uhr (UTC, 1. Januar 1970). Der maximal zulässige Wert istiat
+ 3.600.
Verwende beim Signieren des JWT, das an ein Mobilgerät übergeben werden soll, unbedingt das Dienstkonto für die Rolle „Driver SDK“ oder „Consumer SDK“. Andernfalls kann das Mobilgerät den Status ändern, den es nicht haben sollte.
Ebenso musst du beim Signieren des JWT für privilegierte Aufrufe das Dienstkonto mit der Rolle „Super User“ verwenden. Andernfalls schlägt der Vorgang fehl.
JWT für Testzwecke generieren
Das Generieren von Tokens über das Terminal kann beim Testen hilfreich sein.
Damit Sie diese Schritte ausführen können, muss Ihr Nutzerkonto die Rolle „Ersteller von Dienstkonto-Tokens“ haben:
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Erstellen Sie eine neue Datei mit dem Namen unsigned_token.json
und dem folgenden Inhalt. Das Attribut iat
gibt die aktuelle Zeit in Sekunden nach der Epoche an. Sie kann durch Ausführen von date +%s
in Ihrem Terminal abgerufen werden. Das Attribut exp
ist die Ablaufzeit in Sekunden nach der Epoche, die durch Addition von 3.600 zu iat
berechnet werden kann. Die Ablaufzeit darf nicht mehr als eine Stunde in der Zukunft liegen.
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
Führen Sie dann den folgenden gcloud-Befehl aus, um das Token im Namen Ihres Super User-Dienstkontos zu signieren:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
Ein signiertes Base64-codiertes JWT sollte jetzt in der Datei signed_token.jwt
gespeichert werden. Das Token ist innerhalb der nächsten Stunde gültig.
Sie können das Token jetzt testen, indem Sie einen curl
-Befehl für den REST-Endpunkt „List Vehicles“ ausführen:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
Fahrzeuge und ihr Lebenszyklus
Das Fahrzeug ist die Entität, die ein Fahrer-Fahrzeug-Paar darstellt. Derzeit können Fahrer und Fahrzeug nicht separat erfasst werden. Der Mitfahrdienst oder Lieferanbieter erstellt ein Fahrzeug mithilfe einer Anbieter-ID (die mit der Projekt-ID des Google Cloud-Projekts übereinstimmen muss, das das Dienstkonto zum Aufrufen der Fleet Engine APIs enthält) und einer Fahrzeug-ID des Mitfahrdienstes oder Lieferanbieters.
Ein Fahrzeug, das nach sieben Tagen nicht über UpdateVehicle
aktualisiert wurde, wird automatisch gelöscht. CreateVehicle
darf nicht mit einem bereits vorhandenen Paar aus Anbieter-ID und Fahrzeug-ID aufgerufen werden. Bei Fahrzeugen, die nicht häufig aktualisiert werden, kann auf zwei Arten gehandhabt werden: häufiges AufrufenCreateVehicle
mit einem erwarteten Paar aus Anbieter-ID und Fahrzeug-ID und Verwerfen des Fehlers, wenn das Fahrzeug bereits vorhanden ist, oder durch Aufrufen von CreateVehicle
nach einem UpdateVehicle
-Fehler wird ein NOT_FOUND
-Fehler zurückgegeben.
Updates zum Fahrzeugstandort
Um mit Fleet Engine die beste Leistung zu erzielen, sollten Sie einen Stream von Fahrzeugstandortaktualisierungen bereitstellen. Verwenden Sie eine der folgenden Methoden, um diese Aktualisierungen bereitzustellen:
- Verwenden Sie das Driver SDK für Android oder iOS – die einfachste Option.
- Benutzerdefinierten Code verwenden: Dies ist nützlich, wenn Standorte über Ihr Back-End weitergeleitet werden oder wenn Sie andere Geräte als Android oder iOS verwenden.
Fahrzeugtypen
Die Fahrzeugentität enthält das Pflichtfeld VehicleType
mit einem Category
-Enum, das als AUTO
, TAXI
, TRUCK
, TWO_WHEELER
, BICYCLE
oder PEDESTRIAN
angegeben werden kann. Der Fahrzeugtyp kann als Filterkriterium in SearchVehicles
und ListVehicles
dienen.
Alle Routen für Fahrzeuge verwenden die entsprechende RouteTravelMode
, wenn die Kategorie auf AUTO
, TWO_WHEELER
, BICYCLE
oder PEDESTRIAN
festgelegt ist.
Wenn die Kategorie auf TAXI
oder TRUCK
festgelegt ist, wird das Routing wie der AUTO
-Modus behandelt.
Fahrzeugattribute
Die Fahrzeugentität enthält ein wiederkehrendes Feld von VehicleAttribute
. Diese Attribute werden von der Fleet Engine nicht interpretiert. Die SearchVehicles
API enthält ein Feld, über das festgelegt wird, dass übereinstimmende Vehicles
alle enthaltenen Attribute enthalten müssen, die auf den angegebenen Wert festgelegt sind.
Beachten Sie, dass das Attributfeld zusätzlich zu mehreren anderen unterstützten Feldern in der Vehicle
-Meldung vorhanden ist, z. B. vehicle_type
und supported_trip_types
.
Verbleibende Wegpunkte des Fahrzeugs
Die Fahrzeugentität enthält ein wiederkehrendes Feld von TripWaypoint
(RPC | REST) namens waypoints
(RPC | REST).
Dieses Feld enthält die verbleibenden Wegpunkte der Fahrten in der Reihenfolge, in der sie mit dem Fahrzeug erreicht werden. Fleet Engine berechnet dieses Feld, wenn dem Fahrzeug Fahrten zugewiesen werden, und aktualisiert es, wenn sich Fahrten ihren Status ändern.
Diese Wegpunkte lassen sich anhand der Felder TripId
und WaypointType
identifizieren.
Mehr Möglichkeiten für Fahrzeuge
In der Regel sind die Dienste des Mitfahrdienstes oder des Lieferanbieters dafür verantwortlich, Fahrtanfragen mit Fahrzeugen abzugleichen. Der Dienst kann die Fahrzeugattribute verwenden, um ein Fahrzeug bei einer größeren Anzahl von Suchanfragen anzugeben. Beispielsweise kann der Anbieter eine Reihe von Attributen implementieren, die den Stufen der Vorteile oder Funktionen eines Fahrzeugs entsprechen. Drei Ebenen können beispielsweise eine Reihe von Attributen mit booleschen Werten sein: is_bronze_level
, is_silver_level
und is_gold_level
. Ein Fahrzeug kann für alle drei Optionen infrage kommen. Wenn die Fleet Engine eine Anfrage für eine Fahrt erhält, für die Silberlevel-Funktionen erforderlich sind, wird dieses Fahrzeug in die Suche einbezogen.
Die Verwendung von Attributen auf diese Weise schließt Fahrzeuge mit einer Vielzahl von Funktionen ein.
Es gibt zwei Möglichkeiten, Fahrzeugattribute zu aktualisieren. Eine davon ist die UpdateVehicle
API. Wenn Sie diese API verwenden, wird der gesamte Satz von Fahrzeugattributen auf den Wert festgelegt. Es ist nicht möglich, nur ein einzelnes Attribut zu aktualisieren.
Die andere Methode ist die UpdateVehicleAttributes
API. Bei dieser Methode werden nur die Attribute verwendet, die aktualisiert werden sollen. In der Anfrage enthaltene Attribute werden auf den neuen Wert festgelegt oder hinzugefügt. Nicht angegebene Attribute werden nicht geändert.
Anleitung: Fahrzeug konstruieren
Für jedes Fahrzeug, das in der Flotte verfolgt werden soll, muss eine Vehicle
-Entität erstellt werden.
Verwenden Sie den Endpunkt CreateVehicle
mit der CreateVehicleRequest
, um ein Fahrzeug zu erstellen.
Der provider_id
von Vehicle
muss die Projekt-ID (z.B. my-on-demand-project) des Google Cloud-Projekts sein, das die Dienstkonten enthält, die zum Aufrufen der Fleet Engine verwendet werden. Beachten Sie, dass zwar mehrere Dienstkonten auf die Fleet Engine für denselben Mitfahrdienst oder Bereitstellungsanbieter zugreifen können, die Fleet Engine jedoch derzeit keine Dienstkonten aus mehreren Google Cloud-Projekten unterstützt, die auf dieselbe Vehicles
zugreifen.
Vehicle
kann mit dem Status OFFLINE
oder ONLINE
erstellt werden. Wenn ein ONLINE
erstellt wurde, wird er möglicherweise sofort als Antwort auf SearchVehicles
-Abfragen zurückgegeben.
Ein erster last_location
-Wert kann im CreateVehicle
-Aufruf enthalten sein.
Obwohl dies zulässig ist, sollte ein Vehicle
nicht im Status ONLINE
ohne last_location
erstellt werden.
Weitere Informationen zum Feld für den Fahrzeugtyp finden Sie unter Fahrzeugtypen.
Weitere Informationen zum Attributfeld finden Sie unter Fahrzeugattribute.
Der von CreateVehicle
zurückgegebene Wert ist die erstellte Vehicle
-Entität.
Beispiel
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Weitere Informationen finden Sie in der Referenz zu providers.vehicles.create.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
Google Cloud Platform-Logs für die Fahrzeugerstellung
Die Fleet Engine API schreibt einen Logeintrag über Google Cloud Platform-Logs, wenn ein Aufruf an den Endpunkt CreateVehicle
empfangen wird. Der Logeintrag enthält Informationen zu den Werten in der CreateVehicle
-Anfrage. Wenn der Aufruf erfolgreich ist, enthält er auch Informationen zur zurückgegebenen Vehicle
.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
Es sollte ein Eintrag ausgegeben werden, der in etwa so aussieht:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
Cloud Pub/Sub-Benachrichtigungen zur Fahrzeugerstellung
Die Fleet Engine API veröffentlicht eine Benachrichtigung über Cloud Pub/Sub, wenn ein neues Fahrzeug erstellt wird. Um diese Benachrichtigungen zu erhalten, folgen Sie dieser Anleitung.
Anleitung: Standort eines Fahrzeugs aktualisieren
Wenn Sie das Driver SDK nicht verwenden, um den Standort des Fahrzeugs zu aktualisieren, können Sie den Standort des Fahrzeugs direkt an Fleet Engine aufrufen. Für jedes aktive Fahrzeug erwartet Fleet Engine mindestens einmal pro Minute und höchstens einmal alle fünf Sekunden ein Standortupdate. Für diese Updates sind nur Nutzerberechtigungen für das Fleet Engine Driver SDK erforderlich.
Beispiel
shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
Weitere Informationen finden Sie in der Referenz zu providers.vehicles.update.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
Anleitung: Andere Fahrzeugfelder aktualisieren
Aktualisierungen anderer Attribute des Fahrzeugstatus erfolgen seltener als Positionsaktualisierungen. Für Aktualisierungen anderer Attribute als last_location
sind die Superuser-Berechtigungen von Fleet Engine erforderlich.
Das UpdateVehicleRequest
enthält ein update_mask
-Element, das angibt, welche Felder aktualisiert werden sollen. Das Verhalten des Felds entspricht dem in der Protobuf-Dokumentation für Feldmasken.
Wie unter Fahrzeugattribute beschrieben, müssen beim Aktualisieren des Felds attributes
alle Attribute beibehalten werden. Es ist nicht möglich, nur den Wert eines Schlüssel/Wert-Paars in einem UpdateVehicle
-Aufruf zu aktualisieren. Zum Aktualisieren der Werte bestimmter Attribute kann die UpdateVehicleAttributes
API verwendet werden.
Beispiel
In diesem Beispiel wird back_to_back
aktiviert.
shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
Weitere Informationen finden Sie in der Referenz zu providers.vehicles.update.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
Google Cloud Platform-Logs für Fahrzeugupdates
Die Fleet Engine API schreibt einen Logeintrag über Google Cloud Platform-Logs, wenn ein Aufruf an den Endpunkt UpdateVehicle
empfangen wird. Der Logeintrag enthält Informationen zu den Werten in der UpdateVehicle
-Anfrage. Wenn der Aufruf erfolgreich ist, enthält er auch Informationen zur zurückgegebenen Vehicle
.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
Cloud Pub/Sub-Benachrichtigungen für Fahrzeugupdates
Die Fleet Engine API veröffentlicht eine Benachrichtigung über Cloud Pub/Sub, wenn ein vorhandenes Fahrzeug aktualisiert wird. Um diese Benachrichtigungen zu erhalten, folgen Sie dieser Anleitung.
Anleitung: Fahrzeuge suchen
Fleet Engine unterstützt die Suche nach Fahrzeugen. Mit der SearchVehicles
API können Sie nach verfügbaren Fahrern in der Nähe suchen, die für eine Aufgabe am besten geeignet sind, z. B. das Servieren einer Fahrt oder eine Lieferanfrage. Die SearchVehicles
API gibt eine Rangliste von Fahrern zurück, die die Aufgabenattribute mit den Fahrzeugattributen Ihrer Flotte übereinstimmen. Weitere Informationen finden Sie unter Fahrer in der Nähe finden.
Beispiel
Bei der Suche nach verfügbaren Fahrzeugen schließt die Fleet Engine standardmäßig Fahrzeuge bei aktiven Fahrten aus. Die Dienste des Mitfahrdienstes oder des Lieferanbieters müssen diese explizit in Suchanfragen einbeziehen. Das folgende Beispiel zeigt, wie diese Fahrzeuge in eine Suche nach Fahrzeugen einbezogen werden, die einer Fahrt von der GrandIndonesia East Mall zum Balai Sidang Jakarta Convention Center entsprechen.
shell
Aktualisieren Sie zuerst den Standort des Fahrzeugs, das wir in den vorherigen Schritten erstellt haben, damit es zulässig ist. In der Praxis erfolgt dies über das Driver SDK, das auf einem Android- oder iOS-Gerät im Fahrzeug ausgeführt wird.
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Die Suche sollte mindestens dieses Fahrzeug liefern.
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
Weitere Informationen finden Sie in der Referenz zu providers.vehicles.search.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Abfrage zum Filtern von Fahrzeugen
SearchVehicles
und ListVehicles
unterstützen das Filtern nach Fahrzeugattributen mithilfe einer Filterabfrage. Beispiele zur Filterabfragesyntax finden Sie unter AIP-160.
Filterabfragen unterstützen NUR das Filtern nach Fahrzeugattributen und können nicht für andere Felder verwendet werden. Die Filterabfrage funktioniert als AND
-Klausel mit anderen Einschränkungen wie minimum_capacity
oder vehicle_types
in SearchVehiclesRequest
.
ANLEITUNG: Fahrzeuge auflisten
SearchVehicles
ist dafür optimiert, schnell eine kleine Anzahl von Fahrzeugen in einer Rangfolge zu finden, und wird hauptsächlich verwendet, um Fahrer in der Nähe zu finden, die für eine Aufgabe am besten geeignet sind. Manchmal möchten Sie jedoch alle Fahrzeuge finden, die bestimmte Kriterien erfüllen, auch wenn Sie die Ergebnisse durchblättern müssen. ListVehicles
ist auf diesen Anwendungsfall ausgelegt.
Mit der ListVehicles
API können Sie alle Fahrzeuge finden, die bestimmte Anfrageoptionen erfüllen. Die ListVehicles
API gibt eine paginierte Liste von Fahrzeugen im Projekt zurück, die einigen Anforderungen entspricht.
Informationen zum Filtern nach Fahrzeugattributen finden Sie unter Abfrage zum Filtern von Fahrzeugen.
Beispiel
In diesem Beispiel wird mit dem String filter
nach vehicle_type
und Attributen gefiltert.
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
Weitere Informationen finden Sie in der Referenz zu providers.vehicles.list.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Reisen und ihr Lebenszyklus
Die Trip API und ihr Lebenszyklus ähneln der Vehicle API und der Lebenszyklus.
Der Mitfahrdienstanbieter ist für das Erstellen von Fahrten über die Fleet Engine-Schnittstellen verantwortlich. Die Fleet Engine bietet sowohl einen RPC-Dienst
TripService
als auch die REST-Ressourcen provider.trips
. Diese Schnittstellen ermöglichen die Erstellung von Trip-Entitäten, Informationsanfragen, Suchfunktionen und Aktualisierungsfunktionen.
Eine Trip
hat ein Statusfeld, in dem der Fortschritt während des Lebenszyklus verfolgt wird.
Die Werte ändern sich von NEW
nach COMPLETE
plus CANCELED
und UNKNOWN_TRIP_STATUS
. Weitere Informationen finden Sie unter trip_status
für RPC oder TripStatus für REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Dein Service kann die Fahrt nach CANCELED
aus einem dieser Status aktualisieren.
Wenn Ihr Dienst eine Fahrt erstellt, legt die Suchmaschine den Status auf NEW
fest. vehicle_id
ist optional. Wie bei Fahrzeugen werden Fahrten auch hier nach sieben Tagen ohne Aktualisierung automatisch gelöscht. Wenn Ihr Dienst versucht, eine Fahrt mit einer bereits vorhandenen ID zu erstellen, wird ein Fehler zurückgegeben. Eine Fahrt gilt als „aktiv“, wenn sie einen anderen Status als COMPLETE
oder CANCELED
hat. Diese Unterscheidung ist im Feld active_trips
in der Entität „Vehicle“ und SearchTripsRequest
wichtig.
Der Dienst kann die einer Fahrt zugewiesenen vehicle_id
nur dann ändern, wenn der Status NEW
oder CANCELED
ist. Wenn ein Fahrer eine Fahrt während der Route abbricht, muss der Fahrtstatus auf NEW
oder CANCELED
gesetzt werden, bevor die vehicle_id
geändert oder gelöscht wird.
Der Status ist wichtig bei der Implementierung der Unterstützung für mehrere Fahrten. Durch diese Unterstützung kann der Anbieter einem Fahrzeug eine neue Fahrt zuweisen, während sich dieses Fahrzeug auf einer aktiven Fahrt befindet. Der Code zum Erstellen einer Fahrt mit mehreren Fahrten ist der gleiche wie für eine einzelne Fahrt und verwendet dieselbe Fahrzeug-ID. Die Fleet Engine fügt den Start- und Zielort der neuen Fahrt den Wegpunkten des Fahrzeugs hinzu. Weitere Informationen zu aufeinanderfolgenden Fahrten finden Sie unter Fahrten mit mehreren Wegpunkten erstellen.
Verbleibende Wegpunkte der Fahrt
Die Entität „Trip“ enthält ein wiederkehrendes Feld von TripWaypoint
(RPC | REST) namens remainingWaypoints
(RPC | REST).
Dieses Feld enthält alle Wegpunkte, die das Fahrzeug in der richtigen Reihenfolge fahren muss, bevor es am letzten Ausstiegspunkt dieser Fahrt liegt. Die Berechnung erfolgt anhand der verbleibenden Wegpunkte des Fahrzeugs.
In den Anwendungsfällen „Back-to-back“ und „Carpool“ enthält diese Liste Wegpunkte von anderen Fahrten, die vor dieser Fahrt durchlaufen werden. Alle Wegpunkte nach dieser Fahrt sind jedoch nicht enthalten. Der Wegpunkt in der Liste lässt sich anhand der Werte TripId
und WaypointType
erkennen.
Die Beziehung zwischen dem Fahrtstatus und den verbleibenden Wegpunkten des Fahrzeugs
Die verbleibenden Wegpunkte des Fahrzeugs (RPC | REST) werden aktualisiert, wenn Fleet Engine eine Anfrage zur Fahrtstatusänderung erhält. Der vorherige Wegpunkt wird aus der Liste der verbleibenden Wegpunkte des Fahrzeugs entfernt, wenn der tripStatus
(RPC | REST) von einem anderen Status in ENROUTE_TO_XXX geändert wird. Das heißt, wenn sich der Fahrtstatus von ENROUTE_TO_PICKUP in ARRIVED_AT_PICKUP ändert, bleibt der Abholpunkt der Fahrt weiterhin in der Liste der verbleibenden Wegpunkte des Fahrzeugs. Wenn der Fahrtstatus jedoch in ENROUTE_TO_INTERMEDIATE_DESTINATION oder ENROUTE_TO_DROPOFF geändert wird, werden die verbleibenden Startpunkte vom Fahrzeug entfernt.
Das Gleiche gilt für ARRIVED_AT_INTERMEDIATE_DESTINATION und ENROUTE_TO_INTERMDEDIATE_DESTINATION. Wenn ARRIVED_AT_INTERMEDIATE_DESTINATION festgelegt ist, wird das aktuelle Zwischenziel erst dann aus der Liste der verbleibenden Wegpunkte des Fahrzeugs entfernt, wenn das Fahrzeug meldet, dass es auf den nächsten Wegpunkt fährt.
Wenn der Fahrtstatus zu COMPLETED
geändert wird, werden keine Wegpunkte aus dieser Fahrt in der Liste der verbleibenden Wegpunkte des Fahrzeugs aufgeführt.
Anleitung: Reise erstellen
Eine Trip
-Entität muss erstellt werden, damit jede Fahrtanfrage verfolgt und mit Fahrzeugen in der Flotte abgeglichen werden kann. Verwenden Sie den Endpunkt CreateTrip
mit CreateTripRequest
, um einen Trip zu erstellen.
Die folgenden Attribute sind erforderlich, um eine Fahrt zu erstellen:
parent
: Ein String mit der Anbieter-ID, die beim Erstellen des Google Cloud-Projekts erstellt wurde.trip_id
: Ein vom Mitfahrdienstanbieter erstellter String.trip
: Container mit grundlegenden Metadaten, die die Fahrt beschreiben.trip_type
: Aufzählung, die angibt, ob für die Fahrt möglicherweise andere Fahrgäste mit einem anderen Start- und Zielort im selben Fahrzeug (SHARED
) oder nur eine Partei (EXCLUSIVE
) fahren.pickup_point
: TerminalLocation, das den Startpunkt der Fahrt darstellt. Weitere Informationen finden Sie in der RPC-Referenz oder der REST-Referenz.
Beim Erstellen einer Fahrt können Sie number_of_passengers
, dropoff_point
und vehicle_id
angeben. Diese Felder sind zwar nicht erforderlich, werden aber beibehalten, wenn Sie sie angeben. Alle anderen Felder für die Fahrt werden ignoriert. Beispielsweise beginnen alle Fahrten mit einem trip_status
von NEW
, auch wenn Sie in der Erstellungsanfrage ein trip_status
von CANCELED
übergeben.
Beispiel
Im folgenden Beispiel wird eine Fahrt zur Grand Indonesia East Mall erstellt. Die Fahrt gilt für zwei Passagiere und ist exklusiv. Der provider_id
des Trip
muss mit der Projekt-ID übereinstimmen. In diesem Beispiel hat der Mitfahrdienstanbieter das Google Cloud-Projekt project-id erstellt. Dieses Projekt muss die Dienstkonten haben, mit denen die Fleet Engine aufgerufen wird. Die Fahrt hat den Status NEW
.
Später, nachdem der Dienst die Fahrt einem Fahrzeug zugeordnet hat, kann er UpdateTrip
aufrufen und die vehicle_id
ändern, wenn die Fahrt einem Fahrzeug zugewiesen wird.
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
Weitere Informationen finden Sie in der Referenz zu providers.trips.create.
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Google Cloud Platform-Logs für die Fahrterstellung
Die Fleet Engine API schreibt einen Logeintrag mithilfe von Google Cloud Platform-Logs, wenn ein Aufruf des Endpunkts CreateTrip
empfangen wird. Der Logeintrag enthält Informationen zu den Werten in der CreateTrip
-Anfrage. Wenn der Aufruf erfolgreich ist, enthält er auch Informationen zur zurückgegebenen Trip
.
Anleitung: Fahrt aktualisieren
Die Entität „Trip“ enthält Felder, die das Tracking durch den Dienst und die Berichterstellung für den Streckenfortschritt durch das Driver SDK und das Consumer SDK ermöglichen. Verwenden Sie die Nachricht UpdateTripRequest
, um die Attribute zu aktualisieren. Dadurch werden die Trip-Felder gemäß der field_mask
der Anfrage aktualisiert.
Weitere Informationen finden Sie unter UpdateTripRequest.
Der Mitfahrdienst ist für die Aktualisierung der folgenden Attribute verantwortlich:
- Fahrtstatus.
- Fahrzeug-ID. Entweder bei der Erstellung oder nach der Zuordnung des Fahrzeugs zu einer Fahrt.
- Änderungen an Abhol-, Absetz- und Wegpunkten
Die Fleet Engine aktualisiert die folgenden Felder automatisch, wenn die Funktion „Reise teilen“ über das Driver SDK oder das Consumer SDK verwendet wird:
- Routes
- Voraussichtliche Ankunft
- Verbleibende Entfernung
- Fahrzeugstandort
- Verbleibende Wegpunkte
Weitere Informationen finden Sie unter Trip
in RPC oder Resource.Trip
in REST.
Google Cloud Platform-Logs für Fahrtaktualisierungen
Die Fleet Engine API schreibt einen Logeintrag mithilfe von Google Cloud Platform-Logs, wenn ein Aufruf des Endpunkts UpdateTrip
empfangen wird. Der Logeintrag enthält Informationen zu den Werten in der UpdateTrip
-Anfrage. Wenn der Aufruf erfolgreich ist, enthält er auch Informationen zur zurückgegebenen Trip
.
Anleitung: Reisen suchen
Fleet Engine unterstützt die Suche nach Fahrten. Wie bereits erwähnt, wird eine Fahrt nach sieben Tagen automatisch gelöscht, sodass SearchTrips
keinen vollständigen Verlauf aller Fahrten zur Verfügung stellt.
SearchTrips
ist zwar eine flexible API, in der folgenden Liste werden jedoch zwei Anwendungsfälle berücksichtigt.
Aktive Fahrten eines Fahrzeugs ermitteln: Der Anbieter kann die derzeit aktiven Fahrten eines Fahrzeugs ermitteln. Innerhalb von
SearchTripsRequest
wirdvehicle_id
auf das infrage kommende Fahrzeug festgelegt undactive_trips_only
auftrue
festgelegt.Anbieter und Flotten-Engine-Status abgleichen: Der Anbieter kann
SearchTrips
verwenden, um sicherzustellen, dass sein Fahrtstatus mit dem der Fleet Engine übereinstimmt. Das ist besonders für TripStatus wichtig. Wenn der Status einer Fahrt, die einem Fahrzeug zugewiesen ist, nicht korrekt aufCOMPLETE
oderCANCELED
festgelegt ist, ist das Fahrzeug nicht inSearchVehicles
enthalten.
Wenn Sie SearchTrips
auf diese Weise verwenden möchten, lassen Sie vehicle_id
leer, setzen Sie active_trips_only
auf true
und legen Sie für minimum_staleness
eine Zeit fest, die länger als die meisten Fahrtdauer ist.
Sie könnten zum Beispiel eine Stunde verwenden. Die Ergebnisse umfassen Fahrten, die weder ABGESCHLOSSEN noch ABGESAGT sind und seit über einer Stunde nicht aktualisiert wurden. Der Anbieter sollte diese Fahrten prüfen, um sicherzustellen, dass ihr Status in der Fleet Engine ordnungsgemäß aktualisiert wird.
Fehlerbehebung
Bei einem DEADLINE_EXCEEDED
-Fehler ist der Status der Fleet Engine unbekannt. Der Anbieter sollte CreateTrip
noch einmal aufrufen, was entweder den Fehler 201 (CREATED) oder 409 (CONFLICT) zurückgibt. Im letzteren Fall war die vorherige Anfrage vor DEADLINE_EXCEEDED
erfolgreich. Weitere Informationen zum Beheben von Fahrtfehlern finden Sie in den Consumer API-Leitfäden für Android oder iOS.
Support für Fahrgemeinschaften
Du kannst einem Fahrzeug, das TripType.SHARED
unterstützt, mehrere Fahrten mit SHARED
zuweisen.
Sie müssen die Reihenfolge aller nicht bestandenen Wegpunkte für alle Fahrten angeben, die dem Fahrzeug in dieser geteilten Fahrt über Trip.vehicle_waypoints
zugewiesen sind, wenn Sie die vehicle_id
für eine gemeinsame Fahrt zuweisen (in einer CreateTrip
- oder UpdateTrip
-Anfrage).
Weitere Informationen finden Sie unter vehicle_waypoints
für RPC oder vehicleWaypoints
für REST.
Unterstützung mehrerer Ziele
Zwischenziel ermitteln
Die Felder intermediateDestinations
und intermediateDestinationIndex
in Trip (RPC | REST) werden kombiniert, um das Ziel anzugeben.
Zwischenziel aktualisieren
Sie können die Zwischenziele über UpdateTrip
aktualisieren. Wenn Sie Zwischenziele aktualisieren, müssen Sie eine vollständige Liste der Zwischenziele angeben, einschließlich der bereits besuchten, nicht nur die neu hinzugefügten oder zu ändernden Ziele.
Wenn intermediateDestinationIndex
auf einen Index nach der Position des neu hinzugefügten/geänderten Zwischenziels verweist, wird das neue/aktualisierte Zwischenziel nicht der waypoints
des Fahrzeugs oder dem remainingWaypoints
der Fahrt hinzugefügt.
Der Grund dafür ist, dass alle Zwischenziele vor intermediateDestinationIndex
als bereits besucht behandelt werden.
Änderungen des Fahrtstatus
Das Feld intermediateDestinationsVersion
in (RPC | REST) ist in der Anfrage zur Aktualisierung des Fahrtstatus erforderlich, die an Fleet Engine gesendet wird, um anzugeben, dass ein Zwischenziel verstrichen ist. Das ausgewählte Zwischenziel wird im Feld intermediateDestinationIndex
angegeben.
Wenn tripStatus
(RPC | REST) ENROUTE_TO_INTERMEDIATE_DESTINATION ist, gibt eine Zahl zwischen [0...N-1] an, welches Zwischenziel das Fahrzeug als Nächstes durchquert.
Wenn tripStatus
den Wert ARRIVED_AT_INTERMEDIATE_DESTINATION hat, gibt eine Zahl zwischen [0...N-1] an, an welchem Zwischenziel sich das Fahrzeug befindet.
Beispiel
Im folgenden Codebeispiel wird gezeigt, wie der Status einer Fahrt auf der Route zum ersten Zwischenziel aktualisiert wird. Dabei wird davon ausgegangen, dass Sie eine Fahrt mit mehreren Zielen erstellt haben und die Fahrt den Abholpunkt überschritten hat.
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// Trip update request
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the
// update mask.
.build())
.build();
// Error handling
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
Anleitung: Benachrichtigungen von der Fleet Engine API abonnieren
Die Fleet Engine API verwendet Google Cloud Pub/Sub, um Benachrichtigungen zu dem Thema zu veröffentlichen, das vom Google Cloud-Nutzerprojekt erstellt wurde. Pub/Sub ist in Ihrem Google Cloud-Projekt nicht standardmäßig für Fleet Engine aktiviert. Stellen Sie eine Supportanfrage oder wenden Sie sich an Ihren Customer Engineer, um Pub/Sub zu aktivieren.
Folgen Sie dieser Anleitung, um ein Thema in Ihrem Cloud-Projekt zu erstellen. Die Themen-ID muss „fleet_engine_notifications“ lauten.
Das Thema muss in dem Cloud-Projekt erstellt werden, das die Fleet Engine APIs aufruft.
Nachdem das Thema erstellt wurde, müssen Sie der Fleet Engine API die Berechtigung zum Veröffentlichen des Themas erteilen. Klicken Sie dazu auf das Thema, das Sie gerade erstellt haben,
und fügen Sie eine neue Berechtigung hinzu. Möglicherweise müssen Sie auf Infofeld ansehen klicken, um den Berechtigungseditor zu öffnen.
Das Hauptkonto sollte geo-fleet-engine@system.gserviceaccount.com
und die Rolle Pub/Sub publisher
sein.
Folgen Sie dieser Anleitung, um Ihr Cloud-Projekt für das Abonnieren von Benachrichtigungen einzurichten
Die Fleet Engine API veröffentlicht jede Benachrichtigung in zwei verschiedenen Datenformaten: protobuf
und json
. Das Datenformat für jede Benachrichtigung ist in den PubsubMessage-Attributen mit dem Schlüssel als data_format
und dem Wert protobuf
oder json
angegeben.
Benachrichtigungsschema:
Protobuf
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}