更新行程并管理其状态

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

行程更新基础知识

在以下情况下，您的系统会使用车队引擎更新行程：

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

如需更新行程，请使用 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）时，您需要在车队引擎中更新行程状态。行程生命周期始终以状态值 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 之前成功。

请参阅适用于 Android 或 iOS 的 Consumer SDK 中的网络错误列表。

后续步骤