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 del campo per impostare i campi pertinenti per un viaggio. Presuppone che tu abbia configurato Fleet Engine come descritto in questo sito e che tu stia lavorando con un veicolo assegnato a un viaggio.

Nozioni di base sull'aggiornamento dei viaggi

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

  • Quando assegni un veicolo a un viaggio dopo la sua creazione.
  • Quando lo stato del viaggio cambia, ad esempio quando il veicolo passa attraverso i waypoint.
  • Quando aggiorni i campi del viaggio, ad esempio il numero di passeggeri e il punto di riconsegna.

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

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

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

Aggiornare i campi del viaggio

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

Utilizzare le maschere del campo

Le maschere del campo consentono ai chiamanti dell'API di elencare i campi che una richiesta deve o deve aggiornare. L'utilizzo di un FieldMask evita lavori non necessari e migliora le prestazioni. Fleet Engine utilizza le maschere del campo per aggiornare i campi in tutte le risorse.

Aggiornare il viaggio con l'ID veicolo

Devi configurare un viaggio con un ID veicolo in modo che Fleet Engine possa monitorare il veicolo lungo il suo percorso. Il seguente esempio di codice mostra come aggiornare il viaggio 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 del viaggio per i viaggi

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

Esempio di aggiornamento del viaggio

Di seguito viene illustrato come aggiornare lo stato del viaggio per un viaggio back-to-back 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 di viaggio

Quando aggiorni o cerchi viaggi esistenti, potresti riscontrare un errore DEADLINE_EXCEEDED, nel qual caso lo stato di Fleet Engine è sconosciuto. Per esaminare il problema, chiama di nuovo CreateTrip utilizzando lo stesso ID viaggio 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 di DEADLINE_EXCEEDED.

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

Passaggi successivi