更新車輛欄位

本文將介紹在建立及管理車輛時，可以更新的重要車輛欄位。

  • vehicle_state：判斷車輛是否可供新行程使用。
  • vehicle_type：建立車輛時的必填欄位。這個欄位也可以做為車輛比對的篩選條件。如要進一步瞭解如何設定這個欄位，請參閱「建立車輛」一文。
  • attributes[]：VehicleAttribute 類型的選用陣列。您可以用這些條件定義自訂條件，在搜尋或刊登車輛時強化篩選行為。
  

如需車輛欄位的完整清單，請參閱：

車輛狀態欄位

系統可以將車輛狀態設為 OFFLINE 或 ONLINE。舉例來說，您可以將車輛狀態設為每天上午 9 點的 ONLINE，以及每天下午 5 點的 OFFLINE。

離線模式 ONLINE 模式
使用 OFFLINE 表示車輛不接受新的行程。請注意，在這個狀態下，車輛仍可完成指派的行程。
  • 在 ONLINE 狀態下建立的 Vehicle，可能會立即傳回 SearchVehicles 查詢的回應。詳情請參閱「搜尋車輛」一文。
  • 在 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 管理員 權限。

範例：啟用新的行程類型和自訂屬性

這個範例會為車輛啟用 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

後續步驟