Erste Schritte mit Fleet Engine

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.

gcloud auth login

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.

gcloud --project=project-id services enable fleetengine.googleapis.com

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:

1. Erstellen Sie mit der Google Cloud Console ein Google Cloud-Projekt.
2. 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:

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:

Ein Bereich für JWT-Anforderungen enthält die folgenden Felder:

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 Feld private_key_id der JSON-Datei Ihres Dienstkontos.
• Geben Sie in den Feldern iss und sub die E-Mail-Adresse Ihres Dienstkontos an. Sie finden diesen Wert im Feld client_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 ist iat + 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:

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

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

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

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.

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'

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

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

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.

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

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.

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.

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

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

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.

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

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;
}

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.

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

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 wird vehicle_id auf das infrage kommende Fahrzeug festgelegt und active_trips_only auf true 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 auf COMPLETE oder CANCELED festgelegt ist, ist das Fahrzeug nicht in SearchVehicles 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.

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;
}

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

• Fahrzeug
• FieldMask

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"
    }
  }
}