此页面由 Cloud Translation API 翻译。

更新行程并管理其状态

本文档介绍了如何更新行程并管理其状态，其中涉及使用字段掩码为行程设置相关字段。本文假定您已按照本网站中的说明设置车队引擎，并且正在使用分配给行程的车辆。

行程更新基本信息

在以下情况下，您的系统会使用 Fleet Engine 更新行程：

在行程创建后将车辆分配给行程。
当行程状态发生变化时；例如，当车辆经过航点时。
更新行程字段时，例如乘客人数和下车点。

如需更新行程，请使用 gRPC 和 REST 发送请求。

UpdateTrip() 方法：gRPC 或 REST
UpdateTripRequest 消息：仅限 gRPC

使用项目服务账号的适当凭据，如车队引擎：服务账号角色中所述。

更新行程字段

您可以更新创建单个目的地行程中的行程字段中所述的任何行程字段。例如，创建行程后，通常的做法是先查找车辆，然后更新行程 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）时，您需要在车队引擎中更新行程状态。行程生命周期始终以状态值 NEW 开头，并以值 COMPLETE 或 CANCELED 结尾。

行程更新示例

以下示例演示了如何在车队引擎中更新接连行程的的行程状态。

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 错误的情况，在这种情况下，车队引擎的状态是未知的。如需调查此问题，请先使用您尝试更新或监控的同一行程 ID 再次调用 CreateTrip。这应该会返回 201（已创建）或 409（冲突）。在后一种情况下，上一个请求在 DEADLINE_EXCEEDED 之前成功。

查看 Consumer SDK 中的网络连接错误列表（Android 或 iOS）。

后续步骤

查找行程