建立及顯示多目的地行程

多目的地行程是指消費者安排的獨家行程，在抵達消費者原本要求抵達目的地之前，可能必須前往一或多個停靠站。

多目的地和單一目的地行程的主要差異，在於如果採用多目的地行程，行程業者可能會在出發地和下車地點之間建立一或多個停靠站。

本教學課程將逐步引導您建立多目的地行程。此外，應用程式也會說明如何將行程與消費者應用程式整合，讓客戶能透過手機查看行程進度。您可以使用 ConsumerSDK 進行這項整合。

必要條件

如要完成本教學課程，請務必完成下列步驟：

  1. 設定機群引擎。詳情請參閱「Fleet Engine：初始設定」。

  2. 將應用程式與 Driver SDK 整合。詳情請參閱 Android 適用的「初始化驅動程式 SDK」和 iOS 適用的驅動程式 SDK 整合指南。

  3. 整合消費者應用程式與 Consumer SDK。詳情請參閱 Android 版「開始使用 Consumer SDK」和 iOS 版「開始使用 Consumer SDK」一文。

  4. 設定授權權杖。如要進一步瞭解授權權杖，請參閱開始使用 Fleet Engine 指南中的建立 JSON Web Token 相關說明，及 Fleet Engine 的 Consumer SDK 說明文件中的驗證與授權。

步驟 1：在 Fleet Engine 中建立車輛

車輛是一種物件，代表車隊中的車輛。您必須在 Fleet Engine 中建立它們，才能在消費者應用程式中追蹤。

你可以透過下列兩種方法建立車輛：

gRPC
使用 CreateVehicleRequest 要求訊息呼叫 CreateVehicle() 方法。您必須具備 Fleet Engine 超級使用者權限才能呼叫 CreateVehicle()。
REST
呼叫 https://fleetengine.googleapis.com/v1/providers.vehicles.create。

注意事項

建立車輛時請留意下列注意事項。

  • 請務必將初始車輛狀態設為 OFFLINE。確保 Fleet Engine 可以找到你的車輛，以便進行行程比對。

  • 這輛車的 provider_id 必須與包含用來呼叫機群引擎的服務帳戶的 Google Cloud 專案 ID 相同。雖然多個服務帳戶可以存取同一個共乘供應商的 Fleet Engine，但 Fleet Engine 目前不支援來自存取相同車輛的不同 Google Cloud 專案的服務帳戶。

  • CreateVehicle() 傳回的回應包含 Vehicle 例項。如果執行個體未使用 UpdateVehicle() 更新，則系統會在七天後刪除該執行個體。您應先呼叫 GetVehicle() 再呼叫 CreateVehicle()，藉此確認車輛不存在。如果 GetVehicle() 傳回 NOT_FOUND 錯誤，則應繼續呼叫 CreateVehicle()。詳情請參閱「車輛及其生命週期」一文。

範例

以下供應商程式碼範例示範如何在 Fleet Engine 中建立車輛。

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

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))
    .build();

CreateVehicleRequest createVehicleRequest = CreateVehicleRequest.newBuilder()
    .setParent(parent)
    .setVehicleId("8241890")  // Vehicle ID assigned by solution provider.
    .setVehicle(vehicle)      // Initial state.
    .build();

// The Vehicle is created in the OFFLINE state, and no initial position is
// provided.  When the driver app calls the rideshare provider, the state can be
// set to ONLINE, and the driver app updates 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;
}

步驟 2：啟用位置追蹤功能

位置追蹤是指在行程期間追蹤車輛位置，駕駛應用程式將遙測資料傳送至 Fleet Engine，其中包含車輛目前位置。系統會使用這類持續更新的位置資訊串流，傳送沿途的車輛進度。位置追蹤功能啟用後，驅動程式應用程式會開始傳送此遙測資料，預設頻率為每五秒一次。

您可依下列方式啟用 Android 和 iOS 的位置追蹤功能：

範例

以下程式碼範例示範如何啟用位置追蹤功能。

Java

RidesharingVehicleReporter vehicleReporter = ...;

vehicleReporter.enableLocationTracking();

Kotlin

val vehicleReporter = ...

vehicleReporter.enableLocationTracking()

Swift

vehicleReporter.locationTrackingEnabled = true

Objective-C

_vehicleReporter.locationTrackingEnabled = YES;

步驟 3：將車輛的狀態設為「線上」

您可以將車輛的狀態設為 online，藉此讓車輛進入服務 (也就是讓車輛可以使用)，但必須先啟用位置追蹤功能，才能執行這項操作。

您可以針對 Android 和 iOS 裝置將車輛狀態設為線上狀態，方法如下：

範例

以下程式碼範例說明如何將車輛的狀態設為 ONLINE。

Java

vehicleReporter.setVehicleState(VehicleState.ONLINE);

Kotlin

vehicleReporter.setVehicleState(VehicleState.ONLINE)

Swift

vehicleReporter.update(.online)

Objective-C

[_vehicleReporter updateVehicleState:GMTDVehicleStateOnline];

步驟 4：在 Fleet Engine 中建立行程

如要建立多目的地行程，您必須建立 Trip 物件，就像針對單一目的地一樣。

行程是一個代表旅程的物件，為集合地理座標點，包括起點、路線控點和下車點。您必須為每個行程要求建立一個 Trip 物件，這樣系統才能比對要求和車輛，然後追蹤要求。

提供必要屬性

如要建立多目的地行程，您必須填寫下列欄位。

parent
包含提供者 ID 的字串。此 ID 必須與包含用於呼叫 Fleet Engine 的服務帳戶的 Google Cloud 專案 ID 相同
trip_id
你建立的字串，專門用來識別這個行程。
trip
要建立的`Trip` 物件。

您必須在傳遞至 CreateTripRequest 的 Trip 物件中設定下列欄位：

trip_type
TripType.EXCLUSIVE
pickup_point
行程的起點，
dropoff_point
行程的下車地點，建立行程時不必提供這個欄位，之後可呼叫「UpdateTrip」來設定。
intermediate_destinations
司機在上下車之間抵達的中階目的地清單，如同下車，這個欄位在建立行程時不需要，只要呼叫「UpdateTrip」即可。

範例

以下後端整合範例示範如何建立含有上車地點、下車地點和一個中繼目的地的專屬多目的地行程。

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip initial settings.
String parent = "providers/" + PROJECT_ID;

Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE)
    .setPickupPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.195139).setLongitude(106.820826)))
    .setNumberOfPassengers(1)
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.1275).setLongitude(106.6537)))
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .build();

// Create the Trip request.
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_ID)  // Trip ID assigned by the Provider server.
    .setTrip(trip)       // Initial state is NEW.
    .build();

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

步驟 5：使用車輛 ID 和路線控點更新行程

您必須使用車輛 ID 設定行程，Fleet Engine 才能沿路線追蹤車輛。

附註

  • 如果建立行程時沒有指定下車地點或中繼目的地，你隨時可以執行這項操作。

  • 如果您需要在行程中變更車輛，就必須將行程的狀態改回新狀態，然後使用新的車輛 ID 更新行程 (如上所述)。

範例

以下後端整合範例示範如何更新行程，以便新增中繼目的地清單並設定車輛 ID。

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

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

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(
        FieldMask.newBuilder()
            .addPaths("intermediate_destinations")
            .addPaths("vehicle_id")
            .build())
    .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 PERMISSION_DENIED:
      break;
  }
  return;
}

步驟 6：在消費者應用程式中監聽行程更新

  • 針對 Android，您可以從 TripModelManager 取得 TripModel 物件，並註冊 TripModelCallback 事件監聽器，藉此監聽行程的資料更新。

  • 針對 iOS，您可以從 GMTCTripService 取得 GMTCTripModel 物件，並註冊 GMTCTripModelSubscriber 訂閱者，藉此監聽行程中的資料更新。

TripModelCallback 事件監聽器和 GMTCTripModelSubscriber 訂閱者可讓應用程式根據自動重新整理時間間隔，定期接收行程進度更新。只有變更的值才能觸發回呼。否則回呼會保持靜音。

無論資料變更為何，系統一律會呼叫 TripModelCallback.onTripUpdated() 和 tripModel(_:didUpdate:updatedPropertyFields:) 方法。

範例 1

下列程式碼範例示範如何從 TripModelManager/GMTCTripService 取得 TripModel，並為其設定事件監聽器。

Java

// Start journey sharing after a trip has been created via Fleet Engine.
TripModelManager tripModelManager = consumerApi.getTripModelManager();

// Get a TripModel object.
TripModel tripModel = tripModelManager.getTripModel(tripName);

// Register a listener on the trip.
TripModelCallback tripCallback = new TripModelCallback() {
  ...
};
tripModel.registerTripCallback(tripCallback);

// Set the refresh interval.
TripModelOptions tripModelOptions = TripModelOptions.builder()
    .setRefreshInterval(5000) // interval in milliseconds, so 5 seconds
    .build();
tripModel.setTripModelOptions(tripModelOptions);

// The trip stops auto-refreshing when all listeners are unregistered.
tripModel.unregisterTripCallback(tripCallback);

Kotlin

// Start journey sharing after a trip has been created via Fleet Engine.
val tripModelManager = consumerApi.getTripModelManager()

// Get a TripModel object.
val tripModel = tripModelManager.getTripModel(tripName)

// Register a listener on the trip.
val tripCallback = TripModelCallback() {
  ...
}

tripModel.registerTripCallback(tripCallback)

// Set the refresh interval.
val tripModelOptions =
  TripModelOptions.builder()
    .setRefreshInterval(5000) // interval in milliseconds, so 5 seconds
    .build()

tripModel.setTripModelOptions(tripModelOptions)

// The trip stops auto-refreshing when all listeners are unregistered.
tripModel.unregisterTripCallback(tripCallback)

Swift

let tripService = GMTCServices.shared().tripService

// Create a tripModel instance for listening for updates from the trip
// specified by the trip name.
let tripModel = tripService.tripModel(forTripName: tripName)

// Register for the trip update events.
tripModel.register(self)

// Set the refresh interval (in seconds).
tripModel.options.autoRefreshTimeInterval = 5

// Unregister for the trip update events.
tripModel.unregisterSubscriber(self)

Objective-C

GMTCTripService *tripService = [GMTCServices sharedServices].tripService;

// Create a tripModel instance for listening for updates from the trip
// specified by the trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];

// Register for the trip update events.
[tripModel registerSubscriber:self];

// Set the refresh interval (in seconds).
tripModel.options.autoRefreshTimeInterval = 5;

// Unregister for the trip update events.
[tripModel unregisterSubscriber:self];

範例 2

下列程式碼範例示範如何設定 TripModelCallback 事件監聽器和 GMTCTripModelSubscriber 訂閱者。

Java

// Implements a callback for the trip model so your app can listen for trip
// updates from Fleet Engine.
TripModelCallback subscriber =
  new TripModelCallback() {

    @Override
    public void onTripStatusUpdated(TripInfo tripInfo, @TripStatus int status) {
      // ...
    }

    @Override
    public void onTripActiveRouteUpdated(TripInfo tripInfo, List<LatLng> route) {
      // ...
    }

    @Override
    public void onTripVehicleLocationUpdated(
        TripInfo tripInfo, @Nullable VehicleLocation vehicleLocation) {
      // ...
    }

    @Override
    public void onTripPickupLocationUpdated(
        TripInfo tripInfo, @Nullable TerminalLocation pickup) {
      // ...
    }

    @Override
    public void onTripPickupTimeUpdated(TripInfo tripInfo, @Nullable Long timestampMillis) {
      // ...
    }

    @Override
    public void onTripDropoffLocationUpdated(
        TripInfo tripInfo, @Nullable TerminalLocation dropoff) {
      // ...
    }

    @Override
    public void onTripDropoffTimeUpdated(TripInfo tripInfo, @Nullable Long timestampMillis) {
      // ...
    }

    @Override
    public void onTripETAToNextWaypointUpdated(
        TripInfo tripInfo, @Nullable Long timestampMillis) {
      // ...
    }

    @Override
    public void onTripActiveRouteRemainingDistanceUpdated(
        TripInfo tripInfo, @Nullable Integer distanceMeters) {
      // ...
    }

    @Override
    public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
      // ...
    }

    @Override
    public void onTripUpdated(TripInfo tripInfo) {
      // ...
    }

    @Override
    public void onTripRemainingWaypointsUpdated(
        TripInfo tripInfo, List<TripWaypoint> waypointList) {
      // ...
    }

    @Override
    public void onTripIntermediateDestinationsUpdated(
        TripInfo tripInfo, List<TerminalLocation> intermediateDestinations) {
      // ...
    }

    @Override
    public void onTripRemainingRouteDistanceUpdated(
        TripInfo tripInfo, @Nullable Integer distanceMeters) {
      // ...
    }

    @Override
    public void onTripRemainingRouteUpdated(TripInfo tripInfo, List<LatLng> route) {
      // ...
    }
  };

Kotlin

// Implements a callback for the trip model so your app can listen for trip
// updates from Fleet Engine.
val subscriber =
  object : TripModelCallback() {
    override fun onTripStatusUpdated(tripInfo: TripInfo, status: @TripStatus Int) {
      // ...
    }

    override fun onTripActiveRouteUpdated(tripInfo: TripInfo, route: List<LatLng>) {
      // ...
    }

    override fun onTripVehicleLocationUpdated(
      tripInfo: TripInfo,
      vehicleLocation: VehicleLocation?
    ) {
      // ...
    }

    override fun onTripPickupLocationUpdated(tripInfo: TripInfo, pickup: TerminalLocation?) {
      // ...
    }

    override fun onTripPickupTimeUpdated(tripInfo: TripInfo, timestampMillis: Long?) {
      // ...
    }

    override fun onTripDropoffLocationUpdated(tripInfo: TripInfo, dropoff: TerminalLocation?) {
      // ...
    }

    override fun onTripDropoffTimeUpdated(tripInfo: TripInfo, timestampMillis: Long?) {
      // ...
    }

    override fun onTripETAToNextWaypointUpdated(tripInfo: TripInfo, timestampMillis: Long?) {
      // ...
    }

    override fun onTripActiveRouteRemainingDistanceUpdated(
      tripInfo: TripInfo,
      distanceMeters: Int?
    ) {
      // ...
    }

    override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
      // ...
    }

    override fun onTripUpdated(tripInfo: TripInfo) {
      // ...
    }

    override fun onTripRemainingWaypointsUpdated(
      tripInfo: TripInfo,
      waypointList: List<TripWaypoint>
    ) {
      // ...
    }

    override fun onTripIntermediateDestinationsUpdated(
      tripInfo: TripInfo,
      intermediateDestinations: List<TerminalLocation>
    ) {
      // ...
    }

    override fun onTripRemainingRouteDistanceUpdated(tripInfo: TripInfo, distanceMeters: Int?) {
      // ...
    }

    override fun onTripRemainingRouteUpdated(tripInfo: TripInfo, route: List<LatLng>) {
      // ...
    }
  }

Swift

class TripModelSubscriber: NSObject, GMTCTripModelSubscriber {

  func tripModel(_: GMTCTripModel, didUpdate trip: GMTSTrip?, updatedPropertyFields: GMTSTripPropertyFields) {
    // Update the UI with the new `trip` data.
    updateUI(with: trip)
    ...
  }

  func tripModel(_: GMTCTripModel, didUpdate tripStatus: GMTSTripStatus) {
    // Handle trip status did change.
  }

  func tripModel(_: GMTCTripModel, didUpdateActiveRoute activeRoute: [GMTSLatLng]?) {
    // Handle trip active route did update.
  }

  func tripModel(_: GMTCTripModel, didUpdate vehicleLocation: GMTSVehicleLocation?) {
    // Handle vehicle location did update.
  }

  func tripModel(_: GMTCTripModel, didUpdatePickupLocation pickupLocation: GMTSTerminalLocation?) {
    // Handle pickup location did update.
  }

  func tripModel(_: GMTCTripModel, didUpdateDropoffLocation dropoffLocation: GMTSTerminalLocation?) {
    // Handle drop off location did update.
  }

  func tripModel(_: GMTCTripModel, didUpdatePickupETA pickupETA: TimeInterval) {
    // Handle the pickup ETA did update.
  }

  func tripModel(_: GMTCTripModel, didUpdateDropoffETA dropoffETA: TimeInterval) {
    // Handle the drop off ETA did update.
  }

  func tripModel(_: GMTCTripModel, didUpdateRemaining remainingWaypoints: [GMTSTripWaypoint]?) {
    // Handle updates to the pickup, dropoff or intermediate destinations of the trip.
  }

  func tripModel(_: GMTCTripModel, didFailUpdateTripWithError error: Error?) {
    // Handle the error.
  }

  func tripModel(_: GMTCTripModel, didUpdateIntermediateDestinations intermediateDestinations: [GMTSTerminalLocation]?) {
    // Handle the intermediate destinations being updated.
  }

  ...
}

Objective-C

@interface TripModelSubscriber : NSObject <GMTCTripModelSubscriber>
@end

@implementation TripModelSubscriber

- (void)tripModel:(GMTCTripModel *)tripModel
            didUpdateTrip:(nullable GMTSTrip *)trip
    updatedPropertyFields:(GMTSTripPropertyFields)updatedPropertyFields {
  // Update the UI with the new `trip` data.
  [self updateUIWithTrip:trip];
  ...
}

- (void)tripModel:(GMTCTripModel *)tripModel didUpdateTripStatus:(enum GMTSTripStatus)tripStatus {
  // Handle trip status did change.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateActiveRoute:(nullable NSArray<GMTSLatLng *> *)activeRoute {
  // Handle trip route did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateVehicleLocation:(nullable GMTSVehicleLocation *)vehicleLocation {
  // Handle vehicle location did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdatePickupLocation:(nullable GMTSTerminalLocation *)pickupLocation {
  // Handle pickup location did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateDropoffLocation:(nullable GMTSTerminalLocation *)dropoffLocation {
  // Handle drop off location did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel didUpdatePickupETA:(NSTimeInterval)pickupETA {
  // Handle the pickup ETA did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateRemainingWaypoints:(nullable NSArray<GMTSTripWaypoint *> *)remainingWaypoints {
  // Handle updates to the pickup, dropoff or intermediate destinations of the trip.
}

- (void)tripModel:(GMTCTripModel *)tripModel didUpdateDropoffETA:(NSTimeInterval)dropoffETA {
  // Handle the drop off ETA did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel didFailUpdateTripWithError:(nullable NSError *)error {
  // Handle the error.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateIntermediateDestinations:
        (nullable NSArray<GMTSTerminalLocation *> *)intermediateDestinations {
  // Handle the intermediate destinations being updated.
}
…
@end

你隨時可以按照下列方式查看行程資訊：

步驟 7：在消費者應用程式中顯示歷程

您可以透過下列方式存取「共乘」和「外送」使用者介面元素 API：

範例

以下程式碼範例示範如何啟動旅程共用使用者介面。

Java

JourneySharingSession session = JourneySharingSession.createInstance(tripModel);
consumerController.showSession(session);

Kotlin

val session = JourneySharingSession.createInstance(tripModel)
consumerController.showSession(session)

Swift

let journeySharingSession = GMTCJourneySharingSession(tripModel: tripModel)
mapView.show(journeySharingSession)

Objective-C

GMTCJourneySharingSession *journeySharingSession =
    [[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];
[self.mapView showMapViewSession:journeySharingSession];

根據預設，Consumer SDK 只會顯示路線中的可用路段，但您可以選擇顯示其餘的路段，包括中繼目的地和下車地點。

如要顯示其他行程的路線控點資訊，可以使用以下方式存取與行程相關的所有路線控點：

步驟 8：在機群引擎中管理行程狀態

您可以使用其中一個 TripStatus 列舉值指定行程狀態。當行程狀態變更 (例如從 ENROUTE_TO_PICKUP 變更為 ARRIVED_AT_PICKUP) 時，您必須透過 Fleet Engine 更新行程狀態。行程狀態一律以 NEW 的值開頭，結尾則是 COMPLETE 或 CANCELED。詳情請參閱trip_status。

如果是多目的地行程，除了在處理單一目的地行程時更新行程狀態外，您也需要更新 intermediateDestinationIndex，並在每次到達中繼目的地時在更新要求中提供 intermediateDestinationsVersion。您必須使用 TripStatus 列舉中的下列狀態。

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

範例

以下後端整合範例示範如何建立已傳遞上車地點的多目的地行程，現在正在規劃前往第一個中繼目的地。

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

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

// Get the trip object from either the Fleet Engine or storage.
Trip trip = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Trip status cannot return to a previous state once it has passed.
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)

    // Enroute to the first intermediate destination.
    .setIntermediateDestinationIndex(0)

    // You must provide an intermediate_destinations_version to ensure that you
    // have the same intermediate destinations list as the Fleet Engine.
    .setIntermediateDestinationsVersion(
         trip.getIntermediateDestinationsVersion())
    .build();

// The 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:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // Either the trip status is invalid, or the
                               // intermediate_destinations_version doesn't
                               // match the Fleet Engine’s.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}