更新車輛欄位

注意： 建構車輛要求前，請參閱「簡介」中「車輛要求」一節的規定。

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

如需車輛欄位的完整清單，請參閱： Vehicle message (gRPC) Vehicle resource (REST)

車輛狀態欄位

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

離線模式	線上模式
使用 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，指出要更新的欄位。詳情請參閱通訊協定緩衝區說明文件的欄位遮罩部分。

注意： update_mask 必須一律設定。如果 update_mask 欄位空白，Fleet Engine 會拒絕要求。

如要更新 last_location 以外的欄位，則須具備 Fleet Engine 隨選管理員權限。

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

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

後續步驟

• 更新車輛位置