Aggiornare le corse e gestire il loro stato

Questo documento descrive come aggiornare un viaggio e gestirne lo stato, il che comporta l'utilizzo di una maschera di campo per impostare i campi pertinenti per un viaggio. Si presume che abbia configurato Fleet Engine come descritto in questo sito e che stia lavorando con un veicolo assegnato a un viaggio.

Nozioni di base sugli aggiornamenti delle corse

Il sistema utilizza Fleet Engine per aggiornare un viaggio nelle seguenti situazioni:

  • Quando assegni un veicolo a un viaggio dopo averlo creato.
  • Quando cambia lo stato della corsa, ad esempio quando il veicolo passa per i waypoint.
  • Quando aggiorni i campi relativi alla corsa, ad esempio il numero di passeggeri e il punto di destinazione.

Per aggiornare un viaggio, invia una richiesta utilizzando gRPC e REST.

  • Metodo UpdateTrip(): gRPC o REST
  • Messaggio UpdateTripRequest: solo gRPC

Utilizza le credenziali appropriate per l'account di servizio del tuo progetto come descritto in Fleet Engine: ruoli dell'account di servizio.

Aggiorna i campi della corsa

Puoi aggiornare uno qualsiasi dei campi di viaggio descritti in Campi di viaggio in Creare un viaggio con una singola destinazione. Ad esempio, dopo aver creato un viaggio, è buona prassi trovare prima un veicolo e poi aggiornare il campo vehicle_id del viaggio per associarlo al veicolo che lo eseguirà.

Utilizzare le maschere dei campi

Le maschere di campo consentono agli utenti che chiamano l'API di elencare i campi che una richiesta deve o aggiornare. L'utilizzo di un FieldMask evita operazioni non necessarie e migliora le prestazioni. Fleet Engine utilizza le maschere di campo per aggiornare i campi in tutte le risorse.

Aggiornare la corsa con l'ID del veicolo

Devi configurare un viaggio con un ID veicolo in modo che il motore del parco risorse possa monitorare il veicolo lungo il suo percorso. Il seguente esempio di codice mostra come aggiornare la corsa con un ID veicolo.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()      // No need for the header.
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(FieldMask.newBuilder().addPaths("vehicle_id"))
        .build();

// Error handling.
// If the Fleet Engine has both a trip and vehicle with IDs, and if the
// credentials validate, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:                    // Neither the trip nor vehicle exist.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Gestire lo stato dei viaggi

Specifica lo stato di una corsa utilizzando uno dei valori di enumerazione TripStatus. Quando lo stato di un viaggio cambia, ad esempio da ENROUTE_TO_PICKUP a ARRIVED_AT_PICKUP, aggiornalo in Fleet Engine. Il ciclo di vita del viaggio inizia sempre con un valore di stato NEW e termina con un valore di COMPLETE o CANCELED.

Aggiornamento di una corsa di esempio

Di seguito viene mostrato come aggiornare lo stato di un viaggio con più corse in Fleet Engine.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to be updated.
Trip trip = Trip.newBuilder()
    .setTripStatus(TripStatus.ARRIVED_AT_PICKUP)
    .build();

// Trip update request
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder().addPaths("trip_status"))
    .build();

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

Puoi vedere altri esempi di come aggiornare i viaggi nella sezione Altri tipi di viaggio.

Gestire gli errori relativi ai viaggi

Quando aggiorni o trovi corse esistenti, potresti riscontrare un caso di errore DEADLINE_EXCEEDED, nel qual caso lo stato del motore del parco risorse è sconosciuto. Per effettuare accertamenti, chiama di nuovo CreateTrip utilizzando lo stesso ID corsa che stai tentando di aggiornare o monitorare. Dovrebbe restituire un codice 201 (CREATED) o 409 (CONFLICT). In quest'ultimo caso, la richiesta precedente è andata a buon fine prima del giorno DEADLINE_EXCEEDED.

Consulta l'elenco degli errori di rete nell'SDK Consumer per Android o iOS.

Passaggi successivi