本頁面由 Cloud Translation API 翻譯而成。

更新行程及管理狀態

本文件說明如何更新行程並管理其狀態，這包括使用欄位遮罩來設定行程的相關欄位。這項操作假設您已按照本網站說明設定 Fleet Engine，並且使用指派給行程的車輛。

行程更新基本概念

在下列情況下，系統會使用 Fleet Engine 更新行程：

在行程建立後，將車輛指派給行程。
行程狀態變更時，例如車輛通過路線點。
更新行程欄位時，例如乘客人數和下車地點。

如要更新行程，請使用 gRPC 和 REST 傳送要求。

UpdateTrip() 方法：gRPC 或 REST
UpdateTripRequest 訊息：僅限 gRPC

請為專案的服務帳戶使用適當的憑證，如車隊引擎：服務帳戶角色一節所述。

更新行程欄位

您可以更新「建立單一目的地行程」一文中「行程欄位」一節所述的任何行程欄位。舉例來說，建立行程後，一般做法是先尋找車輛，然後更新行程 vehicle_id 欄位，將行程與將執行行程的車輛建立關聯。

使用欄位遮罩

欄位遮罩是 API 呼叫端用來列出要求應更新或更新的欄位。使用 FieldMask 可避免不必要的工作，並提升效能。Fleet Engine 會使用欄位遮罩更新所有資源的欄位。

更新含有車輛 ID 的行程

您必須設定行程的車輛 ID，讓車隊引擎沿著路線追蹤車輛。以下程式碼範例示範如何使用車輛 ID 更新行程。

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

管理行程的行程狀態

您可以使用其中一個 TripStatus 列舉值指定行程狀態。當行程狀態發生變更時 (例如從 ENROUTE_TO_PICKUP 變更為 ARRIVED_AT_PICKUP)，您可以在 Fleet Engine 中更新行程狀態。行程生命週期一律會從 NEW 的狀態值開始，並以 COMPLETE 或 CANCELED 的值結束。

行程更新範例

以下示範如何在 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;
}

您可以在「其他行程類型」部分查看其他行程更新方法的範例。

處理行程錯誤

更新或查看現有行程時，您可能會遇到 DEADLINE_EXCEEDED 錯誤，在這種情況下，Fleet Engine 的狀態會不明。如要調查這個問題，請先再次呼叫 CreateTrip，並使用您嘗試更新或監控的相同行程 ID。這應該會傳回 201 (CREATED) 或 409 (CONFLICT)。在後一種情況下，先前的要求在 DEADLINE_EXCEEDED 之前已成功。

請參閱 Consumer SDK 中的網路錯誤清單 (適用於 Android 或 iOS)。

後續步驟

尋找行程