Erste Schritte mit Fleet Engine

Mit der Fleet Engine On-demand Rides and Deliveries API können Sie Fahrten und den Fahrzeugstatus für Ihre Fahrt- und Bestellfortschrittsanwendungen verwalten. Er verarbeitet Transaktionen zwischen dem Driver SDK, dem Consumer SDK und Ihrem Back-End-Dienst, der mit der Fleet Engine über gRPC- oder REST-Aufrufe kommunizieren kann.

Voraussetzungen

Achten Sie bei der Entwicklung darauf, dass Sie das Cloud SDK (gcloud) installieren und bei Ihrem Projekt authentifiziert sind.

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

Fleet Engine kann Lognachrichten über empfangene API-Aufrufe in Google Cloud Platform-Logs schreiben. Eine Übersicht über das Lesen und Analysieren von Logs finden Sie in der Cloud Logging-Dokumentation.

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 Dokumentation zu Logging.

Clientbibliotheken

Wir veröffentlichen Client-Bibliotheken in verschiedenen gängigen Programmiersprachen. Diese Bibliotheken bieten eine bessere Entwicklungsumgebung gegenüber REST- oder gRPC-Rohdaten. 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

Sie können die Funktionen von „Trip and Order Progress“ über die Google Cloud Console konfigurieren. Für diese APIs und SDKs ist die Verwendung von JSON-Webtokens erforderlich, die mit Dienstkonten signiert wurden, die in der Cloud Console erstellt wurden.

Cloud-Projekt einrichten

Erstellen Sie zuerst das Projekt und dann die Dienstkonten, um Ihr Cloud-Projekt einzurichten.

So erstellen Sie Ihr Google Cloud-Projekt:

  1. Erstellen Sie mit der Google Cloud Console ein Google Cloud-Projekt.
  2. Aktivieren Sie im Dashboard „APIs und Dienste“ die Local Rides and Deliveries API.

Dienstkonten sind mit einer oder mehreren Rollen verknüpft. Sie werden zum Erstellen von JSON-Webtokens verwendet, die je nach Rollen unterschiedliche Berechtigungen gewähren. In der Regel können Sie mehrere Dienstkonten mit dem erforderlichen Mindestsatz an Rollen erstellen, um Missbrauch zu vermeiden.

Für Fahrten und Bestellfortschritte werden die folgenden Rollen verwendet:

RolleBeschreibung
Fleet Engine Consumer SDK-Nutzer

roles/fleetengine.consumerSdkUser		 Gewährt die Berechtigung zum Suchen nach Fahrzeugen sowie zum Abrufen von Informationen zu Fahrzeugen und Fahrten. Von einem Dienstkonto mit dieser Rolle erstellte Tokens werden in der Regel von den Mobilgeräten Ihrer Mitfahr- oder Lieferdienst-App verwendet.
Fleet Engine Driver SDK-Nutzer

roles/fleetengine.driverSdkUser		 Gewährt die Berechtigung zum Aktualisieren von Fahrzeugstandorten und -routen sowie zum Abrufen von Informationen zu Fahrzeugen und Fahrten. Von einem Dienstkonto mit dieser Rolle erstellte Tokens werden in der Regel von den Mobilgeräten Ihrer Mitfahrdienst- oder Lieferfahrer-App verwendet.
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.
FleetEngine Service-Superuser **(VERWORFEN)**

roles/fleetengine.serviceSuperUser		 Gewährt Berechtigungen für alle APIs für Fahrzeuge und Fahrten. Von einem Dienstkonto mit dieser Rolle erstellte Tokens werden normalerweise von Ihren Back-End-Servern verwendet. Diese Rolle wurde verworfen. Bevorzugen Sie stattdessen roles/fleetengine.ondemandAdmin.

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 das Consumer SDK basieren auf diesen Standardrollen.

Alternativ ist es möglich, benutzerdefinierte Rollen zu erstellen, mit denen ein beliebiger Satz von Berechtigungen gebündelt werden kann. Das Treiber- und das Consumer SDK zeigen Fehlermeldungen an, wenn eine erforderliche Berechtigung fehlt. Daher empfehlen wir dringend, den oben vorgestellten Standardsatz von Rollen zu verwenden und keine benutzerdefinierten Rollen zu verwenden.

Wenn Sie JWT-Tokens für nicht vertrauenswürdige Clients erstellen müssen, können Sie der Rolle „Service Account Token Creator“ Nutzer hinzufügen, um Tokens mit gcloud-Befehlszeilentools zu 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 für die Authentifizierung bei gcloud verwendet wird (gcloud auth list --format='value(account)').

Fleet Engine-Auth-Bibliothek

Fleet Engine verwendet JSON Web Tokens (JWTs), um den Zugriff auf Fleet Engine APIs einzuschränken. Die neue Fleet Engine Auth Library, die auf GitHub verfügbar ist, 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. die Identität eines Dienstkontos).
  • Hängt signierte Tokens an ausgehende Anfragen an, die von einem gRPC-Stub oder GAPIC-Client stammen.

JSON-Webtoken (JWT) für die Autorisierung erstellen

Wenn Sie die Fleet Engine Auth Library nicht verwenden, müssen JSON Web Tokens (JWTs) direkt in Ihrer Codebasis erstellt werden. Dazu müssen Sie sowohl ein tiefes Verständnis der JWTs als auch deren Beziehung zu Fleet Engine haben. Aus diesem Grund empfehlen wir UNBEDINGT, die Fleet Engine Auth Library zu nutzen.

In 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 abgerufen) und den Verschlüsselungsalgorithmus. Der Anforderungsbereich enthält Informationen wie die Erstellungszeit des Tokens, die Gültigkeitsdauer von Tokens, Dienste, auf die es den Zugriff beansprucht, und andere Autorisierungsinformationen zur Herunterstufung des Zugriffs, z. B. die Fahrzeug-ID.

Ein JWT-Header-Abschnitt enthält die folgenden Felder:

FieldBeschreibung
alg Der zu verwendende Algorithmus. „RS256“.
typ Der Tokentyp. „JWT“.
Kind Die private Schlüssel-ID Ihres Dienstkontos. Sie finden diesen Wert im Feld „private_key_id“ der JSON-Datei Ihres Dienstkontos. Achten Sie darauf, einen Schlüssel von einem Dienstkonto mit der richtigen Berechtigungsstufe zu verwenden.

Der Abschnitt für die JWT-Anforderungen enthält die folgenden Felder:

FieldBeschreibung
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 Sekunden, die seit dem 1. Januar 1970 um 00:00:00 UTC (UTC) vergangen sind. Planen Sie 10 Minuten für die Verzerrung ein. 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 Sekunden, die seit dem 1. Januar 1970 um 00:00:00 UTC (UTC) vergangen sind. Die Anfrage schlägt fehl, wenn der Zeitstempel mehr als eine Stunde in der Zukunft liegt.
authorization Kann je nach Anwendungsfall „vehicleid“ oder „tripid“ enthalten.

Das Erstellen eines JWT-Tokens bezieht sich auf das Signieren. Eine Anleitung und Codebeispiele zum Erstellen und Signieren des JWT findest du unter Dienstkontoautorisierung ohne OAuth. Sie können dann ein signiertes Token an gRPC-Aufrufe oder andere Methoden anhängen, die für den Zugriff auf Fleet Engine verwendet werden.

JWT-Anforderungen

Füge beim Erstellen der JWT-Nutzlast eine zusätzliche Anforderung im Autorisierungsabschnitt hinzu, wobei der Schlüssel vehicleid oder tripid auf den Wert der Fahrzeug-ID oder Fahrt-ID gesetzt ist, für die der Aufruf erfolgt.

Das Driver SDK verwendet immer die vehicleid-Anforderung, unabhängig davon, ob es sich um eine Fahrt oder ein Fahrzeug handelt. Das Fleet Engine-Back-End stellt sicher, dass das Fahrzeug der angeforderten Fahrt zugeordnet 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, um alle Fahrzeuge und Fahrten abzugleichen. Das JWT kann beide Tokens enthalten, auch wenn sie nicht erforderlich sind. Dies kann die Implementierung der Tokensignatur vereinfachen.

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

Das folgende Beispiel zeigt 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 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 für die Erstellung des Tokens, angegeben in Sekunden, die seit dem 1. Januar 1970 um 00:00:00 UTC vergangen sind. Planen Sie 10 Minuten für die Verzerrung ein. Wenn der Zeitstempel zu weit in der Vergangenheit oder Zukunft liegt, meldet der Server möglicherweise einen Fehler.
  • Verwenden Sie für das Feld exp den Zeitstempel für das Ablaufdatum des Tokens, angegeben in Sekunden seit dem 1. Januar 1970, 00:00:00 UTC. Der maximal zulässige Wert ist iat + 3.600.

Verwende beim Signieren des JWT, das an ein Mobilgerät übergeben werden soll, das Dienstkonto für die Rolle „Driver“ oder „Consumer SDK“. Andernfalls kann das Mobilgerät den Status ändern, den es nicht haben sollte.

Achte beim Signieren des JWT, das für privilegierte Aufrufe verwendet werden soll, ebenfalls darauf, das Dienstkonto mit der Rolle „Super User“ zu verwenden. Andernfalls schlägt der Vorgang fehl.

JWT zum Testen 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 ist die aktuelle Zeit in Sekunden seit der Epoche, die durch Ausführen von date +%s in Ihrem Terminal abgerufen werden kann. Das Attribut exp gibt die Ablaufzeit in Sekunden nach der Epoche an. Sie kann berechnet werden, indem zu iat 3.600 hinzugefügt wird. 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 Superuser-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 für die nächste Stunde gültig.

Sie können das Token jetzt testen, indem Sie einen curl-Befehl für den REST-Endpunkt zum Auflisten von Fahrzeugen 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 mit dem Dienstkonto zum Aufrufen der Fleet Engine APIs übereinstimmen muss) und einer Fahrzeug-ID des Mitfahrdienstes oder Lieferanbieters.

Ein Fahrzeug, das nach sieben Tagen nicht über UpdateVehicle aktualisiert wurde, wird automatisch gelöscht. CreateVehicle mit einem bereits vorhandenen Paar aus Anbieter-ID und Fahrzeug-ID aufzurufen, ist ein Fehler. Es gibt zwei Möglichkeiten, mit Fahrzeugen umzugehen, die nicht häufig aktualisiert werden: häufiges Aufrufen von CreateVehicle mit einem erwarteten Anbieter-ID-/Fahrzeug-ID-Paar und Verwerfen des Fehlers, wenn das Fahrzeug bereits vorhanden ist, oder CreateVehicle nach einem UpdateVehicle-Fehler zurückgegeben wird.NOT_FOUND

Updates zum Fahrzeugstandort

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

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

Fahrzeugtypen

Die Vehicle-Entität enthält das Pflichtfeld VehicleType, das eine Category-Enum enthält, die als AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE oder PEDESTRIAN angegeben werden kann. Der Fahrzeugtyp kann als Filterkriterium in SearchVehicles und ListVehicles verwendet werden.

Alle Routen für Fahrzeuge verwenden die entsprechende RouteTravelMode, wenn die Kategorie auf AUTO, TWO_WHEELER, BICYCLE oder PEDESTRIAN festgelegt ist. Wenn die Kategorie auf TAXI oder TRUCK festgelegt ist, wird das Routing wie der Modus AUTO behandelt.

Fahrzeugattribute

Die Entität „Vehicle“ enthält ein wiederkehrendes Feld von VehicleAttribute. Diese Attribute werden nicht von Fleet Engine interpretiert. Die SearchVehicles API enthält ein Feld, über das festgelegt werden muss, dass die übereinstimmende Vehicles alle enthaltenen Attribute enthalten muss, die auf den angegebenen Wert festgelegt sind.

Beachten Sie, dass das Attributfeld in der Vehicle-Nachricht zusätzlich zu einigen anderen unterstützten Feldern verwendet wird, 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 den Fahrten in der Reihenfolge, in der das Fahrzeug sie erreicht. Fleet Engine berechnet dieses Feld, wenn dem Fahrzeug Fahrten zugewiesen werden, 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 Dienste des Mitfahrdienstes oder Lieferanbieters dafür verantwortlich, Fahrtanfragen mit Fahrzeugen abzugleichen. Der Dienst kann die Fahrzeugattribute verwenden, um ein Fahrzeug in eine größere Anzahl von Suchanfragen einzubeziehen. Beispielsweise kann der Anbieter eine Gruppe von Attributen implementieren, die den Stufen der Vergünstigungen oder Fähigkeiten eines Fahrzeugs entsprechen. Drei Ebenen könnten 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 geeignet sein. Wenn Fleet Engine eine Anfrage für eine Fahrt erhält, für die Berechtigungen der Stufe „Silber“ erforderlich sind, wird dieses Fahrzeug in die Suche einbezogen. Wenn Attribute auf diese Weise verwendet werden, sind auch Fahrzeuge mit einer Vielzahl von Funktionen eingeschlossen.

Es gibt zwei Möglichkeiten, Fahrzeugattribute zu aktualisieren. Eine davon ist die UpdateVehicle API. Bei Verwendung dieser API 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 zu aktualisierenden Attribute benötigt. Für die in der Anfrage enthaltenen Attribute wird der neue Wert festgelegt oder hinzugefügt. Nicht angegebene 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 dem CreateVehicleRequest, um ein Fahrzeug zu erstellen.

Die provider_id von Vehicle muss die Projekt-ID (z.B. my-on-demand-Projekt) des Google Cloud-Projekts sein, das die Dienstkonten enthält, die zum Aufrufen von Fleet Engine verwendet werden. Hinweis: Obwohl mehrere Dienstkonten für denselben Mitfahrdienst oder Lieferanbieter auf die Fleet Engine zugreifen können, unterstützt Fleet Engine derzeit keine Dienstkonten von mehreren Google Cloud-Projekten, die auf dieselbe Vehicles zugreifen.

Das Vehicle kann im Status OFFLINE oder ONLINE erstellt werden. Eine erstellte ONLINE kann sofort als Antwort auf SearchVehicles-Abfragen zurückgegeben werden.

Ein anfänglicher last_location kann im CreateVehicle-Aufruf enthalten sein. Obwohl es zulässig ist, sollte ein Vehicle im Status ONLINE nicht ohne last_location erstellt werden.

Weitere Informationen zum Feld „Fahrzeugtyp“ finden Sie unter Fahrzeugtypen.

Weitere Informationen zum Attributfeld finden Sie unter Fahrzeugattribute.

Der von CreateVehicle zurückgegebene Wert ist die erstellte Vehicle-Entität.

Beispiel

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "OFFLINE",
    "supportedTripTypes": ["EXCLUSIVE"],
    "maximumCapacity": 4,
    "vehicleType": {"category": "AUTO"},
    "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

Weitere Informationen finden Sie in der Referenz zu providers.vehicles.create.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)  // Initial state
    .addSupportedTripTypes(TripType.EXCLUSIVE)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .addAttributes(VehicleAttribute.newBuilder()
        .setKey("on_trip").setValue("false"))  // Opaque to the Fleet Engine
    // Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
    // matching while even if it is on a trip.  By default this is disabled.
    .build();

CreateVehicleRequest createVehicleRequest =
    CreateVehicleRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setVehicleId("vid-8241890")  // Vehicle ID assigned by Rideshare or Delivery Provider
        .setVehicle(vehicle)  // Initial state
        .build();

// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided.  When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.

try {
  Vehicle createdVehicle =
      vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle created successfully.

Google Cloud Platform-Logs zum Erstellen von Fahrzeugen

Die Fleet Engine API schreibt einen Logeintrag über Google Cloud Platform-Logs, wenn ein Aufruf an den Endpunkt CreateVehicle eingeht. Der Logeintrag enthält Informationen zu den Werten in der CreateVehicle-Anfrage. Wenn der Aufruf erfolgreich ist, enthält er auch Informationen zum zurückgegebenen Vehicle-Objekt.

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 ein neues Fahrzeug erstellt wird. Um diese Benachrichtigungen zu erhalten, gehen Sie wie hier beschrieben vor.

ANLEITUNG: Fahrzeugstandort aktualisieren

Wenn Sie das Driver SDK nicht zum Aktualisieren des Fahrzeugstandorts verwenden, können Sie Fleet Engine direkt mit dem Standort des Fahrzeugs aufrufen. Für jedes aktive Fahrzeug erwartet Flleet Engine mindestens einmal pro Minute und höchstens einmal alle 5 Sekunden eine Standortaktualisierung. Für diese Updates sind nur Nutzerberechtigungen für das Fleet Engine Driver SDK erforderlich.

Beispiel

shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
}
EOM

Siehe Referenz zu providers.vehicles.update.

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setLastLocation(VehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("last_location"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

ANLEITUNG: Andere Fahrzeugfelder aktualisieren

Andere Attribute des Fahrzeugstatus werden seltener aktualisiert als Positionsupdates. Für die Aktualisierung anderer Attribute als last_location sind Superuser-Berechtigungen für Fleet Engine erforderlich.

UpdateVehicleRequest enthält einen update_mask, der 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 geschrieben werden, die beibehalten werden sollen. Es ist nicht möglich, einfach den Wert eines Schlüssel/Wert-Paars in einem UpdateVehicle-Aufruf zu aktualisieren. Zum Aktualisieren der Werte bestimmter Attribute kann die UpdateVehicleAttributes API verwendet werden.

Beispiel

In diesem Beispiel wird back_to_back aktiviert.

shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "on_trip", "value": "true"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

Siehe Referenz zu providers.vehicles.update.

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_state")
        .addPaths("attributes")
        .addPaths("back_to_back_enabled"))
    .build();

// Attributes and vehicle state are being updated, so both are
// included in the field mask.  Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

Google Cloud Platform-Logs für Fahrzeugupdates

Die Fleet Engine API schreibt einen Logeintrag über Google Cloud Platform-Logs, wenn ein Aufruf an den Endpunkt UpdateVehicle eingeht. Der Logeintrag enthält Informationen zu den Werten in der UpdateVehicle-Anfrage. Wenn der Aufruf erfolgreich ist, enthält er auch Informationen zum zurückgegebenen Vehicle-Objekt.

shell

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

Cloud Pub/Sub-Benachrichtigungen für Fahrzeugupdates

Die Fleet Engine API veröffentlicht eine Benachrichtigung über Cloud Pub/Sub, wenn ein vorhandenes Fahrzeug aktualisiert wird. Um diese Benachrichtigungen zu erhalten, gehen Sie wie hier beschrieben vor.

ANLEITUNG: Fahrzeuge suchen

Fleet Engine unterstützt die Suche nach Fahrzeugen. Mit der SearchVehicles API kannst du freie Fahrer in der Nähe finden, die sich am besten für eine Aufgabe wie Fahrten oder Lieferanfragen eignen. Die SearchVehicles API gibt eine nach Rang sortierte Liste von Fahrern zurück, die die Aufgabenattribute mit den Fahrzeugattributen in Ihrem Fuhrpark abgeglichen haben. Weitere Informationen finden Sie unter Fahrer in der Nähe finden.

Beispiel

Bei der Suche nach verfügbaren Fahrzeugen werden Fahrzeuge auf aktiven Fahrten standardmäßig von Fleet Engine ausgeschlossen. Die Dienste des Mitfahrdienstes oder Lieferanbieters müssen sie explizit in Suchanfragen angeben. Das folgende Beispiel zeigt, wie diese Fahrzeuge in eine Suche nach Fahrzeugen einbezogen werden, die einer Fahrt von der Grand Indonesia East Mall zum Balai Sidang Jakarta Convention Center entsprechen.

shell

Aktualisieren Sie zuerst den Standort des in den vorherigen Schritten erstellten Fahrzeugs, damit es infrage kommt. In der Praxis würde dies über das Driver SDK erfolgen, das auf einem Android- oder iOS-Gerät im Fahrzeug ausgeführt wird.

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
    "location": {
      "latitude": "-6.195139",
      "longitude": "106.820826"
    }
  },
  "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

Die Suche sollte mindestens dieses Fahrzeug 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 in der Referenz zu providers.vehicles.search.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jakarta Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);

  // Search results: Each vehicle match contains a vehicle entity and information
  // about the distance and ETA to the pickup point and dropoff point.
  List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Anfrage zum Filtern von Fahrzeugen

SearchVehicles und ListVehicles unterstützen das Filtern von 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, z. B. minimum_capacity oder vehicle_types in SearchVehiclesRequest.

ANLEITUNG: Fahrzeuge auflisten

SearchVehicles ist dafür optimiert, eine kleine Anzahl von Fahrzeugen in einer bestimmten Reihenfolge sehr schnell zu finden. Sie wird hauptsächlich verwendet, um Fahrer in der Nähe zu finden, die für eine bestimmte Aufgabe am besten geeignet sind. Manchmal möchten Sie jedoch alle Fahrzeuge ermitteln, die bestimmte Kriterien erfüllen, auch wenn das Durchblättern der Ergebnisse erforderlich ist. 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 einige Anforderungen erfüllen.

Informationen zum Filtern von Fahrzeugattributen finden Sie unter Anfrage zum Filtern von Fahrzeugen.

Beispiel

In diesem Beispiel werden vehicle_type und Attribute mithilfe des Strings filter gefiltert.

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
}
EOM

Siehe Referenz zu providers.vehicles.list.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
    .setParent(parent)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  ListVehiclesResponse listVehiclesResponse =
      vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Fahrten und ihr Lebenszyklus

Die Trip API und der Lebenszyklus ähneln der Vehicle API und dem Lebenszyklus. Der Mitfahrdienst ist dafür verantwortlich, Fahrten über die Fleet Engine-Oberflächen zu erstellen. Fleet Engine bietet sowohl einen RPC-Dienst ( TripService) als auch die REST-Ressourcen provider.trips. Über diese Oberflächen können Trip-Entitäten erstellt und Informationen angefordert sowie Such- und Aktualisierungsfunktionen genutzt werden.

Eine Trip hat ein Statusfeld, um ihren Fortschritt im Lebenszyklus zu verfolgen. Die Werte werden von NEW nach COMPLETE plus CANCELED und UNKNOWN_TRIP_STATUS verschoben. 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 mit einem dieser Status aktualisieren. Wenn Ihr Service eine Fahrt erstellt, legt der Motor den Status auf NEW fest. Ein vehicle_id ist optional. Wie bei Fahrzeugen werden Fahrten nach sieben Tagen ohne Aktualisierung automatisch gelöscht. Wenn der Dienst versucht, eine Fahrt mit einer bereits vorhandenen ID zu erstellen, wird ein Fehler zurückgegeben. Eine Fahrt gilt als „aktiv“, wenn sie sich in einem anderen Status als COMPLETE oder CANCELED befindet. Diese Unterscheidung ist im Feld active_trips der Entität „Fahrzeug“ und SearchTripsRequest wichtig.

Der Dienst kann die vehicle_id einer Fahrt nur ändern, wenn die Fahrt aktiv ist. Das ist beispielsweise der Fall, wenn ein Fahrer eine Fahrt auf der Route annulliert und die Fahrt einem anderen Fahrzeug zugewiesen wird.

Der Status ist wichtig, wenn mehrere Fahrten direkt nacheinander implementiert werden. So kann der Anbieter einem Fahrzeug, das sich in einer aktiven Fahrt befindet, eine neue Fahrt zuweisen. Der Code zum Erstellen einer zweiteiligen Fahrt ist derselbe wie bei einer einzelnen Fahrt und verwendet dieselbe Fahrzeug-ID. Fleet Engine fügt den Wegpunkten des Fahrzeugs den Start- und Zielort der neuen Fahrt hinzu. Weitere Informationen 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 vor dem letzten Ausstiegspunkt in dieser Reihenfolge zurücklegen muss. Zur Berechnung werden die verbleibenden Wegpunkte des Fahrzeugs herangezogen. In den Anwendungsfällen „Aufeinanderfolgende Fahrten“ und „Fahrgemeinschaften“ enthält diese Liste Wegpunkte von anderen Fahrten, die vor dieser Fahrt durchlaufen werden. Wegpunkte nach dieser Fahrt sind jedoch nicht enthalten. Der Wegpunkt in der Liste kann an TripId und WaypointType identifiziert werden.

Die Beziehung zwischen Fahrtstatus und verbleibenden Wegpunkten des Fahrzeugs

Die verbleibenden Wegpunkte (RPC | REST) des Fahrzeugs werden aktualisiert, wenn Fleet Engine eine Anfrage zur Änderung des Fahrtstatus erhält. Der vorherige Wegpunkt wird aus der Liste der verbleibenden Wegpunkte des Fahrzeugs entfernt, wenn tripStatus(RPC | REST) von einem anderen Status zu ENROUTE_TO_XXX geändert wird. Wird der Fahrtstatus also von ENROUTE_TO_PICKUP in ARRIVED_AT_PICKUP geändert, befindet sich der Abholpunkt weiterhin in der Liste der verbleibenden Wegpunkte des Fahrzeugs. Wird der Fahrtstatus jedoch in ENROUTE_TO_INTERMEDIATE_DESTINATION oder ENROUTE_TO_DROPOFF geändert, werden die verbleibenden Wegpunkte vom Fahrzeug entfernt.

Das Gleiche gilt für ARRIVED_AT_INTERMEDIATE_DESTINATION und ENROUTE_TO_INTERMDEDIATE_DESTINATION. Bei ARRIVED_AT_INTERMEDIATE_DESTINATION wird das aktuelle Zwischenziel erst dann aus der verbleibenden Wegpunktliste des Fahrzeugs entfernt, wenn das Fahrzeug meldet, dass es zum nächsten Wegpunkt führt.

Wenn der Fahrtstatus in COMPLETED geändert wird, sind in der verbleibenden Wegpunktliste des Fahrzeugs keine Wegpunkte von dieser Fahrt zu sehen.

ANLEITUNG: Eine Reise erstellen

Es muss eine Trip-Entität erstellt werden, damit jede Fahrtanfrage verfolgt und den Fahrzeugen in der Flotte zugeordnet 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, der die Anbieter-ID enthält, die beim Erstellen des Google Cloud-Projekts erstellt wurde.
  • trip_id: ein vom Mitfahrdienst-Anbieter erstellter String
  • trip: Container mit grundlegenden Metadaten, die die Fahrt beschreiben.
    • trip_type: Aufzählung, die angibt, ob bei der Fahrt möglicherweise andere Fahrgäste mit einem anderen Start- und Zielort im selben Fahrzeug (SHARED) oder nur mit einer Partei (EXCLUSIVE) dabei sind.
    • pickup_point: TerminalLocation, das den Startpunkt der Fahrt darstellt. Weitere Informationen finden Sie in der RPC-Referenz oder der REST-Referenz.

Wenn Sie eine Fahrt erstellen, können Sie number_of_passengers, dropoff_point und vehicle_id angeben. Obwohl diese Felder nicht erforderlich sind, bleiben sie erhalten, wenn Sie sie angeben. Alle anderen Trip-Felder 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 exklusiv für zwei Passagiere. Der provider_id von Trip muss mit der Projekt-ID übereinstimmen. In diesem Beispiel hat der Mitfahrdienst das Google Cloud-Projekt project-id erstellt. Dieses Projekt muss die Dienstkonten haben, die zum Aufrufen der Fleet Engine verwendet werden. Der Status der Fahrt ist „NEW“.

Später, nachdem die Fahrt einem Fahrzeug zugeordnet wurde, kann der Dienst UpdateTrip aufrufen und vehicle_id ändern, wenn die Fahrt einem Fahrzeug zugewiesen wird.

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "tripType": "EXCLUSIVE",
  "numberOfPassengers": 2,
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  }
}
EOM

Siehe Referenz zu providers.trips.create.

Java

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
    .setPickupPoint(                 // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    // Provide the number of passengers if available.
    .setNumberOfPassengers(2)
    // Provide the drop-off point if available.
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
    .build();

CreateTripRequest createTripRequest =
    CreateTripRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setTripId("tid-1f97")  // Trip ID assigned by the Provider
        .setTrip(trip)              // Initial state
        .build();

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

try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Google Cloud Platform-Logs zum Erstellen von Fahrten

Die Fleet Engine API schreibt einen Logeintrag mithilfe von Google Cloud Platform-Logs, wenn ein Aufruf an den Endpunkt CreateTrip eingeht. Der Logeintrag enthält Informationen zu den Werten in der CreateTrip-Anfrage. Wenn der Aufruf erfolgreich ist, enthält er auch Informationen zum zurückgegebenen Trip.

ANLEITUNG: Fahrt aktualisieren

Die Entität „Trip“ enthält Felder, die die Verfolgung durch den Dienst und die Meldung des Fahrtverlaufs durch das Driver SDK und das Consumer SDK ermöglichen. Verwenden Sie zum Aktualisieren der Attribute die Nachricht UpdateTripRequest. 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 einer Fahrt zugeordnet wurde.
  • Änderungen an Abhol-, Absetz- oder Wegpunkten.

Fleet Engine aktualisiert automatisch die folgenden Felder, wenn die Prozessfreigabe über das Driver SDK oder Consumer SDK verwendet wird:

  • Routes
  • Voraussichtliche Ankunft
  • 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 Google Cloud Platform-Logs, wenn ein Aufruf an den Endpunkt UpdateTrip eingeht. Der Logeintrag enthält Informationen zu den Werten in der UpdateTrip-Anfrage. Wenn der Aufruf erfolgreich ist, sind auch Informationen zum zurückgegebenen Trip enthalten.

ANLEITUNG: Reisen suchen

Fleet Engine unterstützt die Suche nach Fahrten. Wie bereits erwähnt, wird ein Trip 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. In SearchTripsRequest ist vehicle_id auf das infrage kommende Fahrzeug und active_trips_only auf true festgelegt.

  • Anbieter und Fleet Engine-Status abgleichen: Der Anbieter kann mithilfe von SearchTrips dafür sorgen, dass der Trip-Status und der von Fleet Engine übereinstimmen. Das ist besonders wichtig für „TripStatus“. Wenn der Status einer Fahrt, die einem Fahrzeug zugewiesen ist, nicht korrekt auf COMPLETE oder CANCELED festgelegt ist, wird das Fahrzeug in SearchVehicles nicht berücksichtigt.

Wenn Sie SearchTrips auf diese Weise verwenden möchten, lassen Sie vehicle_id leer, legen Sie active_trips_only auf true fest und geben Sie für minimum_staleness eine Zeit an, die länger als die meisten Fahrten ist. Sie können beispielsweise eine Stunde verwenden. Die Ergebnisse umfassen Trips, die weder COMPLETE noch CANCELED sind und seit über einer Stunde nicht mehr aktualisiert wurden. Der Anbieter sollte diese Fahrten prüfen, um dafür zu sorgen, dass ihr Status in Fleet Engine ordnungsgemäß aktualisiert wird.

Fehlerbehebung

Im Fall des Fehlers DEADLINE_EXCEEDED ist der Status von Fleet Engine unbekannt. Der Anbieter sollte CreateTrip noch einmal aufrufen, wodurch entweder 201 (CREATED) oder 409 (CONFLICT) zurückgegeben wird. Im letzteren Fall war die vorherige Anfrage vor DEADLINE_EXCEEDED erfolgreich. Weitere Informationen zum Umgang mit Fahrtfehlern finden Sie in den Consumer API-Leitfäden für Android und 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 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 bestimmen

Die Felder intermediateDestinations und Feld intermediateDestinationIndex in „Trip“ (RPC | REST) werden zur Angabe des Ziels kombiniert.

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 Ziele, die besucht wurden, und nicht nur die neu hinzugefügten oder zu ändernden Ziele. Wenn der intermediateDestinationIndex auf einen Index nach der Position eines neu hinzugefügten/geänderten Zwischenziels verweist, wird das neue/aktualisierte Zwischenziel nicht der waypoints des Fahrzeugs oder dem remainingWaypoints der Fahrt hinzugefügt. Dies liegt daran, 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 übergeben wurde. Das Ziel-Zwischenziel wird über das Feld intermediateDestinationIndex angegeben. Wenn tripStatus (RPC | REST) den Wert ENROUTE_TO_INTERMEDIATE_DESTINATION hat, gibt eine Zahl zwischen [0..N-1] an, welches Zwischenziel das Fahrzeug als Nächstes überquert. 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 Sie den Status einer Fahrt aktualisieren, um zum ersten Zwischenziel zu gelangen. Dabei wird davon ausgegangen, dass Sie eine Fahrt mit mehreren Zielen erstellt haben und die Fahrt ihren Abholpunkt passiert hat.

Java

static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to update.
Trip trip = Trip.newBuilder()
    // Trip status cannot go back to a previous status once it is passed
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
    // Enrouting to the first intermediate destination.
    .setIntermediateDestinationIndex(0)
    // intermediate_destinations_version MUST be provided to ensure you
    // have the same picture on intermediate destinations list as FleetEngine has.
    .setIntermediateDestinationsVersion(
        trip.getIntermediateDestinationsVersion())
    .build();

// Trip update request
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(
            FieldMask.newBuilder()
                .addPaths("trip_status")
                .addPaths("intermediate_destination_index")
                // intermediate_destinations_version must not be in the
                // update mask.
                .build())
        .build();

// Error handling
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:  // Trip does not exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid, or the
                                // intermediate_destinations_version
                                // doesn’t match FleetEngine’s.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

ANLEITUNG: Benachrichtigungen der Fleet Engine API abonnieren

Die Fleet Engine API verwendet Google Cloud Pub/Sub, um Benachrichtigungen zu dem Thema zu veröffentlichen, das vom Google Cloud-Projekt für Nutzer erstellt wurde. Pub/Sub ist in Ihrem Google Cloud-Projekt nicht standardmäßig für Fleet Engine aktiviert. 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 in dem Cloud-Projekt erstellt werden, das 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 gerade erstellte 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 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 angegeben. Der Schlüssel ist dabei data_format und der 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;
  }
}

JavaScript Object Notation

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