Mit der Fleet Engine On-demand Rides and Deliveries API können Sie Fahrten verwalten und Fahrzeugstatus für Ihre App „Reise- und Bestellfortschritt“. Es verarbeitet Transaktionen zwischen dem Driver SDK, dem Consumer SDK und Ihrem Back-End-Dienst, der mit der Fleet Engine kommunizieren kann, indem er entweder gRPC oder REST-Aufrufe.
Vorbereitung
Achten Sie bei der Entwicklung darauf, dass Sie die Cloud SDK (gcloud) und sind für für Ihr Projekt.
shell
gcloud auth login
Es sollte eine Erfolgsmeldung wie die folgende angezeigt werden:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Prüfen Sie, ob die On-demand Rides and Deliveries Solution Fleet Engine APIs entsprechend 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 Lognachrichten über empfangene API-Aufrufe schreiben Google Cloud Platform-Logs. In der Cloud Logging-Dokumentation finden Sie Übersicht über das Lesen und Analysieren von Logs.
Logging ist möglicherweise für Projekte, die vor erstellt wurden, nicht standardmäßig aktiviert 10. Februar 2022. Weitere Informationen finden Sie in der Logging-Dokumentation .
Clientbibliotheken
Wir veröffentlichen Client-Bibliotheken in verschiedenen gängigen Programmiersprachen. Diese Bibliotheken ermöglichen eine bessere Entwicklung im Vergleich zu REST oder gRPC. Wie Sie Clientbibliotheken für Ihre Serveranwendung abrufen, Siehe Clientbibliotheken.
Die Java-Beispiele in dieser Dokumentation setzen voraus, dass Sie mit gRPC vertraut sind.
Authentifizierung und Autorisierung
Sie können die Funktionen für Fahrten und Bestellfortschritte bis in der Google Cloud Console. Für diese APIs und SDKs ist die Verwendung von JSON Web Tokens erforderlich, die mit Dienstkonten signiert, die aus Cloud Console
Cloud-Projekt einrichten
Erstellen Sie zum Einrichten Ihres Cloud-Projekts zuerst Ihr Projekt und dann Dienstkonten erstellen.
So erstellen Sie Ihr Google Cloud-Projekt:
- Erstellen Sie mit der Google Cloud Console ein Google Cloud-Projekt.
- Aktivieren Sie im Dashboard „APIs und Dienste“ die Local Rides and Deliveries API
Dienstkonten sind mit einer oder mehreren Rollen verknüpft. Sie dienen dazu, JSON Web Tokens, die unterschiedliche Berechtigungen gewähren, je nachdem, Rollen. Um Missbrauch zu vermeiden, können Sie in der Regel mehrere Dienstkonten mit jeweils dem erforderlichen Mindestsatz an Rollen.
Für Fahrten und Bestellfortschritte 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. Von einem Dienstkonto erstellte Tokens mit diesem werden in der Regel auf den Mobilgeräten Ihrer Mitfahrdienst- oder Liefer-App verwendet. |
Fleet Engine Driver SDK-Nutzer
roles/fleetengine.driverSdkUser |
Gewährt die Berechtigung zum Aktualisieren von Fahrzeugstandorten und ‐routen sowie um Informationen zu Fahrzeugen und Fahrten abzurufen. Tokens erstellt Dienstkonten mit dieser Rolle werden in der Regel von Ihrem mobile Mitfahrdienst- oder Lieferfahrer-Apps. |
Fleet Engine On-Demand-Administrator
roles/fleetengine.ondemandAdmin |
Gewährt Lese- und Schreibberechtigungen für alle Fahrzeug- und Fahrtenressourcen. Hauptkonten mit dieser Rolle müssen keine JWTs verwenden und sollten stattdessen Standardanmeldedaten für Anwendungen verwenden. Benutzerdefinierte JWT-Anforderungen werden ignoriert. Diese Rolle sollte auf vertrauenswürdige Umgebungen (Kunden-Backend) beschränkt werden. |
roles/fleetengine.serviceSuperUser |
Gewährt Berechtigungen für alle APIs für Fahrzeuge und Fahrten. Tokens erstellt
von einem Dienstkonto mit dieser Rolle werden in der Regel aus Ihrem Back-End verwendet.
Server. Diese Rolle wurde verworfen. Bevorzugen
Stattdessen roles/fleetengine.ondemandAdmin . |
Erstellen Sie beispielsweise ein Dienstkonto für jede der drei Rollen und weisen Sie ihre jeweilige Rolle.
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 das Consumer SDK basieren auf diesen Standardrollen.
Alternativ ist es möglich, benutzerdefinierte Rollen zu erstellen, Beliebige Reihe von Berechtigungen, die zu gebündelt werden können. Das Treiber- und das Consumer-SDK zeigen Fehlermeldungen an, wenn ein erforderliche Berechtigung fehlt. Daher empfehlen wir dringend, Dabei werden die oben beschriebenen Standardrollen und keine benutzerdefinierten Rollen verwendet.
Wenn Sie JWT-Tokens für nicht vertrauenswürdige Clients erstellen müssen, fügen Sie Nutzer mit der Rolle „Service Account Token Creator“ können Tokens erstellen gcloud-Befehlszeilentools verwenden.
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 für Folgendes verwendet wird:
Authentifizieren Sie sich mit gcloud (gcloud auth list
--format='value(account)'
).
Fleet Engine-Auth-Bibliothek
Fleet Engine verwendet JSON Web Tokens (JWTs), um den Zugriff auf Fleet Engine APIs Die neue Fleet Engine-Auth-Bibliothek auf GitHub verfügbar, vereinfacht das Erstellen von Fleet Engine-JWTs und signiert sie sicher.
Die Bibliothek bietet folgende Vorteile:
- Vereinfacht das Erstellen von Fleet Engine-Tokens.
- Stellt Tokensignaturmechanismen bereit, die keine Anmeldedatendateien verwenden (z. B. Identitätsdiebstahl eines Dienstkontos)
- Hängt signierte Tokens an ausgehende Anfragen an, die von einem gRPC-Stub oder GAPIC-Client.
JSON-Webtoken (JWT) für die Autorisierung erstellen
Wenn Sie die Fleet Engine Auth Library nicht verwenden, müssen die JSON Web Tokens (JWTs) mit die direkt in Ihrer Codebasis erstellt wurden. Dazu benötigen Sie sowohl eine von JWTs und deren Beziehung zu Fleet Engine. Aus diesem Grund Wir empfehlen UNBEDINGT, die Fleet Engine Auth Library zu nutzen.
In Fleet Engine bieten JSON Web Tokens (JWTs) eine kurzlebige Authentifizierung und sicherzustellen, dass Geräte nur Fahrzeuge, Fahrten oder Aufgaben für die sie autorisiert sind. JWTs enthalten einen Header und einen Anforderungsabschnitt. Der Header-Abschnitt enthält Informationen wie die den von Dienstkonten abgerufenen privaten Schlüssel und die Verschlüsselung Algorithmus. Der Abschnitt zum Anspruch enthält Informationen wie die Erstellungszeit des Tokens, Gültigkeitsdauer des Tokens, Dienste, die es ist das Behaupten des Zugriffs auf und andere Autorisierungsinformationen Zugriff z. B. die Fahrzeug-ID.
Ein JWT-Header-Abschnitt enthält die folgenden Felder:
Feld | Beschreibung |
---|---|
alg | Der zu verwendende Algorithmus. „RS256“. |
Typ | Der Tokentyp. „JWT“. |
Kind | Die private Schlüssel-ID Ihres Dienstkontos. Diesen Wert finden Sie im Feld „private_key_id“ der JSON-Datei Ihres Dienstkontos ein. Achten Sie darauf, einen Schlüssel von einem Dienstkonto mit der richtigen Berechtigungsstufe zu verwenden. |
Der Abschnitt für die JWT-Anforderungen enthält die folgenden Felder:
Feld | Beschreibung |
---|---|
iss | Die E-Mail-Adresse Ihres Dienstkontos. |
sub | Die E-Mail-Adresse Ihres Dienstkontos. |
aud | Der SERVICE_NAME Ihres Dienstkontos, in diesem Fall https://fleetengine.googleapis.com/ |
iat | Der Zeitstempel für die Erstellung des Tokens, angegeben in verstrichenen Sekunden seit 00:00:00 UTC am 1. Januar 1970. Planen Sie 10 Minuten für die Verzerrung ein. Wenn die Wenn der Zeitstempel zu weit in der Vergangenheit oder Zukunft liegt, meldet der Server möglicherweise einen Fehler. |
exp | Der Zeitstempel für das Ablaufdatum des Tokens, angegeben in verstrichenen Sekunden seit 00:00:00 UTC am 1. Januar 1970. Die Anfrage schlägt fehl, wenn der Zeitstempel mehr als eine Stunde in der Zukunft liegt. |
Autorisierung | Kann je nach Anwendungsfall „vehicleid“ oder „tripid“ enthalten. |
Das Erstellen eines JWT-Tokens bezieht sich auf das Signieren. Anleitungen und Codebeispiele zum Erstellen und Signieren des JWT, siehe Dienstkontoautorisierung ohne OAuth: Sie können dann ein signiertes Token an gRPC-Aufrufe oder andere verwendete Methoden anhängen. um auf Fleet Engine zuzugreifen.
JWT-Anforderungen
Fügen Sie beim Erstellen der JWT-Nutzlast in der Autorisierung eine zusätzliche Anforderung hinzu.
mit dem Schlüssel vehicleid
oder tripid
, der auf den Wert des
Fahrzeug-ID oder Fahrt-ID, für die der Anruf getätigt wird.
Das Driver SDK verwendet immer die vehicleid
-Anforderung, unabhängig davon, ob auf
eine Reise oder ein Fahrzeug. Das Fleet Engine-Back-End
sorgt dafür, dass das Fahrzeug
mit der angeforderten Fahrt verknüpft ist, bevor die Änderung vorgenommen wird.
Das Consumer SDK verwendet immer die tripid
-Anforderung.
Der Mitfahrdienst oder Lieferdienst muss vehicleid
oder tripid
mit einem „*“ verwenden bis
Übereinstimmung mit allen Fahrzeugen und Fahrten. Das JWT kann sowohl Tokens
auch wenn nicht erforderlich, was die Implementierung der Tokensignatur vereinfachen kann.
JWT-Anwendungsfälle
Im Folgenden sehen Sie ein Beispieltoken für einen 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": "*"
}
}
Hier sehen Sie ein Beispieltoken für die Nutzer-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"
}
}
Hier sehen Sie ein Beispieltoken für die Treiber-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 Feld
kid
im Header den privaten Schlüssel Ihres Dienstkontos an ID. Sie finden diesen Wert im Feldprivate_key_id
Ihres Dienstes JSON-Datei des Kontos. - Geben Sie in den Feldern
iss
undsub
die E-Mail-Adresse Ihres Dienstkontos an. Sie finden diesen Wert in Ihrem Dienstkonto im Feldclient_email
. JSON-Datei. - Geben Sie für das Feld
aud
https://SERVICE_NAME/ an. - Geben Sie für das Feld
iat
den Zeitstempel der Erstellung des Tokens an. angegeben als verstrichene Sekunden seit dem 1. Januar 1970 00:00:00 UTC. Planen Sie 10 Minuten für die Verzerrung ein. Wenn der Zeitstempel zu weit in der Vergangenheit liegt, oder in Zukunft, meldet der Server einen Fehler. - Geben Sie im Feld
exp
den Zeitstempel an, der angibt, wann das Token abläuft. angegeben als Sekunden seit dem 1. Januar 1970 00:00:00 UTC. Das Maximum Der zulässige Wert istiat
+ 3.600.
Achte beim Signieren des JWT, das an ein Mobilgerät übergeben werden soll, Dienstkonto für die Rolle „Driver“ oder „Consumer SDK“ Andernfalls wird das mobile Gerät kann den Status ändern, den es nicht haben sollte.
Achten Sie beim Signieren des JWT, das für privilegierte Aufrufe verwendet werden soll, ebenfalls darauf, um das Dienstkonto mit der Rolle „Super User“ zu verwenden. Andernfalls wird das Feld schlägt der Vorgang fehl.
JWT zum Testen generieren
Das Generieren von Tokens über das Terminal kann beim Testen hilfreich sein.
Um diese Schritte ausführen zu können, Konto muss 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 iat
ist die aktuelle Zeit in Sekunden seit der Epoche. Der Wert kann
abgerufen, indem date +%s
in deinem Terminal ausgeführt wird. Das Attribut exp
ist der
die Ablaufzeit in Sekunden nach der Epoche und kann folgendermaßen berechnet werden:
iat
wird 3.600 hinzugefügt. Die Ablaufzeit darf nicht mehr als eine Stunde im
in der Zukunft.
{ "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- Nutzerdienstkonto:
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 gespeichert sein
signed_token.jwt
Das Token ist für die nächste Stunde gültig.
Sie können das Token jetzt testen, indem Sie den Befehl curl
für die Fahrzeugliste ausführen.
REST-Endpunkt:
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 Ein Fahrer und ein Fahrzeug können nicht separat verfolgt werden. Mitfahrdienst oder Lieferdienst ein Fahrzeug mit einer Anbieter-ID (muss mit der ID Projekt-ID des Google Cloud-Projekts, das das Dienstkonto enthält zum Aufrufen der Fleet Engine APIs) und einer Fahrzeug-ID eines Mitfahrdienstes oder eines Zustellers verwendet wird.
Ein Fahrzeug, das nach sieben Tagen noch nicht über UpdateVehicle
aktualisiert wurde,
automatisch gelöscht und die zugehörigen Fahrten, falls vorhanden, werden als
nicht zugewiesen. Die empfohlene Vorgehensweise, damit ein Fahrzeug verfügbar bleibt
in Fleet Engine ist die regelmäßige
Aktualisierung des Standorts. Aktualisierungen für die meisten
andere Felder in der Entität Vehicle
verlängern ebenfalls ihre Lebensdauer, sofern
dass sich der neue Feldwert von dem vorhandenen unterscheidet.
HINWEIS: Einige Felder in der Entität Vehicle
wie device_settings
dienen ausschließlich zur Fehlerbehebung.
Informationen, die nicht von Fleet Engine gespeichert werden. Das Aktualisieren
die Lebensdauer der Vehicle
-Entität verlängern.
Fehler beim Aufrufen von CreateVehicle
mit einer
Paar „Anbieter-ID/Fahrzeug-ID“ ist bereits vorhanden. Der Fall von Fahrzeugen,
nicht regelmäßig aktualisiert werden, kann dies zwei Ursachen haben: häufige Anrufe
CreateVehicle
mit einem erwarteten Paar aus Anbieter-ID und Fahrzeug-ID und wird verworfen
den Fehler, wenn das Fahrzeug bereits vorhanden ist; oder CreateVehicle
nach einer
UpdateVehicle
gibt den Fehler NOT_FOUND
zurück.
Updates zum Fahrzeugstandort
Die beste Leistung erzielen Sie, wenn Sie Fleet Engine mit einem Fahrzeugstrom versorgen. Standortaktualisierungen. Verwenden Sie eine der folgenden Möglichkeiten, um diese Aktualisierungen bereitzustellen:
- Treiber-SDK verwenden: Android-Geräte iOS -- die einfachste Option.
- Verwenden Sie benutzerdefinierten Code. Dies ist nützlich, wenn Standorte oder wenn Sie andere Geräte als Android oder iOS
Fahrzeugtypen
Die Entität „Vehicle“ (Fahrzeug) enthält das Pflichtfeld VehicleType
mit einem
Category
-Enum, das als AUTO
, TAXI
, TRUCK
, angegeben werden kann,
TWO_WHEELER
, BICYCLE
oder PEDESTRIAN
. Der Fahrzeugtyp kann als
Filterkriterien in SearchVehicles
und ListVehicles
.
Bei allen Routen für Fahrzeuge wird die entsprechende RouteTravelMode
verwendet, wenn
Die Kategorie ist entweder auf AUTO
, TWO_WHEELER
, BICYCLE
oder PEDESTRIAN
festgelegt.
Wenn die Kategorie auf TAXI
oder TRUCK
festgelegt ist, wird die Weiterleitung wie folgt behandelt:
AUTO
-Modus.
Fahrzeugattribute
Die Entität „Vehicle“ enthält ein wiederkehrendes Feld von VehicleAttribute
. Diese
Attribute werden von Fleet Engine nicht interpretiert. Das SearchVehicles
Die API enthält ein Feld, mit dem festgelegt werden muss, dass übereinstimmende Vehicles
-Elemente alle enthalten müssen
die enthaltenen Attribute, die auf den angegebenen Wert festgelegt sind.
Beachten Sie, dass das Attributfeld eine Ergänzung zu einigen anderen unterstützten Feldern enthält.
in der Vehicle
-Nachricht, z. B. vehicle_type
und supported_trip_types
.
Verbleibende Fahrzeugwegpunkte
Die Entität „Vehicle“ enthält ein wiederkehrendes Feld von TripWaypoint
(RPC | REST).
mit dem Namen waypoints
(RPC | REST).
Dieses Feld enthält die verbleibenden Wegpunkte in der Reihenfolge,
wie das Fahrzeug sie erreicht. Fleet Engine berechnet dieses Feld so, dass Fahrten
zugewiesen und aktualisiert es, wenn sich der Status von Fahrten ändert.
Diese Wegpunkte können durch die Felder TripId
und WaypointType
angegeben werden.
Mehr Möglichkeiten für Übereinstimmungen
In der Regel sind die Fahrdienste von Mitfahrdiensten oder Lieferdiensten für die Zuordnung der Fahrt verantwortlich.
an Fahrzeuge senden. Der Dienst kann mithilfe der Fahrzeugattribute eine
bei einer größeren Anzahl von
Suchanfragen verwendet wird. Der Anbieter kann beispielsweise
eine Reihe von Attributen, die den Stufen der Vorteile oder Fähigkeiten entsprechen, die von
ein Fahrzeug. Drei Ebenen könnten z. B. eine Reihe von Attributen mit booleschen
Werte: is_bronze_level
, is_silver_level
und is_gold_level
. Ein Fahrzeug
für alle drei infrage kommen. Wenn die Fleet Engine eine Anfrage für eine
die Silber-Status erfordert, wird dieses Fahrzeug in der Suche berücksichtigt.
Wenn Sie Attribute auf diese Weise verwenden, sind auch Fahrzeuge eingeschlossen, die eine Vielzahl von
Funktionen.
Es gibt zwei Möglichkeiten, Fahrzeugattribute zu aktualisieren. Einer ist der UpdateVehicle
der API erstellen. Bei Verwendung dieser API ist der gesamte Satz an Fahrzeugattributen
auf den Wert festgelegt ist. Es ist nicht möglich, nur ein einzelnes Attribut zu aktualisieren.
Die andere Methode ist die UpdateVehicleAttributes
API. Bei dieser Methode werden nur
die zu aktualisierenden Attribute. In der Anfrage enthaltene Attribute sind
auf den neuen oder hinzugefügten Wert festgelegt; nicht spezifizierte Attribute werden nicht geändert.
ANLEITUNG: Fahrzeug erstellen
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 einen
Fahrzeug.
Die provider_id
von Vehicle
muss die Projekt-ID sein
(z.B. my-on-demand-Projekt) des Google Cloud-Projekts, das die
Dienstkonten, die zum Aufrufen der Fleet Engine verwendet werden. Hinweis: Während
mehrere Dienstkonten können für denselben Mitfahrdienst auf die Fleet Engine zugreifen.
Delivery Provider unterstützt, unterstützt die Fleet Engine derzeit keine Dienstkonten von
Mehrere Google Cloud-Projekte greifen auf dasselbe Vehicles
zu.
Das Vehicle
kann im Status OFFLINE
oder ONLINE
erstellt werden. Wenn
erstellt am ONLINE
, wird er möglicherweise sofort als Antwort auf SearchVehicles
zurückgegeben.
Abfragen.
Ein anfänglicher last_location
kann im CreateVehicle
-Aufruf enthalten sein.
Obwohl dies zulässig ist, sollte ein Vehicle
im Status ONLINE
nur erstellt werden, wenn
last_location
.
Weitere Informationen zum Fahrzeug finden Sie unter Fahrzeugtypen type ein.
Weitere Informationen finden Sie in den Fahrzeugattributen. für das Attributfeld.
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 unter providers.vehicles.create Referenz.
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 zum Erstellen von Fahrzeugen
Die Fleet Engine API schreibt einen Log-Eintrag über Google Cloud Platform-Logs, wenn
an den Endpunkt CreateVehicle
empfangen wird. Der Logeintrag enthält
Informationen zu den Werten in der CreateVehicle
-Anfrage. Wenn der Anruf
enthält, enthält sie auch Informationen zur Vehicle
, die
zurückgegeben.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
Der Datensatz sollte in etwa so gedruckt werden:
---
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 für Fahrzeugerstellung
Die Fleet Engine API veröffentlicht eine Benachrichtigung über Cloud Pub/Sub, wenn eine neue das Fahrzeug erstellt wird. Um diese Benachrichtigungen zu erhalten, folgen Sie bitte der Anleitung.
ANLEITUNG: Fahrzeugstandort aktualisieren
Wenn Sie das Driver SDK nicht verwenden, um den Standort des Fahrzeugs zu aktualisieren, können Sie einen direkten Aufruf der Fleet Engine mit dem Standort des Fahrzeugs. Für alle aktiven Fahrzeuge Fleet Engine erwartet ein Standortupdate mindestens einmal pro Minute und höchstens einmal alle 5 Sekunden. Für diese Updates ist nur ein Fleet Engine Driver SDK-Nutzer erforderlich Berechtigungen.
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 unter providers.vehicles.update Referenz.
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
Andere Attribute des Fahrzeugstatus werden seltener aktualisiert als
zu aktualisieren. Aktualisierungen anderer Attribute als last_location
erfordern
Fleet Engine-Superuser-Berechtigungen.
UpdateVehicleRequest
enthält einen update_mask
, der angibt, welche Felder
aktualisieren. Das Verhalten des Feldes entspricht dem in der Protobuf-Dokumentation für
Feldmasken.
Wie unter Fahrzeugattribute beschrieben, aktualisieren Sie die
Im Feld attributes
müssen alle Attribute geschrieben werden, die beibehalten werden sollen. Es
den Wert eines Schlüssel/Wert-Paars in einem
UpdateVehicle
Anruf. Um die Werte bestimmter Attribute zu aktualisieren,
Die UpdateVehicleAttributes
API kann 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 unter providers.vehicles.update Referenz.
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 Log-Eintrag über Google Cloud Platform-Logs, wenn
an den Endpunkt UpdateVehicle
empfangen wird. Der Logeintrag enthält
Informationen zu den Werten in der UpdateVehicle
-Anfrage. Wenn der Anruf
enthält, enthält sie auch Informationen über die Vehicle
, die
zurückgegeben.
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 eine vorhandene das Fahrzeug aktualisiert wird. Um diese Benachrichtigungen zu erhalten, folgen Sie bitte der Anleitung.
ANLEITUNG: Fahrzeuge suchen
Fleet Engine unterstützt die Suche nach Fahrzeugen. Das SearchVehicles
Die API ermöglicht es Ihnen, verfügbare Fahrer in der Nähe zu finden, die für eine Aufgabe am besten geeignet sind, z. B.
Fahrdienst- oder Lieferanfragen durchgeführt werden. Die SearchVehicles
API gibt eine
Rangliste der Fahrer, die die Aufgabenattribute mit den Fahrzeugattributen in
für Ihre Flotte. Weitere Informationen finden Sie unter
Suche nach Fahrern in der Nähe.
Beispiel
Bei der Suche nach verfügbaren Fahrzeugen schließt Fleet Engine Fahrzeuge aus standardmäßig aktive Fahrten. Die Dienste des Mitfahrdienstes oder Lieferanbieters müssen explizit in Suchanfragen einschließen. Das folgende Beispiel zeigt, wie Sie diese Fahrzeuge in eine Suche nach Fahrzeugen einschließen, die mit einer Fahrt vom Grand Indonesia East Mall zum Balai Sidang Jakarta Convention Center.
shell
Aktualisieren Sie zunächst den Standort des in den vorherigen Schritten erstellten Fahrzeugs, infrage kommen. In der Praxis würde das über das Treiber-SDK erfolgen, auf einem Android- oder iOS-Gerät im Fahrzeug.
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 ergeben.
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 unter providers.vehicles.search Referenz.
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;
}
Anfrage zum Filtern von Fahrzeugen
SearchVehicles
und ListVehicles
unterstützen das Filtern nach Fahrzeugattributen
mithilfe einer Filterabfrage. Informationen zur Filterabfragesyntax finden Sie unter
AIP-160.
Beachten Sie, dass Filterabfragen NUR das Filtern nach Fahrzeugattributen unterstützen.
kann 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 für die Suche nach einer kleinen Anzahl von Fahrzeugen im Ranking optimiert
sehr schnell und wird hauptsächlich verwendet, um Fahrer in der Nähe zu finden,
zu einer Aufgabe hinzufügen. Sie möchten jedoch auch alle Fahrzeuge finden,
selbst wenn das Durchblättern der Ergebnisse erforderlich ist. ListVehicles
ist
die speziell für diesen Anwendungsfall entwickelt wurden.
Mit der ListVehicles
API können Sie alle Fahrzeuge finden, die bestimmte
Anfrageoptionen. Die ListVehicles
API gibt eine paginierte Liste von Fahrzeugen in
das einige Anforderungen erfüllt.
Informationen zum Filtern nach Fahrzeugattributen finden Sie unter Anfrage zum Filtern von Fahrzeugen.
Beispiel
In diesem Beispiel wird nach vehicle_type
und Attributen gefiltert. Dabei werden die Parameter
filter
-String.
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 unter providers.vehicles.list Referenz.
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;
}
Fahrten und ihr Lebenszyklus
Die Trip API und der Lebenszyklus ähneln der Vehicle API und dem Lebenszyklus.
Der Mitfahrdienst ist für die Erstellung von Fahrten mithilfe der Fleet Engine verantwortlich.
Schnittstellen. Fleet Engine bietet
einen RPC-Dienst,
TripService
und REST-Ressourcen provider.trips
. Über diese Oberflächen können Trip-Entitäten erstellt, Informationen angefordert und
Funktionalität und Update-Funktion.
Eine Trip
hat ein Statusfeld, um ihren Fortschritt im Lebenszyklus zu verfolgen.
Die Werte verschieben sich von NEW
nach COMPLETE
plus CANCELED
und UNKNOWN_TRIP_STATUS
. Siehe 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
mit einem dieser Status aktualisieren.
Wenn Ihr Service eine Fahrt erstellt, legt der Motor den Status auf NEW
fest. A
vehicle_id
ist optional. Wie bei Fahrzeugen löschen die Dienste nicht zugewiesene Fahrten automatisch
nach 7 Tagen ohne
Update zu kaufen. Wenn Ihr Service versucht, eine Fahrt mit einer
ID bereits vorhanden ist, wird ein Fehler zurückgegeben. Eine Fahrt gilt als „aktiv“, wenn
Sie hat einen anderen Status als COMPLETE
oder CANCELED
. Diese Unterscheidung
in der Entität „Fahrzeug“ und SearchTripsRequest
im Feld active_trips
wichtig.
Dein Service kann die vehicle_id
, die einer Fahrt zugewiesen ist, nur ändern, wenn die Fahrt
ist aktiv. Das ist zum Beispiel der Fall, wenn ein Fahrer eine Fahrt annulliert, während
und die Fahrt wird einem anderen Fahrzeug zugewiesen.
Der Status ist wichtig, wenn eine direkte Implementierung Reiseunterstützung. Diese Unterstützung ermöglicht es dem Anbieter, einem Fahrzeug eine neue Fahrt zuzuweisen während sich das Fahrzeug auf einer aktiven Fahrt befindet. Der Code zum Erstellen einer direkt aufeinanderfolgenden Fahrt ist identisch mit Fahrzeug-ID. Fleet Engine fügt den Start- und Zielort der neuen Fahrt zur die Wegpunkte des Fahrzeugs. Weitere Informationen zu aufeinanderfolgenden Fahrten finden Sie unter Fahrten mit mehreren Wegpunkten erstellen
Verbleibende Wegpunkte
Die Entität „Trip“ enthält ein wiederkehrendes Feld von TripWaypoint
(RPC | REST).
mit dem Namen remainingWaypoints
(RPC | REST).
Dieses Feld enthält alle Wegpunkte, die das Fahrzeug in dieser Reihenfolge zurücklegen muss.
vor dem letzten Ausstiegspunkt dieser Fahrt. Berechnung anhand von
Verbleibende Wegpunkte des Fahrzeugs.
Bei den Anwendungsfällen für Rücken an Rücken und Fahrgemeinschaft enthält diese Liste Wegpunkte aus
andere Fahrten, die vor dieser Fahrt durchlaufen werden, aber Wegpunkte ausgeschlossen
nach dieser Reise. Der Wegpunkt in der Liste kann anhand seiner TripId
identifiziert werden
und WaypointType
.
Die Beziehung zwischen Fahrtstatus und verbleibenden Wegpunkten des Fahrzeugs
Die verbleibenden Wegpunkte (RPC | REST) des Fahrzeugs
wird aktualisiert, wenn Fleet Engine eine Anfrage zur Änderung des Fahrtstatus erhält. Die
wird der vorherige Wegpunkt aus der Liste der verbleibenden Wegpunkte entfernt, wenn
den tripStatus
(RPC | REST)
wird von anderem Status in ENROUTE_TO_XXX geändert. Das heißt, wenn
sich der Fahrtstatus von ENROUTE_TO_PICKUP in ARRIVED_AT_PICKUP ändert,
ist der Abholpunkt weiterhin in der Liste der verbleibenden Wegpunkte, aber
Status in ENROUTE_TO_INTERMEDIATE_DESTINATION oder ENROUTE_TO_DROPOFF geändert wird,
wird sein Abholpunkt dann aus den verbleibenden Wegpunkten des Fahrzeugs entfernt.
Das Gleiche gilt für ARRIVED_AT_INTERMEDIATE_DESTINATION und ENROUTE_TO_INTERMDEDIATE_DESTINATION. Bei ARRIVED_AT_INTERMEDIATE_DESTINATION, wird das aktuelle Zwischenziel nicht aus dem verbleibenden Ziel entfernt. bis das Fahrzeug meldet, dass es auf der Route zum nächsten Wegpunkt ist.
Wenn der Fahrtstatus zu COMPLETED
geändert wird, werden keine Wegpunkte von dieser Fahrt
in der verbleibenden Wegpunktliste des Fahrzeugs.
ANLEITUNG: Eine Reise erstellen
Es muss eine Trip
-Entität erstellt werden, damit jede Fahrtanfrage verfolgt und
den Fahrzeugen in der Flotte zugeordnet. Endpunkt CreateTrip
mit CreateTripRequest
verwenden
, um eine Reise zu erstellen.
Die folgenden Attribute sind erforderlich, um eine Fahrt zu erstellen:
parent
: ein String, der die Anbieter-ID enthält, die beim Verwenden der Cloud-Projekt wurde erstellt.trip_id
: ein vom Mitfahrdienst-Anbieter erstellter Stringtrip
: Container mit grundlegenden Metadaten, die die Fahrt beschreiben.trip_type
: Aufzählung, die angibt, ob die Fahrt möglicherweise andere Fahrgäste haben könnte von einem anderen Start- und Zielort im selben Fahrzeug (SHARED
) oder nur für eine einzelne Partei (EXCLUSIVE
).pickup_point
: TerminalLocation, das den Startpunkt für den Fahrt. Siehe RPC-Referenz oder REST-Referenz
Wenn Sie eine Reise erstellen, können Sie Folgendes angeben: number_of_passengers
, dropoff_point
und vehicle_id
. Obwohl diese Felder nicht erforderlich sind,
bleiben sie erhalten. Alle anderen Trip-Felder werden ignoriert. Beispielsweise werden alle Fahrten
beginnen Sie mit einem trip_status
von NEW
, auch wenn Sie eine trip_status
von
CANCELED
in der Anfrage zur Erstellung.
Beispiel
Im folgenden Beispiel wird eine Fahrt zur Grand Indonesia East Mall erstellt. Die Fahrt
ist für zwei Passagiere exklusiv. Die provider_id
von Trip
muss
Projekt-ID übereinstimmen. In diesem Beispiel hat der Mitfahrdienst die
Google Cloud-Projekt, project-id. Dieses Projekt muss die
Dienstkonten, die zum Aufrufen der Fleet Engine verwendet werden. Der Status der Fahrt ist „NEW
“.
Später, nachdem der Dienst die Fahrt einem Fahrzeug zugeordnet hat, kann der Dienst
UpdateTrip
und ändern vehicle_id
, 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 unter providers.trips.create Referenz.
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 zum Erstellen von Fahrten
Die Fleet Engine API schreibt einen Logeintrag mithilfe von Logs der Google Cloud Platform, wenn ein
an den Endpunkt CreateTrip
empfangen wird. Der Logeintrag enthält
Informationen zu den Werten in der CreateTrip
-Anfrage. Wenn der Anruf
erfolgreich ist, enthält sie auch Informationen zum zurückgegebenen Trip
.
ANLEITUNG: Fahrt aktualisieren
Die Entität „Trip“ enthält Felder, die die Nachverfolgung durch den Dienst und für
Meldung des Fahrtverlaufs durch das Driver SDK und
Consumer SDK: Verwenden Sie UpdateTripRequest
, um die Attribute zu aktualisieren.
angezeigt. Dadurch werden die Trip-Felder entsprechend 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 nachdem das Fahrzeug einem Fahrt.
- Änderungen an Abhol-, Absetz- oder Wegpunkten.
Die Fleet Engine aktualisiert die folgenden Felder automatisch, wenn die Funktion zum Teilen von Kaufprozessen über das Driver SDK oder Consumer SDK:
- Routen
- ETA
- Verbleibende Strecke
- 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 Logs der Google Cloud Platform, wenn ein
an den Endpunkt UpdateTrip
empfangen wird. Der Logeintrag enthält
Informationen zu den Werten in der UpdateTrip
-Anfrage. Ist der Aufruf erfolgreich,
enthält sie auch Informationen zum zurückgegebenen Trip
.
ANLEITUNG: Reisen suchen
Fleet Engine unterstützt die Suche nach Fahrten. Wie bereits erwähnt, ist eine Reise
werden nach sieben Tagen automatisch gelöscht. SearchTrips
stellen den vollständigen Verlauf aller Fahrten bereit.
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
enthält das Feldvehicle_id
ist auf das betreffende Fahrzeug festgelegt undactive_trips_only
sollte auftrue
festgelegt sein.Anbieter und Fleet Engine-Status abgleichen: Der Anbieter kann Folgendes verwenden:
SearchTrips
, um sicherzustellen, dass der Trip-Status und der von Fleet Engine übereinstimmen. Das ist besonders wichtig für „TripStatus“. Wenn der Status einer Fahrt nicht korrekt aufCOMPLETE
oderCANCELED
eingestellt ist, wird das Fahrzeug ist inSearchVehicles
nicht enthalten.
Wenn Sie SearchTrips
auf diese Weise verwenden möchten, lassen Sie vehicle_id
leer und legen active_trips_only
fest
auf true
und minimum_staleness
auf eine Zeit festlegen, die länger als die meisten Fahrten ist.
Sie können beispielsweise eine Stunde verwenden. Die Ergebnisse umfassen Fahrten, die nicht
FULL oder CANCELED und wurden seit über einer Stunde nicht mehr aktualisiert. Der Anbieter
sollten diese Fahrten überprüfen, um sicherzustellen, dass ihr Status in der Fleet Engine
auf dem neuesten Stand sind.
Fehlerbehebung
Im Fall des Fehlers DEADLINE_EXCEEDED
lautet der Status der Fleet Engine
unbekannt. Der Anbieter sollte CreateTrip
noch einmal aufrufen, wodurch entweder ein Fehler zurückgegeben wird.
201 (ERSTELLT) oder 409 (CONFLICT). Im letzteren Fall war die vorherige Anfrage erfolgreich.
vor dem DEADLINE_EXCEEDED
. Weitere Informationen finden Sie in den Consumer API-Leitfäden.
zur Behandlung von Fahrtfehlern: Android
oder iOS.
Unterstützung 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 Trips angeben, die
das Fahrzeug in dieser geteilten Fahrt über Trip.vehicle_waypoints
, wenn du die
vehicle_id
für eine gemeinsame Reise (in einer CreateTrip
- oder UpdateTrip
-Anfrage).
Siehe vehicle_waypoints
für RPC
oder vehicleWaypoints
für REST.
Unterstützung mehrerer Ziele
Zwischenziel bestimmen
Die Felder intermediateDestinations
und intermediateDestinationIndex
in Fahrt (RPC | REST)
werden kombiniert, um das Ziel anzugeben.
Zwischenziel aktualisieren
Sie können die Zwischenziele über UpdateTrip
aktualisieren. Beim Aktualisieren
Zwischenziele erreichen, müssen Sie eine vollständige Liste der Zwischenziele angeben,
einschließlich der bereits besuchten, nicht nur die
hinzugefügt oder zu ändern ist.
Wenn intermediateDestinationIndex
auf einen Index nach der Position von
neu hinzugefügtes/geändertes Zwischenziel, neues/aktualisiertes Zwischenziel
wird nicht zur waypoints
des Fahrzeugs oder zur remainingWaypoints
der Reise hinzugefügt.
Der Grund ist, dass 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,
ein Zwischenziel verstrichen ist. Das Zwischenziel als Ziel
wird im Feld intermediateDestinationIndex
angegeben.
Wenn tripStatus
(RPC | REST) gleich ENROUTE_TO_INTERMEDIATE_DESTINATION ist, wird eine Zahl zwischen
[0..N-1] gibt an, welches Zwischenziel das Fahrzeug als Nächstes überquert.
Wenn tripStatus
ARRIVED_AT_INTERMEDIATE_DESTINATION ist, wird eine Zahl zwischen
[0..N-1] gibt an, an welchem Zwischenziel sich das Fahrzeug befindet.
Beispiel
Im folgenden Codebeispiel wird gezeigt, wie Sie den Status einer Fahrt so aktualisieren, dass sie unterwegs ist an ihr erstes Zwischenziel zu leiten, vorausgesetzt, Sie haben ein mehrere Ziele und die Fahrt hat ihren Abholpunkt überschritten.
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 der Fleet Engine API abonnieren
Die Fleet Engine API verwendet Google Cloud Pub/Sub Zum Veröffentlichen von Benachrichtigungen zu dem Thema, das vom Google Cloud-Nutzer erstellt wurde Projekt Pub/Sub ist für Fleet Engine in Ihrer Google Cloud nicht standardmäßig aktiviert Projekt arbeiten. Reichen Sie eine Supportanfrage ein 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“ sein.
Das Thema muss im selben Cloud-Projekt erstellt werden, das Fleet Engine aufruft APIs
Nachdem das Thema erstellt wurde, müssen Sie die Fleet Engine API gewähren
die Berechtigung zum Veröffentlichen
für das Thema. Klicke dafür auf das Thema,
und fügen Sie eine neue Berechtigung hinzu. Möglicherweise müssen Sie auf INFOFELD ANZEIGEN klicken, um den Berechtigungseditor zu öffnen.
Das Hauptkonto sollte geo-fleet-engine@system.gserviceaccount.com
sein
und die Rolle sollte Pub/Sub publisher
sein.
Um Ihr Cloud-Projekt für das Abonnieren von Benachrichtigungen einzurichten, folgen Sie dieser Anleitung
Die Fleet Engine API veröffentlicht jede Benachrichtigung in zwei verschiedenen Daten
Formate, protobuf
und
json
. Das Datenformat für jede Benachrichtigung wird in der
PubsubMessage-Attribute
mit dem Schlüssel data_format
und dem Wert protobuf
oder json
.
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"
}
}
}