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

更新行程及管理狀態

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

行程更新基本概念

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

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

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

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

請按照 Fleet Engine：服務帳戶角色一節中所述，為專案的服務帳戶使用適當的憑證。

更新行程欄位

您可以更新「建立單一目的地行程」中行程欄位所述的任何行程欄位。舉例來說，建立行程後，一般做法是先找到車輛，然後更新行程的 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)。

後續步驟

尋找行程