Erste Schritte mit Fleet Engine

Mit der Fleet Engine On-demand Rides and Deliveries API können Sie Fahrten verwalten und Fahrzeugstatus für Ihre App „Reise- und Bestellfortschritt“. Es verarbeitet Transaktionen zwischen dem Driver SDK, dem Consumer SDK und Ihrem Back-End-Dienst, der mit der Fleet Engine kommunizieren kann, indem er entweder gRPC oder REST-Aufrufe.

Vorbereitung

Achten Sie bei der Entwicklung darauf, dass Sie die Cloud SDK (gcloud) und sind für für Ihr Projekt.

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 entsprechend konfiguriert sind.

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

Logging

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

Logging ist möglicherweise für Projekte, die vor erstellt wurden, nicht standardmäßig aktiviert 10. Februar 2022. Weitere Informationen finden Sie in der Logging-Dokumentation .

Clientbibliotheken

Wir veröffentlichen Client-Bibliotheken in verschiedenen gängigen Programmiersprachen. Diese Bibliotheken ermöglichen eine bessere Entwicklung im Vergleich zu REST oder gRPC. Wie Sie Clientbibliotheken für Ihre Serveranwendung abrufen, Siehe Clientbibliotheken.

Die Java-Beispiele in dieser Dokumentation setzen voraus, dass Sie mit gRPC vertraut sind.

Authentifizierung und Autorisierung

Sie können die Funktionen für Fahrten und Bestellfortschritte bis in der Google Cloud Console. Für diese APIs und SDKs ist die Verwendung von JSON Web Tokens erforderlich, die mit Dienstkonten signiert, die aus Cloud Console

Cloud-Projekt einrichten

Um Ihr Cloud-Projekt einzurichten, müssen Sie es zuerst erstellen und dann Dienstkonten erstellen.

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 dienen dazu, JSON Web Tokens, die unterschiedliche Berechtigungen gewähren, je nachdem, Rollen. Um Missbrauch zu vermeiden, können Sie in der Regel mehrere Dienstkonten mit jeweils dem erforderlichen Mindestsatz an Rollen.

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

Erstellen Sie beispielsweise ein Dienstkonto für jede der drei Rollen und weisen Sie ihre jeweilige Rolle.

gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.consumerSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.driverSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-su
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.serviceSuperUser

Die Treiber und das Consumer SDK basieren auf diesen Standardrollen.

Alternativ ist es möglich, benutzerdefinierte Rollen zu erstellen, Beliebige Reihe von Berechtigungen, die zu gebündelt werden können. Das Treiber- und das Consumer-SDK zeigen Fehlermeldungen an, wenn ein erforderliche Berechtigung fehlt. Daher empfehlen wir dringend, Dabei werden die oben beschriebenen Standardrollen und keine benutzerdefinierten Rollen verwendet.

Wenn Sie JWT-Tokens für nicht vertrauenswürdige Clients erstellen müssen, fügen Sie Nutzer mit der Rolle „Service Account Token Creator“ können Tokens erstellen gcloud-Befehlszeilentools verwenden.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Dabei ist my-user@example.com die E-Mail-Adresse, die für Folgendes verwendet wird: Authentifizieren Sie sich mit gcloud (gcloud auth list --format='value(account)').

Fleet Engine-Auth-Bibliothek

Fleet Engine verwendet JSON Web Tokens (JWTs), um den Zugriff auf Fleet Engine APIs Die neue Fleet Engine-Auth-Bibliothek auf GitHub verfügbar, vereinfacht das Erstellen von Fleet Engine-JWTs und signiert sie sicher.

Die Bibliothek bietet folgende Vorteile:

• Vereinfacht das Erstellen von Fleet Engine-Tokens.
• Stellt Tokensignaturmechanismen bereit, die keine Anmeldedatendateien verwenden (z. B. Identitätsdiebstahl eines Dienstkontos)
• Hängt signierte Tokens an ausgehende Anfragen an, die von einem gRPC-Stub oder GAPIC-Client.

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

Wenn Sie die Fleet Engine Auth Library nicht verwenden, müssen die JSON Web Tokens (JWTs) mit die direkt in Ihrer Codebasis erstellt wurden. Dazu benötigen Sie sowohl eine von JWTs und deren Beziehung zu Fleet Engine. Aus diesem Grund Wir empfehlen UNBEDINGT, die Fleet Engine Auth Library zu nutzen.

In Fleet Engine bieten JSON Web Tokens (JWTs) eine kurzlebige Authentifizierung und sicherzustellen, dass Geräte nur Fahrzeuge, Fahrten oder Aufgaben für die sie autorisiert sind. JWTs enthalten einen Header und einen Anforderungsabschnitt. Der Header-Abschnitt enthält Informationen wie die den von Dienstkonten abgerufenen privaten Schlüssel und die Verschlüsselung Algorithmus. Der Abschnitt zum Anspruch enthält Informationen wie die Erstellungszeit des Tokens, Gültigkeitsdauer des Tokens, Dienste, die es ist das Behaupten des Zugriffs auf und andere Autorisierungsinformationen Zugriff z. B. die Fahrzeug-ID.

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

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

Das Erstellen eines JWT-Tokens bezieht sich auf das Signieren. Anleitungen und Codebeispiele zum Erstellen und Signieren des JWT, siehe Dienstkontoautorisierung ohne OAuth: Sie können dann ein signiertes Token an gRPC-Aufrufe oder andere verwendete Methoden anhängen. um auf Fleet Engine zuzugreifen.

JWT-Anforderungen

Fügen Sie beim Erstellen der JWT-Nutzlast in der Autorisierung eine zusätzliche Anforderung hinzu. mit dem Schlüssel vehicleid oder tripid, der auf den Wert des Fahrzeug-ID oder Fahrt-ID, für die der Anruf getätigt wird.

Das Driver SDK verwendet immer die vehicleid-Anforderung, unabhängig davon, ob auf eine Reise oder ein Fahrzeug. Das Fleet Engine-Back-End sorgt dafür, dass das Fahrzeug mit der angeforderten Fahrt verknüpft ist, bevor die Änderung vorgenommen wird.

Das Consumer SDK verwendet immer die tripid-Anforderung.

Der Mitfahrdienst oder Lieferdienst muss vehicleid oder tripid mit einem „*“ verwenden bis Übereinstimmung mit allen Fahrzeugen und Fahrten. Das JWT kann sowohl Tokens auch wenn nicht erforderlich, was die Implementierung der Tokensignatur vereinfachen kann.

JWT-Anwendungsfälle

Im Folgenden sehen Sie ein Beispieltoken für einen Anbieterserver:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
  "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Hier sehen Sie ein Beispieltoken für die Nutzer-App:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

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 den privaten Schlüssel Ihres Dienstkontos an ID. Sie finden diesen Wert im Feld private_key_id Ihres Dienstes JSON-Datei des Kontos.
• Geben Sie in den Feldern iss und sub die E-Mail-Adresse Ihres Dienstkontos an. Sie finden diesen Wert in Ihrem Dienstkonto im Feld client_email. JSON-Datei.
• Geben Sie für das Feld aud https://SERVICE_NAME/ an.
• Geben Sie für das Feld iat den Zeitstempel der Erstellung des Tokens an. angegeben als verstrichene Sekunden seit dem 1. Januar 1970 00:00:00 UTC. Planen Sie 10 Minuten für die Verzerrung ein. Wenn der Zeitstempel zu weit in der Vergangenheit liegt, oder in Zukunft, meldet der Server einen Fehler.
• Geben Sie im Feld exp den Zeitstempel für das Ablaufdatum des Tokens an. angegeben als Sekunden seit dem 1. Januar 1970 00:00:00 UTC. Das Maximum Der zulässige Wert ist iat + 3.600.

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

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

JWT zum Testen generieren

Das Generieren von Tokens über das Terminal kann beim Testen hilfreich sein.

Um diese Schritte ausführen zu können, Konto muss die Rolle „Ersteller von Dienstkonto-Tokens“ haben:

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Erstellen Sie eine neue Datei mit dem Namen unsigned_token.json und dem folgenden Inhalt. Das iat ist die aktuelle Zeit in Sekunden seit der Epoche. Der Wert kann abgerufen, indem date +%s in deinem Terminal ausgeführt wird. Das Attribut exp ist der die Ablaufzeit in Sekunden nach der Epoche und kann folgendermaßen berechnet werden: iat wird 3.600 hinzugefügt. Die Ablaufzeit darf nicht mehr als eine Stunde im in der Zukunft.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "sub": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Führen Sie dann den folgenden gcloud-Befehl aus, um das Token im Namen Ihres Super- Nutzerdienstkonto:

gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt

Ein signiertes Base64-codiertes JWT sollte jetzt in der Datei gespeichert sein signed_token.jwt Das Token ist für die nächste Stunde gültig.

Sie können das Token jetzt testen, indem Sie den Befehl curl für die Fahrzeugliste ausführen. REST-Endpunkt:

curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"

Fahrzeuge und ihr Lebenszyklus

Das Fahrzeug ist die Entität, die ein Fahrer/Fahrzeug-Paar darstellt. Derzeit Ein Fahrer und ein Fahrzeug können nicht separat verfolgt werden. Mitfahrdienst oder Lieferdienst ein Fahrzeug mit einer Anbieter-ID (muss mit der ID Projekt-ID des Google Cloud-Projekts, das das Dienstkonto enthält zum Aufrufen der Fleet Engine APIs) und einer Fahrzeug-ID eines Mitfahrdienstes oder eines Zustellers verwendet wird.

Ein Fahrzeug, das nach sieben Tagen noch nicht über UpdateVehicle aktualisiert wurde, automatisch gelöscht und die zugehörigen Fahrten, falls vorhanden, werden als nicht zugewiesen. Die empfohlene Vorgehensweise, damit ein Fahrzeug verfügbar bleibt in Fleet Engine ist die regelmäßige Aktualisierung des Standorts. Aktualisierungen für die meisten anderen Felder in der Entität Vehicle wird ihre Lebensdauer ebenfalls verlängert, sofern dass sich der neue Feldwert von dem vorhandenen unterscheidet.

HINWEIS: Einige Felder in der Entität Vehicle wie device_settings dienen ausschließlich zur Fehlerbehebung. Informationen, die nicht von Fleet Engine gespeichert werden. Das Aktualisieren die Lebensdauer der Vehicle-Entität verlängern.

Fehler beim Aufrufen von CreateVehicle mit einer Paar „Anbieter-ID/Fahrzeug-ID“ ist bereits vorhanden. Der Fall von Fahrzeugen, nicht regelmäßig aktualisiert werden, kann dies zwei Ursachen haben: häufige Anrufe CreateVehicle mit einem erwarteten Paar aus Anbieter-ID und Fahrzeug-ID und wird verworfen den Fehler, wenn das Fahrzeug bereits vorhanden ist; oder CreateVehicle nach einer UpdateVehicle gibt den Fehler NOT_FOUND zurück.

Updates zum Fahrzeugstandort

Die beste Leistung erzielen Sie, wenn Sie Fleet Engine mit einem Fahrzeugstrom versorgen. Standortaktualisierungen. Verwenden Sie eine der folgenden Möglichkeiten, um diese Aktualisierungen bereitzustellen:

1. Treiber-SDK verwenden: Android iOS -- die einfachste Option.
2. Verwenden Sie benutzerdefinierten Code. Dies ist nützlich, wenn Standorte oder wenn Sie andere Geräte als Android oder iOS

Die Entität „Vehicle“ enthält ein wiederkehrendes Feld von TripWaypoint (RPC | REST). mit dem Namen waypoints(RPC | REST). Dieses Feld enthält die verbleibenden Wegpunkte in der Reihenfolge, wie das Fahrzeug sie erreicht. Fleet Engine berechnet dieses Feld so, dass Fahrten zugewiesen und aktualisiert es, wenn sich der Status von Fahrten ändert. Diese Wegpunkte können durch die Felder TripId und WaypointType angegeben werden.

Mehr Möglichkeiten für Übereinstimmungen

In der Regel sind die Fahrdienste von Mitfahrdiensten oder Lieferdiensten für die Zuordnung der Fahrt verantwortlich. an Fahrzeuge senden. Der Dienst kann mithilfe der Fahrzeugattribute eine bei einer größeren Anzahl von Suchanfragen verwendet wird. Beispielsweise kann der Anbieter eine Reihe von Attributen, die den Stufen der Vorteile oder Fähigkeiten entsprechen, die von ein Fahrzeug. Drei Ebenen könnten z. B. eine Reihe von Attributen mit booleschen Werte: is_bronze_level, is_silver_level und is_gold_level. Ein Fahrzeug für alle drei infrage kommen. Wenn die Fleet Engine eine Anfrage für eine die Silber-Status erfordert, wird dieses Fahrzeug in der Suche berücksichtigt. Wenn Sie Attribute auf diese Weise verwenden, sind auch Fahrzeuge eingeschlossen, die eine Vielzahl von Funktionen.

Es gibt zwei Möglichkeiten, Fahrzeugattribute zu aktualisieren. Einer ist der UpdateVehicle der API erstellen. Bei Verwendung dieser API ist der gesamte Satz an Fahrzeugattributen auf den Wert festgelegt ist. Es ist nicht möglich, nur ein einzelnes Attribut zu aktualisieren. Die andere Methode ist die UpdateVehicleAttributes API. Bei dieser Methode werden nur die zu aktualisierenden Attribute. In der Anfrage enthaltene Attribute sind auf den neuen oder hinzugefügten Wert festgelegt; nicht spezifizierte Attribute werden nicht geändert.

ANLEITUNG: Fahrzeug erstellen

Für jedes Fahrzeug, das in der Flotte verfolgt werden soll, muss eine Vehicle-Entität erstellt werden.

Verwenden Sie den Endpunkt CreateVehicle mit der CreateVehicleRequest, um einen Fahrzeug.

Die provider_id von Vehicle muss die Projekt-ID sein (z.B. my-on-demand-Projekt) des Google Cloud-Projekts, das die Dienstkonten, die zum Aufrufen der Fleet Engine verwendet werden. Hinweis: Während mehrere Dienstkonten können für denselben Mitfahrdienst auf die Fleet Engine zugreifen. oder Delivery Provider, unterstützt die Fleet Engine derzeit keine Dienstkonten von Mehrere Google Cloud-Projekte greifen auf dasselbe Vehicles zu.

Das Vehicle kann im Status OFFLINE oder ONLINE erstellt werden. Wenn erstellt ONLINE, wird er möglicherweise sofort als Antwort auf SearchVehicles zurückgegeben. Abfragen.

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

Weitere Informationen zum Fahrzeug finden Sie unter Fahrzeugtypen type ein.

Weitere Informationen finden Sie in den Fahrzeugattributen. für das Attributfeld.

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

Beispiel

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 zum Erstellen von Fahrzeugen

Die Fleet Engine API schreibt einen Log-Eintrag über Google Cloud Platform-Logs, wenn an den Endpunkt CreateVehicle empfangen wird. Der Logeintrag enthält Informationen zu den Werten in der CreateVehicle-Anfrage. Wenn der Anruf enthält, enthält sie auch Informationen über die Vehicle, die zurückgegeben.

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 für Fahrzeugerstellung

Die Fleet Engine API veröffentlicht eine Benachrichtigung über Cloud Pub/Sub, wenn eine neue das Fahrzeug erstellt wird. Um diese Benachrichtigungen zu erhalten, folgen Sie bitte der Anleitung.

ANLEITUNG: Fahrzeugstandort aktualisieren

Wenn Sie das Driver SDK nicht verwenden, um den Standort des Fahrzeugs zu aktualisieren, können Sie einen direkten Aufruf der Fleet Engine mit dem Standort des Fahrzeugs. Für alle aktiven Fahrzeuge Fleet Engine erwartet ein Standortupdate mindestens einmal pro Minute und höchstens einmal alle 5 Sekunden. Für diese Updates ist nur ein Fleet Engine Driver SDK-Nutzer erforderlich Berechtigungen.

Beispiel

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

Andere Attribute des Fahrzeugstatus werden seltener aktualisiert als zu aktualisieren. Aktualisierungen anderer Attribute als last_location erfordern Fleet Engine-Superuser-Berechtigungen.

UpdateVehicleRequest enthält einen update_mask, der angibt, welche Felder aktualisieren. Das Verhalten des Feldes entspricht dem in der Protobuf-Dokumentation für Feldmasken.

Wie unter Fahrzeugattribute beschrieben, aktualisieren Sie die Im Feld attributes müssen alle Attribute geschrieben werden, die beibehalten werden sollen. Es den Wert eines Schlüssel/Wert-Paars in einem UpdateVehicle Anruf. Um die Werte bestimmter Attribute zu aktualisieren, Die UpdateVehicleAttributes API kann verwendet werden.

Beispiel

In diesem Beispiel wird back_to_back aktiviert.

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 Log-Eintrag über Google Cloud Platform-Logs, wenn an den Endpunkt UpdateVehicle empfangen wird. Der Logeintrag enthält Informationen zu den Werten in der UpdateVehicle-Anfrage. Wenn der Anruf enthält, enthält sie auch Informationen über die Vehicle, die zurückgegeben.

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

Cloud Pub/Sub-Benachrichtigungen für Fahrzeugupdates

Die Fleet Engine API veröffentlicht eine Benachrichtigung über Cloud Pub/Sub, wenn eine vorhandene das Fahrzeug aktualisiert wird. Um diese Benachrichtigungen zu erhalten, folgen Sie bitte den Anleitung.

ANLEITUNG: Fahrzeuge suchen

Fleet Engine unterstützt die Suche nach Fahrzeugen. Das SearchVehicles Die API ermöglicht es Ihnen, verfügbare Fahrer in der Nähe zu finden, die für eine Aufgabe am besten geeignet sind, z. B. Fahrdienst- oder Lieferanfragen warten. Die SearchVehicles API gibt eine Rangliste der Fahrer, die die Aufgabenattribute mit den Fahrzeugattributen in für Ihre Flotte. Weitere Informationen finden Sie unter Suche nach Fahrern in der Nähe.

Beispiel

Bei der Suche nach verfügbaren Fahrzeugen schließt Fleet Engine Fahrzeuge aus standardmäßig aktive Fahrten. Die Dienste des Mitfahrdienstes oder Lieferanbieters müssen explizit in Suchanfragen einschließen. Das folgende Beispiel zeigt, wie Sie diese Fahrzeuge in eine Suche nach Fahrzeugen einschließen, die mit einer Fahrt vom Grand Indonesia East Mall zum Balai Sidang Jakarta Convention Center.

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

Anfrage zum Filtern von Fahrzeugen

SearchVehicles und ListVehicles unterstützen das Filtern nach Fahrzeugattributen mithilfe einer Filterabfrage. Informationen zur Filterabfragesyntax finden Sie unter AIP-160.

Beachten Sie, dass Filterabfragen NUR das Filtern nach Fahrzeugattributen unterstützen. kann nicht für andere Felder verwendet werden. Die Filterabfrage funktioniert als AND-Klausel mit anderen Einschränkungen wie minimum_capacity oder vehicle_types in SearchVehiclesRequest

ANLEITUNG: Fahrzeuge auflisten

SearchVehicles ist für die Suche nach einer kleinen Anzahl von Fahrzeugen im Ranking optimiert sehr schnell und wird hauptsächlich verwendet, um Fahrer in der Nähe zu finden, zu einer Aufgabe hinzufügen. Sie möchten jedoch auch alle Fahrzeuge finden, selbst wenn das Durchblättern der Ergebnisse erforderlich ist. ListVehicles ist die speziell für diesen Anwendungsfall entwickelt wurden.

Mit der ListVehicles API können Sie alle Fahrzeuge finden, die bestimmte Anfrageoptionen. Die ListVehicles API gibt eine paginierte Liste von Fahrzeugen in das einige Anforderungen erfüllt.

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

Beispiel

In diesem Beispiel wird nach vehicle_type und Attributen gefiltert. Dabei werden die Parameter filter-String.

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 der Lebenszyklus ähneln der Vehicle API und dem Lebenszyklus. Der Mitfahrdienst ist für die Erstellung von Fahrten mithilfe der Fleet Engine verantwortlich. Schnittstellen. Fleet Engine bietet einen RPC-Dienst, TripService und REST-Ressourcen provider.trips . Über diese Oberflächen können Trip-Entitäten erstellt, Informationen angefordert und Funktionalität und Update-Funktion.

Eine Trip hat ein Statusfeld, um ihren Fortschritt im Lebenszyklus zu verfolgen. Die Werte verschieben sich von NEW nach COMPLETE plus CANCELED und UNKNOWN_TRIP_STATUS . Siehe trip_status für RPC oder TripStatus für REST.

• NEW
• ENROUTE_TO_PICKUP
• ARRIVED_AT_PICKUP
• ENROUTE_TO_INTERMEDIATE_DESTINATION
• ARRIVED_AT_INTERMEDIATE_DESTINATION
• ENROUTE_TO_DROPOFF
• COMPLETE

Dein Service kann die Fahrt nach CANCELED mit einem dieser Status aktualisieren. Wenn Ihr Service eine Fahrt erstellt, legt der Motor den Status auf NEW fest. A vehicle_id ist optional. Wie bei Fahrzeugen löschen die Dienste nicht zugewiesene Fahrten automatisch nach 7 Tagen ohne Update zu kaufen. Wenn Ihr Service versucht, eine Fahrt mit einer ID bereits vorhanden ist, wird ein Fehler zurückgegeben. Eine Fahrt gilt als „aktiv“, wenn Sie hat einen anderen Status als COMPLETE oder CANCELED. Diese Unterscheidung in der Entität „Fahrzeug“ und SearchTripsRequest im Feld active_trips wichtig.

Dein Service kann die vehicle_id, die einer Fahrt zugewiesen ist, nur ändern, wenn die Fahrt ist aktiv. Das ist zum Beispiel der Fall, wenn ein Fahrer eine Fahrt annulliert, während und die Fahrt wird einem anderen Fahrzeug zugewiesen.

Der Status ist wichtig, wenn eine direkte Implementierung Reiseunterstützung. Diese Unterstützung ermöglicht es dem Anbieter, einem Fahrzeug eine neue Fahrt zuzuweisen während sich das Fahrzeug auf einer aktiven Fahrt befindet. Der Code zur Erstellung einer direkt aufeinanderfolgenden Fahrt ist identisch mit Fahrzeug-ID. Fleet Engine fügt den Start- und Zielort der neuen Fahrt zur die Wegpunkte des Fahrzeugs. Weitere Informationen zu aufeinanderfolgenden Fahrten finden Sie unter Fahrten mit mehreren Wegpunkten erstellen

Verbleibende Wegpunkte

Die Entität „Trip“ enthält ein wiederkehrendes Feld von TripWaypoint (RPC | REST), mit dem Namen remainingWaypoints(RPC | REST). Dieses Feld enthält alle Wegpunkte, die das Fahrzeug in dieser Reihenfolge zurücklegen muss. vor dem letzten Ausstiegspunkt dieser Fahrt. Berechnung anhand von Verbleibende Wegpunkte des Fahrzeugs. Bei den Anwendungsfällen für Rücken an Rücken und Fahrgemeinschaft enthält diese Liste Wegpunkte aus andere Fahrten, die vor dieser Fahrt durchlaufen werden, aber Wegpunkte ausgeschlossen nach dieser Reise. Der Wegpunkt in der Liste kann anhand seiner TripId identifiziert werden und WaypointType.

Die Beziehung zwischen Fahrtstatus und verbleibenden Wegpunkten des Fahrzeugs

Die verbleibenden Wegpunkte (RPC | REST) des Fahrzeugs wird aktualisiert, wenn Fleet Engine eine Anfrage zur Änderung des Fahrtstatus erhält. Die wird der vorherige Wegpunkt aus der Liste der verbleibenden Wegpunkte entfernt, wenn den tripStatus(RPC | REST) wird von anderem Status in ENROUTE_TO_XXX geändert. Das heißt, wenn sich der Fahrtstatus von ENROUTE_TO_PICKUP in ARRIVED_AT_PICKUP ändert, ist der Abholpunkt weiterhin in der Liste der verbleibenden Wegpunkte, aber Status in ENROUTE_TO_INTERMEDIATE_DESTINATION oder ENROUTE_TO_DROPOFF geändert wird sein Abholpunkt dann aus den verbleibenden Wegpunkten des Fahrzeugs entfernt.

Das Gleiche gilt für ARRIVED_AT_INTERMEDIATE_DESTINATION und ENROUTE_TO_INTERMDEDIATE_DESTINATION. Bei ARRIVED_AT_INTERMEDIATE_DESTINATION, wird das aktuelle Zwischenziel nicht aus dem verbleibenden Ziel entfernt. bis das Fahrzeug meldet, dass es auf der Route zum nächsten Wegpunkt ist.

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

ANLEITUNG: Eine Reise erstellen

Es muss eine Trip-Entität erstellt werden, damit jede Fahrtanfrage verfolgt und den Fahrzeugen in der Flotte zugeordnet. Endpunkt CreateTrip mit CreateTripRequest verwenden , um eine Reise zu erstellen.

Die folgenden Attribute sind erforderlich, um eine Fahrt zu erstellen:

• parent: ein String, der die Anbieter-ID enthält, die beim Verwenden der Cloud-Projekt wurde erstellt.
• trip_id: ein vom Mitfahrdienst-Anbieter erstellter String
• trip: Container mit grundlegenden Metadaten, die die Fahrt beschreiben.
  • trip_type: Aufzählung, die angibt, ob die Fahrt möglicherweise andere Fahrgäste haben könnte von einem anderen Start- und Zielort im selben Fahrzeug (SHARED) oder nur für eine einzelne Partei (EXCLUSIVE).
  • pickup_point: TerminalLocation, das den Startpunkt für den Fahrt. Siehe RPC-Referenz oder REST-Referenz

Wenn Sie eine Fahrt erstellen, können Sie Folgendes angeben: number_of_passengers, dropoff_point und vehicle_id. Obwohl diese Felder nicht erforderlich sind, bleiben sie erhalten. Alle anderen Trip-Felder werden ignoriert. Beispielsweise werden alle Fahrten beginnen Sie mit einem trip_status von NEW, auch wenn Sie eine trip_status von CANCELED in der Anfrage zur Erstellung.

Beispiel

Im folgenden Beispiel wird eine Fahrt zur Grand Indonesia East Mall erstellt. Die Fahrt ist für zwei Passagiere exklusiv. Die provider_id von Trip muss Projekt-ID übereinstimmen. In diesem Beispiel hat der Mitfahrdienst die Google Cloud-Projekt, project-id. Dieses Projekt muss die Dienstkonten, die zum Aufrufen der Fleet Engine verwendet werden. Der Status der Fahrt ist „NEW“.

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

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 zum Erstellen von Fahrten

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

ANLEITUNG: Fahrt aktualisieren

Die Entität „Trip“ enthält Felder, die die Nachverfolgung durch den Dienst und für Meldung des Fahrtverlaufs durch das Driver SDK und Consumer SDK: Verwenden Sie UpdateTripRequest, um die Attribute zu aktualisieren. angezeigt. Dadurch werden die Trip-Felder entsprechend der field_mask der Anfrage aktualisiert. Weitere Informationen finden Sie unter UpdateTripRequest.

Der Mitfahrdienst ist für die Aktualisierung der folgenden Attribute verantwortlich:

• Fahrtstatus.
• Fahrzeug-ID. entweder bei der Erstellung oder nachdem das Fahrzeug einem Fahrt.
• Änderungen an Abhol-, Absetz- oder Wegpunkten.

Die Fleet Engine aktualisiert die folgenden Felder automatisch, wenn die Funktion zum Teilen von Kaufprozessen über das Driver SDK oder Consumer SDK:

• Routen
• ETA
• Verbleibende Strecke
• Fahrzeugstandort
• Verbleibende Wegpunkte

Weitere Informationen finden Sie unter Tripin RPC oder Resource.Trip in REST.

Google Cloud Platform-Logs für Fahrtaktualisierungen

Die Fleet Engine API schreibt einen Logeintrag mithilfe von Logs der Google Cloud Platform, wenn an den Endpunkt UpdateTrip empfangen wird. Der Logeintrag enthält Informationen zu den Werten in der UpdateTrip-Anfrage. Ist der Aufruf erfolgreich, enthält sie auch Informationen zum zurückgegebenen Trip.

ANLEITUNG: Reisen suchen

Fleet Engine unterstützt die Suche nach Fahrten. Wie bereits erwähnt, ist eine Reise werden nach sieben Tagen automatisch gelöscht. SearchTrips stellen den vollständigen Verlauf aller Fahrten bereit.

SearchTrips ist zwar eine flexible API, in der folgenden Liste werden jedoch zwei Anwendungsfälle berücksichtigt.

• Aktive Fahrten eines Fahrzeugs ermitteln: Der Anbieter kann die derzeit aktiven Fahrten eines Fahrzeugs ermitteln. Innerhalb von SearchTripsRequest enthält das Feld vehicle_id ist auf das betreffende Fahrzeug festgelegt und active_trips_only sollte auf true festgelegt sein.

• Anbieter und Fleet Engine-Status abgleichen: Der Anbieter kann Folgendes verwenden: SearchTrips, um sicherzustellen, dass der Trip-Status und der von Fleet Engine übereinstimmen. Das ist besonders wichtig für „TripStatus“. Wenn der Status einer Fahrt nicht korrekt auf COMPLETE oder CANCELED eingestellt ist, wird das Fahrzeug ist in SearchVehicles nicht enthalten.

Wenn Sie SearchTrips auf diese Weise verwenden möchten, lassen Sie vehicle_id leer und legen active_trips_only fest auf true und minimum_staleness auf eine Zeit festlegen, die länger als die meisten Fahrten ist. Sie können beispielsweise eine Stunde verwenden. Die Ergebnisse umfassen Fahrten, die nicht FULL oder CANCELED und wurden seit über einer Stunde nicht mehr aktualisiert. Der Anbieter sollten diese Fahrten überprüfen, um sicherzustellen, dass ihr Status in der Fleet Engine auf dem neuesten Stand sind.

Fehlerbehebung

Im Fall des Fehlers DEADLINE_EXCEEDED lautet der Status der Fleet Engine unbekannt. Der Anbieter sollte CreateTrip noch einmal aufrufen, wodurch entweder ein Fehler zurückgegeben wird. 201 (ERSTELLT) oder 409 (CONFLICT). Im letzteren Fall war die vorherige Anfrage erfolgreich. vor dem DEADLINE_EXCEEDED. Weitere Informationen finden Sie in den Consumer API-Leitfäden. zur Behandlung von Fahrtfehlern: Android oder iOS.

Unterstützung für Fahrgemeinschaften

Du kannst einem Fahrzeug, das TripType.SHARED unterstützt, mehrere Fahrten mit „SHARED“ zuweisen. Sie müssen die Reihenfolge aller nicht bestandenen Wegpunkte für alle Trips angeben, die der das Fahrzeug in dieser geteilten Fahrt über Trip.vehicle_waypoints, wenn du die vehicle_id für eine gemeinsame Reise (in einer CreateTrip- oder UpdateTrip-Anfrage). Siehe vehicle_waypoints für RPC oder vehicleWaypoints für REST.

Unterstützung mehrerer Ziele

Zwischenziel bestimmen

Die Felder intermediateDestinations und intermediateDestinationIndex in Fahrt (RPC | REST) werden kombiniert, um das Ziel anzugeben.

Zwischenziel aktualisieren

Sie können die Zwischenziele über UpdateTrip aktualisieren. Beim Aktualisieren Zwischenziele erreichen, müssen Sie eine vollständige Liste der Zwischenziele angeben, einschließlich der bereits besuchten, nicht nur die hinzugefügt oder zu ändern ist. Wenn intermediateDestinationIndex auf einen Index nach der Position von neu hinzugefügtes/geändertes Zwischenziel, neues/aktualisiertes Zwischenziel wird nicht zur waypoints des Fahrzeugs oder zur remainingWaypoints der Reise hinzugefügt. Der Grund ist, dass Zwischenziele vor intermediateDestinationIndex als bereits besucht behandelt werden.

Änderungen des Fahrtstatus

Das Feld intermediateDestinationsVersion in (RPC | REST) ist in der Anfrage zur Aktualisierung des Fahrtstatus erforderlich, die an Fleet Engine gesendet wird, ein Zwischenziel verstrichen ist. Das Zwischenziel als Ziel wird im Feld intermediateDestinationIndex angegeben. Wenn tripStatus (RPC | REST) gleich ENROUTE_TO_INTERMEDIATE_DESTINATION ist, wird eine Zahl zwischen [0..N-1] gibt an, welches Zwischenziel das Fahrzeug als Nächstes überquert. Wenn tripStatus ARRIVED_AT_INTERMEDIATE_DESTINATION ist, wird eine Zahl zwischen [0..N-1] gibt an, an welchem Zwischenziel sich das Fahrzeug befindet.

Beispiel

Im folgenden Codebeispiel wird gezeigt, wie Sie den Status einer Fahrt so aktualisieren, dass sie unterwegs ist an ihr erstes Zwischenziel zu leiten, vorausgesetzt, Sie haben ein mehrere Ziele und die Fahrt hat ihren Abholpunkt überschritten.

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 Zum Veröffentlichen von Benachrichtigungen zu dem Thema, das vom Google Cloud-Nutzer erstellt wurde Projekt Pub/Sub ist für Fleet Engine in Ihrer Google Cloud nicht standardmäßig aktiviert Projekt arbeiten. Reichen Sie eine Supportanfrage ein oder wenden Sie sich an Ihren Customer Engineer, um Pub/Sub zu aktivieren.

Folgen Sie dieser Anleitung, um ein Thema in Ihrem Cloud-Projekt zu erstellen. Die Themen-ID muss „fleet_engine_notifications“ sein.

Das Thema muss im selben Cloud-Projekt erstellt werden, das Fleet Engine aufruft APIs

Nachdem das Thema erstellt wurde, müssen Sie die Fleet Engine API gewähren die Berechtigung zum Veröffentlichen für das Thema. Klicke dafür auf das Thema, und fügen Sie eine neue Berechtigung hinzu. Möglicherweise müssen Sie auf INFOFELD ANZEIGEN klicken, um den Berechtigungseditor zu öffnen. Das Hauptkonto sollte geo-fleet-engine@system.gserviceaccount.com sein und die Rolle sollte Pub/Sub publisher sein.

Um Ihr Cloud-Projekt für das Abonnieren von Benachrichtigungen einzurichten, folgen Sie dieser Anleitung

Die Fleet Engine API veröffentlicht jede Benachrichtigung in zwei verschiedenen Daten Formate, protobuf und json. Das Datenformat für jede Benachrichtigung wird in der PubsubMessage-Attribute mit dem Schlüssel data_format und dem Wert protobuf oder json.

Benachrichtigungsschema:

Protobuf

// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
  // Required. At least one notification must exist.
  // List of notifications containing information related to changes in
  // Fleet Engine data.
  repeated Notification notifications = 1;
}

// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
  // Required. At least one type must exist.
  // Type of notification.
  oneof type {
    // Notification related to changes in vehicle data.
    VehicleNotification vehicle_notification = 1;
  }
}

// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
  // Required.
  // Vehicle must contain all fields that were set when it was created.
  Vehicle vehicle = 1;
}

// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
  // Required.
  // Vehicle must only contain name and fields that are present in the
  // field_mask field below.
  Vehicle vehicle = 1;

  // Required.
  // Contains vehicle field paths that were specifically requested
  // by the Provider.
  google.protobuf.FieldMask field_mask = 2;
}

// Notification related to changes in vehicle data.
message VehicleNotification {
  // Required. At least one type must be set.
  // Type of notification.
  oneof type {
    // Notification sent when a new vehicle was created.
    CreateVehicleNotification create_notification = 1;
    // Notification sent when an existing vehicle is updated.
    UpdateVehicleNotification update_notification = 2;
  }
}

JSON

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