Comienza a usar Fleet Engine

La API de Fleet Engine On-demand Rides and Deliveries te permite administrar viajes y el estado del vehículo para tus aplicaciones del Progreso del viaje y del pedido. Este controla transacciones entre el SDK del controlador, el SDK para consumidores y tu de servicio de backend, que puede comunicarse con Fleet Engine haciendo gRPC o llamadas de REST.

Requisitos previos

Para el desarrollo, asegúrate de instalar el SDK de Cloud SDK (gcloud) y se autentican en tu proyecto.

gcloud auth login

You are now logged in as [my-user@example.com].
Your current project is [project-id].  You ...

Verifica que las APIs de Solution Fleet Engine de On-demand Rides and Deliveries estén configuradas de forma correcta.

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

Logging

Fleet Engine puede escribir mensajes de registro sobre las llamadas a la API que recibe en registros de Google Cloud Platform. Consulta la documentación de Cloud Logging para obtener un descripción general de cómo leer y analizar registros.

Es posible que el registro no esté habilitado de forma predeterminada en los proyectos creados antes del 10 de febrero de 2022. Consulta la documentación de registros para obtener más información.

Bibliotecas cliente

Publicamos bibliotecas cliente en varios lenguajes de programación comunes. Estos ayudarán a proporcionar una mejor experiencia al desarrollador con REST o gRPC sin procesar. Si deseas instrucciones sobre cómo obtener bibliotecas cliente para tu aplicación de servidor, ver Bibliotecas cliente.

Para los ejemplos de Java en esta documentación, se da por sentado que el usuario tiene conocimientos previos sobre gRPC.

Autenticación y autorización

Puedes configurar las capacidades proporcionadas por el Progreso del viaje y del pedido mediante con la consola de Google Cloud. Estas APIs y SDKs requieren el uso de tokens web JSON que se firmaron con cuentas de servicio creadas a partir de Google Cloud.

Configuración del proyecto de Cloud

Para configurar tu proyecto de la nube, primero créalo y, luego, crear cuentas de servicio.

Para crear tu proyecto de Google Cloud, sigue estos pasos:

1. Crea un proyecto de Google Cloud con la consola de Google Cloud.
2. Con el panel de APIs y servicios, habilita la API de Local Rides and Deliveries.

Las cuentas de servicio están asociadas con uno o más roles. Se usan para crear Los tokens web JSON que otorgan diferentes conjuntos de permisos según el tipo para los puestos de profesionales de datos en la nube. Normalmente, para reducir la posibilidad de abuso, puedes crear varias cuentas de servicio, cada una con el conjunto mínimo de roles necesarios.

El Progreso del viaje y el pedido usa los siguientes roles:

Por ejemplo, crea una cuenta de servicio para cada uno de los tres roles y asígnale sus respectivos roles.

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

Los SDK del controlador y del consumidor se basan en estas funciones estándar.

Como alternativa, se pueden crear roles personalizados que permitan un conjunto arbitrario de permisos para agrupar. Los SDK para consumidores y controladores mostrarán mensajes de error cada vez que se falta el permiso necesario. Por eso, recomendamos enfáticamente usando el conjunto estándar de roles presentado arriba y no usando roles personalizados.

Para mayor comodidad, si necesitas crear tokens JWT para clientes que no son de confianza, puedes agregar usuarios al rol Creador de tokens de cuenta de servicio les permite crear tokens con las herramientas de línea de comandos de gcloud

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

Donde my-user@example.com es el correo electrónico que se usa para autenticar con gcloud (gcloud auth list --format='value(account)').

Biblioteca de autenticación de Fleet Engine

Fleet Engine usa tokens web JSON (JWT) para restringir el acceso a APIs de Fleet Engine. La nueva biblioteca de autenticación de Fleet Engine disponibles en GitHub simplifica la construcción de JWT de Fleet Engine y los firma de forma segura.

La biblioteca proporciona los siguientes beneficios:

• Simplifica el proceso de creación de tokens de Fleet Engine.
• Proporciona mecanismos de firma de token distintos del uso de archivos de credenciales (como y suplantará la identidad de una cuenta de servicio).
• Adjunta tokens firmados a solicitudes salientes realizadas desde un stub de gRPC o cliente GAPIC.

Crea un token web JSON (JWT) para la autorización

Cuando no se usa la biblioteca de autenticación de Fleet Engine, los tokens web JSON (JWT) deben que puedes crear directamente en tu base de código. Esto requiere que tengas conocimientos comprensión de los JWT y su relación con Fleet Engine. Por eso, Se recomienda encarecidamente aprovechar la biblioteca de autenticación de Fleet Engine.

Dentro de Fleet Engine, los tokens web JSON (JWT) proporcionan autenticación de corta duración y garantizar que los dispositivos solo modifiquen vehículos, viajes o tareas para los que están autorizados. Los JWT contienen un encabezado y una sección de reclamación. La sección de encabezado contiene información como el clave privada para usar (obtenida de las cuentas de servicio) y la encriptación de codificador-decodificador. La sección de reclamos contiene información como el el tiempo de creación del token, el tiempo de actividad de los tokens, los servicios reclamar acceso y otra información de autorización para reducir el alcance el acceso a los datos; por ejemplo, el ID del vehículo.

Una sección de encabezado JWT contiene los siguientes campos:

Una sección de reclamaciones de JWT contiene los siguientes campos:

Crear un token JWT hace referencia a firmarlo. Para instrucciones y muestras de código para crear y firmar el JWT, consulta Autorización de cuenta de servicio sin OAuth. Luego, puedes adjuntar un token firmado a las llamadas de gRPC o a otros métodos usados para acceder a Fleet Engine.

Reclamaciones de JWT

Cuando crees la carga útil de JWT, agrega una reclamación adicional en la autorización con la clave vehicleid o tripid establecida en el valor de la el ID de vehículo o el ID de viaje para el que se realiza la llamada.

El SDK de Driver siempre usa la reclamación de vehicleid, ya sea que opere en un viaje o un vehículo. El backend de Fleet Engine asegura que el vehículo está asociada con el viaje solicitado antes de realizar la modificación.

El SDK para consumidores siempre usa la reclamación tripid.

El proveedor de transporte compartido o de entrega debe utilizar el vehicleid o la tripid con un "*" a coincide con todos los vehículos y viajes. Ten en cuenta que el JWT puede contener ambos tokens, incluso si no es necesario, lo que puede simplificar la implementación de la firma de tokens.

Casos de uso de JWT

A continuación, se muestra un token de ejemplo para el servidor del proveedor:

{
  "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": "*"
   }
}

A continuación, se muestra un ejemplo de token para una App de consumidor:

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

A continuación, se muestra un token de ejemplo para una app del controlador:

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

• En el campo kid del encabezado, especifica la clave privada de tu cuenta de servicio ID. Puedes encontrar este valor en el campo private_key_id de tu servicio en el archivo JSON de la cuenta.
• Para los campos iss y sub, especifica la dirección de correo electrónico de tu cuenta de servicio. Puedes encontrar este valor en el campo client_email de tu cuenta de servicio Archivo JSON.
• En el campo aud, especifica https://SERVICE_NAME/.
• En el campo iat, usa la marca de tiempo de cuando se creó el token. se especifica como los segundos transcurridos desde las 00:00:00 UTC del 1 de enero de 1970. Espera 10 minutos para el sesgo. Si la marca de tiempo corresponde a un pasado muy lejano, o en el futuro, el servidor podría informar un error.
• En el campo exp, usa la marca de tiempo de vencimiento del token. especificado como segundos desde el 1 de enero de 1970 a las 00:00:00 UTC. El máximo el valor permitido es iat + 3,600.

Al firmar el JWT que se pasará a un dispositivo móvil, asegúrate de usar la cuenta de servicio para el rol de controlador o SDK de consumidor. De lo contrario, el vínculo el dispositivo podrá modificar el estado que no debería tener.

Asimismo, cuando firmes el JWT que se usará para llamadas con privilegios, asegúrate de que para usar la cuenta de servicio con el rol de superusuario. De lo contrario, el la operación fallará.

Cómo generar un JWT para realizar pruebas

Generar tokens desde la terminal puede ser útil durante las pruebas.

Para seguir estos pasos, tu usuario debe tener el rol Creador de tokens de cuenta de servicio:

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

Crea un archivo nuevo llamado unsigned_token.json con el siguiente contenido. El iat es la hora actual en segundos después del ciclo de entrenamiento, que puede para recuperarlo mediante la ejecución de date +%s en tu terminal. La propiedad exp es la de vencimiento en segundos después del ciclo de entrenamiento, que se puede calcular agregando 3,600 a iat. El tiempo de vencimiento no puede ser superior a una hora en la en el futuro.

{
  "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": "*"
   }
}

Ejecuta el siguiente comando de gcloud para firmar el token en nombre de tu Super Cuenta de servicio de usuario:

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

Los JWT firmados codificados en Base64 deberían almacenarse en el archivo signed_token.jwt El token es válido durante la próxima hora.

Ahora puedes probar el token ejecutando un comando curl en el comando List Vehicles. Extremo de REST:

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

Vehículos y su ciclo de vida

El vehículo es la entidad que representa un par conductor-vehículo. Actualmente, no se puede hacer un seguimiento de un conductor y un vehículo por separado. El proveedor de transporte compartido o de entregas crea un vehículo con un ID de proveedor (que debe ser el mismo que el ID del proyecto de Google Cloud que contiene la cuenta de servicio para llamar a las APIs de Fleet Engine) y un ID de vehículo propiedad del proveedor de transporte compartido o de entrega.

Un vehículo que no se haya actualizado a través de UpdateVehicle después de siete días hará lo siguiente: se borrará automáticamente, y sus viajes asignados, si los hay, se marcarán como sin asignar. El enfoque recomendado para mantener la disponibilidad de un vehículo en Fleet Engine es que actualice su ubicación en intervalos regulares. Actualizaciones de la mayoría Otros campos de la entidad Vehicle también extenderán su vida útil, siempre y cuando el valor del campo nuevo es diferente del existente.

NOTA: Algunos campos de la entidad Vehicle, como device_settings, son puramente depurados. que no persiste en Fleet Engine. Actualizarlos no extender la vida útil de la entidad Vehicle

Es un error llamar a CreateVehicle con un Par de ID de proveedor/ID de vehículo que ya existe. El caso de los vehículos que que no se actualizan con frecuencia se pueden tratar de dos maneras: llamando con frecuencia CreateVehicle con un par de ID de proveedor/ID de vehículo esperado y descartado el error si el vehículo ya existe; o llamar a CreateVehicle después de un UpdateVehicle se muestra con un error NOT_FOUND.

Actualizaciones de la ubicación del vehículo

Para obtener el mejor rendimiento con Fleet Engine, proporciónalo con una transmisión de vehículos las actualizaciones de ubicación. Usa cualquiera de las siguientes formas para proporcionar estas actualizaciones:

1. Usa el SDK de Driver: Android iOS -- es la opción más sencilla.
2. Utilizar un código personalizado, útil si las ubicaciones son se retransmiten mediante tu backend o si usas dispositivos que no sean Android iOS

La entidad Vehicle contiene un campo repetido de TripWaypoint (RPC | REST), llamado waypoints(RPC | REST). Este campo incluye los puntos de referencia restantes en los viajes, en el orden en que hasta que el vehículo los llegue. Fleet Engine calcula este campo a medida que los viajes asignado al vehículo y lo actualiza a medida que los viajes cambian su estado. Estos puntos de referencia se pueden identificar mediante los campos TripId y WaypointType.

Ampliación de la elegibilidad de un vehículo para coincidencias

Por lo general, los servicios de transporte compartido o proveedor de servicios de transporte son responsables de hacer coincidir el viaje. solicitudes a vehículos. El servicio puede usar los atributos de vehículo para incluir una vehículo en una mayor cantidad de búsquedas. Por ejemplo, el proveedor puede implementar un conjunto de atributos correspondientes a los niveles de beneficios o capacidades que proporciona un vehículo. Por ejemplo, tres niveles podrían ser un conjunto de atributos con valores valores: is_bronze_level, is_silver_level y is_gold_level. Un vehículo puede ser apto para los tres. Cuando Fleet Engine recibe una solicitud de viaje que requiere capacidades en el nivel plateado, la búsqueda incluye ese vehículo. Al usar los atributos de esta forma, se incluyen los vehículos que ofrecen una variedad de capacidades de integración.

Existen dos formas de actualizar los atributos del vehículo. Uno es UpdateVehicle en la API de Cloud. Cuando se usa esta API, todo el conjunto de atributos de vehículo se define en el valor. No es posible actualizar un solo atributo. El otro método es la API de UpdateVehicleAttributes. Este método toma solo los atributos que se actualizarán. Los atributos incluidos en la solicitud serán se establezca en el valor nuevo o agregado. los atributos no especificados no se modificarán.

Instructivo: Crea un vehículo

Se debe crear una entidad Vehicle para cada vehículo que se rastreará en la flota.

Usa el extremo CreateVehicle con CreateVehicleRequest para crear un Vehículo

El provider_id de Vehicle debe ser el ID del proyecto (p.ej., my-on-demand-project) del proyecto de Google Cloud que contiene los Cuentas de servicio que se usarán para llamar a Fleet Engine. Ten en cuenta que, si bien varias cuentas de servicio pueden acceder a Fleet Engine por el mismo transporte compartido o proveedor de servicios de entrega, Fleet Engine actualmente no admite cuentas de servicio de varios proyectos de Google Cloud que acceden al mismo Vehicles.

Vehicle se puede crear en el estado OFFLINE o ONLINE. Si creado ONLINE, es posible que se muestre de inmediato en respuesta a SearchVehicles para tus consultas.

Se puede incluir un last_location inicial en la llamada a CreateVehicle. Si bien se permite, no se debe crear un Vehicle en el estado ONLINE sin Un objeto last_location.

Consulta la sección Tipos de vehículos para obtener más detalles. .

Consulta los Atributos de vehículo para obtener más detalles. en el campo de atributos.

El valor que muestra CreateVehicle es la entidad Vehicle creada.

Ejemplo

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.

Registros de plataforma de Google Cloud para la creación de vehículos

La API de Fleet Engine escribe una entrada de registro a través de los registros de la plataforma de Google Cloud cuando un al extremo CreateVehicle. La entrada de registro incluye información sobre los valores de la solicitud CreateVehicle. Si la llamada tiene éxito, también incluirá información sobre el Vehicle que se que se devuelven.

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'

Notificaciones de Cloud Pub/Sub para la creación de vehículos

La API de Fleet Engine publica una notificación a través de Cloud Pub/Sub cuando se crea se crea el vehículo. Para recibir estas notificaciones, sigue la aquí.

Instructivo: Actualiza la ubicación de un vehículo

Si no usas el SDK del conductor para actualizar la ubicación del vehículo, puedes crear una llamada directa a Fleet Engine con la ubicación del vehículo. Para cualquier vehículo activo, Fleet Engine espera una actualización de la ubicación al menos una vez por minuto y como máximo una vez cada 5 segundos. Estas actualizaciones solo requieren el usuario del SDK de Fleet Engine Driver privilegios.

Ejemplo

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.

Instructivo: Actualiza otros campos de vehículos

Las actualizaciones a otros atributos del estado del vehículo ocurren con menos frecuencia que las actualizaciones de posición. Las actualizaciones de atributos que no sean last_location requieren Privilegios de superusuario de Fleet Engine.

UpdateVehicleRequest incluye un update_mask para indicar qué campos se deben actualización. El comportamiento del campo es como en la documentación de Protobuf para máscaras de campo.

Como se indica en Atributos de vehículo, actualizar el El campo attributes requiere la escritura de todos los atributos que se conservarán. Integra no es posible actualizar el valor de un par clave-valor en una UpdateVehicle llamada. Para actualizar valores de atributos específicos, el Se puede usar la API de UpdateVehicleAttributes.

Ejemplo

En este ejemplo, se habilita back_to_back.

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.

Registros de plataforma de Google Cloud para actualizaciones de vehículos

La API de Fleet Engine escribe una entrada de registro a través de los registros de la plataforma de Google Cloud cuando un al extremo UpdateVehicle. La entrada de registro incluye información sobre los valores de la solicitud UpdateVehicle. Si la llamada tiene éxito, también incluirá información sobre el Vehicle que se que se devuelven.

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

Notificaciones de Cloud Pub/Sub para actualizaciones de vehículos

La API de Fleet Engine publica una notificación a través de Cloud Pub/Sub cuando se vehículo se actualiza. Para recibir estas notificaciones, sigue la aquí.

Instructivo: Buscar vehículos

Fleet Engine admite la búsqueda de vehículos. El SearchVehicles La API te permite encontrar conductores cercanos disponibles que se adapten mejor a una tarea, como para brindar servicios a un viaje o una solicitud de entrega. La API de SearchVehicles muestra un lista clasificada de conductores que coinciden con los atributos de tareas con los atributos de vehículos en de tu flota. Para obtener más información, consulta Cómo encontrar conductores cercanos.

Ejemplo

Cuando se buscan vehículos disponibles, Fleet Engine excluye aquellos en viajes activos de forma predeterminada. Los servicios del Proveedor de transporte compartido o entrega a domicilio deben incluirlos explícitamente en las solicitudes de búsqueda. En el siguiente ejemplo, se muestra cómo incluir esos vehículos en una búsqueda de vehículos que coincidan con un viaje del Grand Indonesia East East al centro de convenciones Balai Sidang Yakarta.

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

Consulta de filtrado de vehículos

SearchVehicles y ListVehicles admiten el filtrado de atributos de vehículos con una consulta de filtro. Para ver la sintaxis de consulta de filtro, consulta AIP-160 para ver ejemplos.

Ten en cuenta que las consultas con filtros SOLO admiten el filtrado por atributos de vehículos. no se puede usar para otros campos. La consulta de filtro funciona como una cláusula AND. con otras restricciones, como minimum_capacity o vehicle_types en SearchVehiclesRequest

Instructivo: Muestra una lista de vehículos

SearchVehicles está optimizado para encontrar una pequeña cantidad de vehículos en la clasificación hacer pedidos muy rápido y se usa principalmente para encontrar conductores cercanos que sean más adecuados a una tarea. Sin embargo, a veces, quieres encontrar todos los vehículos que cumplan con incluso si es necesario revisar los resultados. ListVehicles es diseñadas para ese caso de uso.

La API de ListVehicles te permite encontrar todos los vehículos que cumplan con algunas opciones de solicitud. La API de ListVehicles muestra una lista paginada de vehículos en proyecto que cumpla con algunos requisitos.

Para filtrar los atributos de vehículos, consulta lo siguiente: Consulta de filtrado de vehículos.

Ejemplo

En este ejemplo, se filtran los vehicle_type y los atributos con el String filter.

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

La API de Trip y el ciclo de vida son similares a la API de Vehicle y el ciclo de vida. El proveedor de transporte compartido es responsable de crear viajes con Fleet Engine interfaces. Fleet Engine brinda un servicio de RPC, TripService y recursos de REST, provider.trips de Google Cloud. Estas interfaces permiten la creación de entidades de Viaje, las solicitudes de información, la búsqueda de la aplicación, la funcionalidad y la capacidad de actualización.

Un Trip tiene un campo de estado para hacer un seguimiento de su progreso a lo largo del ciclo de vida. Los valores se mueven de NEW a COMPLETE más CANCELED y UNKNOWN_TRIP_STATUS de Google Cloud. Consulta trip_status para RPC. o TripStatus para REST.

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

Tu servicio puede actualizar el viaje a CANCELED desde cualquiera de estos estados. Cuando tu servicio crea un viaje, el motor establece el estado como NEW. R vehicle_id es opcional. Al igual que con los vehículos, los servicios borran los viajes sin asignar automáticamente después de siete días sin una actualización. Si tu servicio intenta crear un viaje con una ID existente, se mostrará un error. Un viaje se considera “activo” si está en un estado que no es COMPLETE ni CANCELED. Esta distinción es importante en el campo active_trips de la entidad Vehicle y SearchTripsRequest.

Tu servicio solo puede cambiar el vehicle_id asignado a un viaje cuando este está activo. Por ejemplo, puedes hacerlo cuando un conductor cancela un viaje mientras está en ruta y el viaje se reasigna a un vehículo diferente.

El estado es importante cuando se implementa la verificación la asistencia para viajes. Esta compatibilidad permite que el Proveedor asigne un viaje nuevo a un Vehículo mientras el Vehículo está en un Viaje activo. El código para crear un viaje consecutivo es lo mismo que un viaje único y utiliza las mismas el ID del vehículo. Fleet Engine agrega el origen y el destino del nuevo viaje al los puntos de referencia del vehículo. Para obtener más información sobre viajes consecutivos, consulta Crea viajes con varios puntos de referencia.

Puntos de referencia restantes del viaje

La entidad Trip contiene un campo repetido de TripWaypoint (RPC | REST). llamada remainingWaypoints(RPC | REST) Este campo incluye todos los puntos de referencia que el vehículo deberá recorrer en orden. antes del punto de llegada final de este viaje. Calcula a partir de Puntos de referencia restantes del vehículo. En los casos de uso Back-to-Back-to-Back-to-Back-To-Back-To-Back-To-Back-to-Back-to-Back-to-Back-to-Back-to-Back-to-Back-to-Back-to-back y otros viajes que se recorrerán antes de este viaje, pero excluye cualquier punto de referencia después de este viaje. El punto de referencia en la lista se puede identificar por su TripId. y WaypointType.

La relación entre el estado del viaje y los puntos de referencia restantes del vehículo

Los puntos de referencia restantes del vehículo (RPC | REST) cuando Fleet Engine recibe una solicitud de cambio de estado de viaje. El El punto de referencia anterior se quitará de la lista de puntos de referencia restantes del Vehículo cuando tripStatus(RPC | REST) se cambia de otro estado a ENROUTE_TO_XXX. Es decir, cuando el estado del viaje cambia de ENROUTE_TO_PICKUP a ARRIVED_AT_PICKUP, el punto de partida seguirá estando en la lista de puntos de referencia restantes del vehículo, pero cuando el viaje el estado cambie a ENROUTE_TO_INTERMEDIATE_DESTINATION o ENROUTE_TO_DROPOFF, el punto de partida se quitará de los puntos de referencia restantes del vehículo.

Esto es igual para ARRIVED_AT_INTERMEDIATE_DESTINATION y ENROUTE_TO_INTERMDEDIATE_DESTINATION. Cuando ARRIVED_AT_INTERMEDIATE_DESTINATION, el destino intermedio actual no se quitará de las rutas restantes de referencia hasta que el vehículo informe que se está dirigiendo al siguiente punto de referencia.

Cuando el estado del viaje cambie a COMPLETED, no se mostrarán puntos de referencia desde este viaje en la lista de puntos de referencia restantes del vehículo.

INSTRUCTIVO: Cómo crear un viaje

Se debe crear una entidad Trip para que se pueda hacer un seguimiento de cada solicitud de viaje para los vehículos de la flota. Usa el extremo CreateTrip con CreateTripRequest. para crear un Viaje.

Los siguientes atributos son obligatorios para crear un viaje:

• parent: Es una cadena que incluye el ID del proveedor que se creó cuando se creó Se creó el proyecto de la nube.
• trip_id: Es una cadena que crea el proveedor de transporte compartido.
• trip: Contenedor con metadatos básicos que describen el viaje.
  • trip_type: Es una enumeración que indica si el viaje podría tener otros pasajeros. de un origen y un destino diferentes en el mismo vehículo (SHARED) o solo una parte (EXCLUSIVE).
  • pickup_point: TerminalLocation que representa el punto de origen del viaje. Consulta la referencia de RPC. o referencia de REST

Cuando creas un viaje, puedes proporcionar los siguientes elementos: number_of_passengers y dropoff_point. y vehicle_id. Aunque estos campos no son obligatorios, si los proporcionas, se retienen. Se ignoran todos los demás campos Viaje. Por ejemplo, todos los viajes comienza con una trip_status de NEW, incluso si pasas una trip_status de CANCELED en la solicitud de creación.

Ejemplo

En el siguiente ejemplo, se crea un viaje al Grand Indonesia East Mall. El viaje es exclusivo para dos pasajeros. El provider_id de Trip debe ser el mismo que el ID del proyecto. En el ejemplo, el proveedor de transporte compartido creó el Proyecto de Google Cloud, project-id. Este proyecto debe tener Cuentas de servicio que se usan para llamar a Fleet Engine. El estado del viaje es NEW.

Más tarde, una vez que el servicio asocia el viaje a un vehículo, puede llamar a UpdateTrip y cambia el valor de vehicle_id cuando el viaje está asignado a un vehículo.

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

Registros de Google Cloud Platform para la creación de viajes

La API de Fleet Engine escribe una entrada de registro usando los registros de la plataforma de Google Cloud cuando un al extremo CreateTrip. La entrada de registro incluye información sobre los valores de la solicitud CreateTrip. Si la llamada si tiene éxito, también incluirá información sobre el Trip que se mostró.

Instructivo: Actualiza un viaje

La entidad Trip contiene campos que permiten el seguimiento por parte del servicio y para informando el progreso del viaje mediante el SDK del conductor y al SDK del consumidor. Para actualizar las propiedades, usa UpdateTripRequest. mensaje. Esto actualizará los campos Viaje según el field_mask de la solicitud. Consulta UpdateTripRequest.

El proveedor de transporte compartido es responsable de actualizar los siguientes atributos:

• Estado del viaje.
• El ID del vehículo. ya sea en el momento de la creación o después de hacer coincidir el vehículo con una viaje.
• Cambios en el punto de partida, el destino o los puntos de referencia.

Fleet Engine actualiza automáticamente los siguientes campos cuando se usa el Función de viajes compartidos a través del SDK de Driver o del consumidor:

• Rutas
• ETA
• Distancia restante
• Ubicación del vehículo
• Puntos de referencia restantes

Consulta Tripen RPC o Resource.Trip en REST.

Registros de Google Cloud Platform para las actualizaciones de viaje

La API de Fleet Engine escribe una entrada de registro usando los registros de la plataforma de Google Cloud cuando un al extremo UpdateTrip. La entrada de registro incluye información sobre los valores de la solicitud UpdateTrip. Si la llamada se realiza correctamente, también incluirá información sobre el Trip que se mostró.

Instructivo: Busca viajes

Fleet Engine admite la búsqueda de viajes. Como se indicó anteriormente, un Viaje se borra automáticamente después de siete días, por lo que SearchTrips no exponer un historial completo de todos los viajes.

Si bien SearchTrips es una API flexible, en la siguiente lista se consideran dos casos de uso.

• Determina los viajes activos de un vehículo: El Proveedor puede determinar los viajes activos actualmente de un vehículo. En SearchTripsRequest, el elemento vehicle_id se establece en el vehículo en cuestión y active_trips_only se debe establecer en true.

• Conciliación del estado del proveedor y del motor de flota: El proveedor puede utilizar SearchTrips para garantizar que su estado de viaje y el de Fleet Engine coincidan. Esto es muy importante para TripStatus. Si el estado de un viaje asignado a un Vehículo no está configurado correctamente en COMPLETE o CANCELED, el Vehículo no se incluye en SearchVehicles.

Para usar SearchTrips de esta manera, deja vehicle_id vacío y configura active_trips_only en true y establece minimum_staleness en un tiempo mayor que la mayoría de las duraciones de los viajes. Por ejemplo, puedes usar una hora. Los resultados incluyen Viajes que no COMPLETA ni CANCELADA, y no se actualizaron en más de una hora. El proveedor debe examinar estos Viajes para asegurarse de que su estado en Fleet Engine sea correctamente actualizados.

Soluciona problemas

En el caso de un error DEADLINE_EXCEEDED, el estado de Fleet Engine es desconocidos. El proveedor debe volver a llamar a CreateTrip, lo que muestra un 201 (CREATED) o 409 (CONFLICT). En el último caso, la solicitud anterior se realizó correctamente antes del DEADLINE_EXCEEDED. Consulta las guías de la API de consumidor para obtener más información sobre cómo manejar los errores de los viajes: Android o iOS.

Asistencia para viajes compartidos

Puedes asignar varios viajes con SHARED a un vehículo que admita TripType.SHARED. Debes especificar el orden de todos los puntos de referencia no aprobados para todos los Viajes asignados a el Vehículo de este viaje compartido a través de Trip.vehicle_waypoints cuando asignes el vehicle_id para un viaje compartido (en una solicitud de CreateTrip o UpdateTrip). Consulta vehicle_waypoints para RPC. o vehicleWaypoints para REST.

Compatibilidad con varios destinos

Identifica un destino intermedio

Los campos intermediateDestinations y intermediateDestinationIndex en Trip (RPC | REST) se combinan para indicar el destino.

Actualizar destino intermedio

Puedes actualizar los destinos intermedios a través de UpdateTrip. Durante la actualización de destinos intermedios, debes brindar una lista completa de ellos, incluidos los visitados, no solo el que se acaba de agregarse o modificarse. Cuando intermediateDestinationIndex apunta a un índice posterior a la posición de destino intermedio recién agregado/modificado, el destino intermedio nuevo/actualizado el destino no se agregará a la waypoints del Vehículo ni a la remainingWaypoints del Viaje. Esto se debe a que cualquier destino intermedio anterior a intermediateDestinationIndex se tratarán como ya visitados.

Cambios en el estado del viaje

El campo intermediateDestinationsVersion (RPC | REST) obligatorio en la solicitud de actualización del estado del viaje enviada a Fleet Engine para indicar ya pasó un destino intermedio. El destino intermedio objetivo se especifica a través del campo intermediateDestinationIndex. Cuando tripStatus (RPC | REST) es ENROUTE_TO_INTERMEDIATE_DESTINATION, es un número entre [0..N-1] indica qué destino intermedio cruzará el vehículo. Cuando tripStatus sea ARRIVED_AT_INTERMEDIATE_DESTINATION, un número entre [0..N-1] indica en qué destino intermedio se encuentra el vehículo.

Ejemplo

El siguiente ejemplo de código demuestra cómo actualizar el estado de un viaje a Enruta. a su primer destino intermedio, suponiendo que creaste un un viaje con varios destinos y este pasó su punto de partida.

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

La API de Fleet Engine usa Google Cloud Pub/Sub para publicar notificaciones sobre el tema creado por el consumidor de Google Cloud Proyecto. Pub/Sub no está habilitado de forma predeterminada para Fleet Engine en tu cuenta de Google Cloud en un proyecto final. Presenta un caso de asistencia o comunícate con tu Ingeniero de Atención al cliente para habilitar Pub/Sub.

Para crear un tema en tu proyecto de Cloud, sigue estas instrucciones. El ID del tema debe ser “fleet_engine_notifications”.

El tema debe crearse en el mismo proyecto de Cloud que llama a Fleet Engine APIs

Una vez que crees el tema, deberás otorgarle a la API de Fleet Engine permiso para publicar en el tema. Para ello, haz clic en el tema que acabas de crear y agregar un permiso nuevo. Es posible que tengas que hacer clic en MOSTRAR PANEL DE INFORMACIÓN para abrir el editor de permisos. La principal debe ser geo-fleet-engine@system.gserviceaccount.com. y el rol debe ser Pub/Sub publisher.

Si deseas configurar tu proyecto de Cloud para que se suscriba a las notificaciones, sigue estos pasos: sigue estas instrucciones

La API de Fleet Engine publicará cada notificación en dos datos diferentes formatos, protobuf y json El formato de datos para cada notificación se indica en el Atributos de PubsubMessage con la clave como data_format y el valor como protobuf o json.

Esquema de notificación:

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

• Vehículo
• 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"
    }
  }
}