此页面由 Cloud Translation API 翻译。

更新行程并管理其状态

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

行程更新基础知识

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

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

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

UpdateTrip() 方法：gRPC 或 REST
UpdateTripRequest message：仅限 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 之前成功完成。

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

后续步骤

查找行程