更新车辆字段

本文档介绍了您在创建和管理车辆时可以更新的重要车辆字段。

  • vehicle_state：确定车辆是否可供新行程使用。
  • vehicle_type：创建车辆时必填字段。 此字段还可用作车辆匹配的过滤条件。 如需详细了解如何设置此字段，请参阅创建车辆。
  • attributes[]：VehicleAttribute 类型的可选数组。您可以使用这些属性来定义自定义条件，以便在搜索或展示车辆时增强过滤行为。
  

如需查看车辆字段的完整列表，请参阅：

“车辆状态”字段

您的系统可以将车辆状态设置为 OFFLINE 或 ONLINE。例如，您可以将车辆状态设为每天上午 9 点为 ONLINE，每天下午 5 点为 OFFLINE。

离线模式 在线模式
使用 OFFLINE 指示车辆不接受新的行程。请注意，车辆在这种状态下仍可完成分配的行程。
  • 系统可能会立即在响应 SearchVehicles 查询时返回在 ONLINE 状态下创建的 Vehicle。如需了解详情，请参阅搜索车辆。
  • 在 ONLINE 状态下创建的车辆应在 CreateVehicle 调用中使用 last_location 字段。

“车辆属性”字段

使用车辆 attributes 字段创建自定义条件，让您的消费者或车队运营商能够通过更多搜索条件查找车队中的车辆。与仅使用其他车辆字段的搜索条件相比，这可以增强应用提供更准确车辆匹配的能力。每辆车最多可以有 100 个属性，每个属性都必须具有唯一的键。值可以是字符串、布尔值或数字。

例如，您可以声明一个名为 class 的自定义属性，以区分不同类别的共享车辆。您可以使用以下字符串值来表示车辆类别级别：ECONOMY、STANDARD 和 LUXURY。

不过，自定义属性值不必互斥。您可能需要使用“允许携带宠物”“禁止吸烟”和“可以长途旅行”等条件。其中每个属性都可以是使用布尔值的单独自定义属性。您可以为给定车辆分配全部三个这些自定义属性，并将 class 自定义属性设置为适当的字符串值。

以这种方式使用属性可以为您提供各种功能，这些功能对于查找满足特定需求的行程的车辆非常有用。如需了解如何将自定义属性用作查询过滤条件，请参阅搜索车辆。

更新车辆属性

您可以使用 UpdateVehicle 或 UpdateVehicleAttributes 更新车辆属性。每个 attributes 键对每辆车只能有一个值。您可以在字段遮罩中使用 attributes 声明自定义车辆属性，然后根据以下方法提供值。

UpdateVehicle UpdateVehicleAttributes
此 API 不支持仅更新单个属性。使用此方法时，如果在字段掩码中使用 attributes 字段，系统会为车辆重新声明整个集的车辆属性。这会导致覆盖字段掩码中未明确包含的任何现有属性。如果您使用此方法声明新的自定义属性，则还必须重新声明您希望车辆保留的每个自定义属性。如果您在字段掩码中排除了 attributes，则此方法会保留之前为车辆定义的现有自定义属性。如果您在字段掩码中使用 attributes，但未设置值，则相当于从车辆中移除所有自定义属性。 此方法接受要更新的特定属性列表。该请求仅会更新或添加字段掩码中指定的属性。未指定的现有属性将保持不变。

更新车辆字段示例

本部分介绍了如何使用 UpdateVehicleRequest 更新车辆字段，其中包含一个 update_mask 来指明要更新的字段。如需了解详情，请参阅协议缓冲区文档中的字段掩码部分。

对 last_location 以外的字段进行更新需要 Fleet Engine On-demand Admin 权限。

示例：启用新的行程类型和自定义属性

此示例为车辆启用了 back_to_back 行程，并指定了一个新的属性：class。如前面更新车辆属性中所述，若要使用此方法更新 attributes 字段，您需要指明要保留的所有自定义属性。因此，该示例显示了写入的 cash_only 值，以防止其在指定 attributes 字段的更新操作期间被覆盖。

若要仅更新一个键值对特性对的值，请改用 UpdateVehicleAttributes 方法，并且不要在 UpdateVehicle 请求的字段掩码中包含 attribute 字段。

请参阅 gRPC 和 REST 的 providers.vehicles.update 参考文档。

gRPC

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("class").setValue("ECONOMY").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_state")
        .addPaths("attributes")
        .addPaths("back_to_back_enabled"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

REST

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "class", "value": "LUXURY"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

后续步骤