更新行程及管理狀態

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

行程更新基本概念

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

  • 在行程建立後指派車輛。
  • 行程狀態變更時，例如車輛通過途中的航點。
  • 更新行程欄位，例如乘客人數和下車地點。

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

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

請使用專案服務帳戶的適當憑證，如「Fleet Engine：服務帳戶角色」一文所述。

更新行程欄位

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

使用欄位遮罩

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

使用車輛 ID 更新行程

您必須使用車輛 ID 設定行程，Fleet Engine 才能沿著路線追蹤車輛。下列程式碼範例示範如何使用車輛 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 的狀態不明。如要調查這個問題，請先使用您要更新或監控的相同行程 ID，再次呼叫 CreateTrip。這應該會傳回 201 (CREATED) 或 409 (CONFLICT)。在後者中，先前的要求會在 DEADLINE_EXCEEDED 之前成功。

請參閱 Android 版或 iOS 版 Consumer SDK 的網路錯誤清單。

後續步驟