차량 attributes 필드를 사용하여 소비자가 다양한 검색 기준으로 차량을 찾을 수 있도록 맞춤 기준을 만드세요. 이를 통해 다른 차량 필드만을 기반으로 검색 기준을 사용하는 것보다 더 나은 차량 일치 항목을 제공하는 앱의 기능을 향상할 수 있습니다. 각 차량에는 최대 100개의 속성이 있을 수 있으며 각 속성에는 고유한 키가 있어야 합니다. 값은 문자열, 불리언 또는 숫자일 수 있습니다.
예를 들어 배송 차량이 운행하는 도시의 구역을 구분하기 위해 zone이라는 맞춤 속성을 선언할 수 있습니다. 1B, 2C, 3A과 같은 문자열 값을 사용하여 서로 다른 영역을 나타냅니다. 그런 다음 Fleet Tracking에서 필터를 사용하여 특정 구역에서 작업하는 차량만 해당 구역을 담당하는 운영자에게 표시할 수 있습니다.
하지만 맞춤 속성 값은 상호 배타적이지 않아도 됩니다. available-at-night 및 has-refrigeration과 같은 기준을 사용할 수 있습니다. 각각 부울 값을 사용하는 별도의 맞춤 속성일 수 있습니다. 특정 차량에는 이 세 가지 맞춤 속성이 모두 할당될 수 있으며, 지역 맞춤 속성은 적절한 문자열 값으로 설정됩니다.
차량 속성 업데이트
각 attributes 키에는 차량당 하나의 값만 있을 수 있습니다. 필드 마스크에서 attributes를 사용하여 맞춤 차량 속성을 선언한 다음 아래 방법에 따라 값을 제공합니다.
이 UpdateDeliveryVehicle API는 단일 속성만 업데이트하는 것을 허용하지 않습니다. 이 방법을 사용하면 필드 마스크에서 attributes 필드를 사용하는 경우 차량의 전체 집합이 차량에 대해 다시 선언됩니다. 이렇게 하면 필드 마스크에 명시적으로 포함되지 않은 기존 속성이 덮어쓰여집니다. 이 메서드를 사용하여 새 맞춤 속성을 선언하는 경우 차량이 유지하도록 하려는 모든 맞춤 속성도 다시 선언해야 합니다. 필드 마스크에서 attributes를 제외하면 이 메서드는 기존 맞춤 속성을 차량에 대해 이전에 정의된 대로 유지합니다.
필드 마스크에서 attributes을 사용하지만 값을 설정하지 않으면 차량에서 모든 맞춤 속성을 삭제하는 것과 같습니다.
차량 필드 업데이트 예시
이 섹션에서는 업데이트할 필드를 나타내는 update_mask가 포함된 UpdateDeliveryVehicleRequest를 사용하여 차량 필드를 업데이트하는 방법을 보여줍니다. 자세한 내용은 필드 마스크에 관한 프로토콜 버퍼 문서를 참고하세요.
last_location 이외의 필드를 업데이트하려면 Fleet Engine Delivery 관리자 권한이 필요합니다.
예: 맞춤 속성 설정
이 예에서는 새 속성 zone을 지정합니다. 앞서 차량 속성 업데이트에서 설명한 것처럼 이 방법을 사용하여 attributes 필드를 업데이트하려면 유지하려는 모든 맞춤 속성을 표시해야 합니다.
따라서 이 예에서는 attributes 필드를 지정하는 업데이트 작업 중에 덮어쓰지 않도록 available-at-night 값이 작성됩니다.
staticfinalStringPROJECT_ID="my-delivery-co-gcp-project";staticfinalStringVEHICLE_ID="vehicle-8241890";DeliveryServiceBlockingStubdeliveryService=DeliveryServiceGrpc.newBlockingStub(channel);// Vehicle settingsStringvehicleName="providers/"+PROJECT_ID+"/deliveryVehicles/"+VEHICLE_ID;DeliveryVehiclemyDeliveryVehicle=DeliveryVehicle.newBuilder().addAllAttributes(ImmutableList.of(DeliveryVehicleAttribute.newBuilder().setKey("zone").setValue("1B").build(),DeliveryVehicleAttribute.newBuilder().setKey("available-at-night").setValue("true").build())).build();// DeliveryVehicle requestUpdateDeliveryVehicleRequestupdateDeliveryVehicleRequest=UpdateDeliveryVehicleRequest.newBuilder()// No need for the header.setName(vehicleName).setDeliveryVehicle(myDeliveryVehicle).setUpdateMask(FieldMask.newBuilder().addPaths("attributes")).build();try{DeliveryVehicleupdatedDeliveryVehicle=deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);}catch(StatusRuntimeExceptione){Statuss=e.getStatus();switch(s.getCode()){caseNOT_FOUND:break;casePERMISSION_DENIED:break;}return;}
REST
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local# environmentcurl-XPATCH"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=attributes"\-H"Content-type: application/json"\-H"Authorization: Bearer ${JWT}"\--data-binary@- << EOM
{"attributes":[{"key":"zone","value":"1B"},
{"key":"available-at-night","value":"true"}]}EOM
[null,null,["최종 업데이트: 2025-08-31(UTC)"],[[["\u003cp\u003eThis document explains how to update vehicle fields, focusing on the \u003ccode\u003eattributes\u003c/code\u003e field for creating custom criteria to search and filter vehicles.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eattributes\u003c/code\u003e field allows you to define custom criteria for vehicles, such as zone or availability, to enhance search and filtering capabilities.\u003c/p\u003e\n"],["\u003cp\u003eWhen updating the \u003ccode\u003eattributes\u003c/code\u003e field, the entire set of attributes is re-declared, overwriting any pre-existing attribute not explicitly included.\u003c/p\u003e\n"],["\u003cp\u003eThe provided example demonstrates how to update vehicle fields, including setting custom attributes using the \u003ccode\u003eUpdateDeliveryVehicle\u003c/code\u003e API.\u003c/p\u003e\n"],["\u003cp\u003eUpdating fields other than \u003ccode\u003elast_location\u003c/code\u003e requires Fleet Engine Delivery Admin privileges.\u003c/p\u003e\n"]]],["Before creating vehicle requests, review the requirements. You can manage vehicle fields like `type` and `attributes[]`. Attributes allow custom criteria for filtering, supporting strings, booleans, or numbers, each vehicle can have up to 100 attributes, with unique keys. Updating attributes overwrites the entire set; all desired attributes must be re-declared. The `update_mask` should always be set to specify what is being updated. There are gRPC and REST examples to set a custom attribute for a vehicle.\n"],null,["| **Note:** **Before constructing a vehicle request** , read the requirements under [Vehicle requests](/maps/documentation/mobility/fleet-engine/essentials/vehicles#vehicle_requests) in the Introduction.\n\n|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| This document covers important vehicle fields you can update when creating and managing vehicles. - `type`: The type of this delivery vehicle. This impacts routes generated for this vehicle. - `attributes[]`: An option array of type [`DeliveryVehicleAttribute`](/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1#maps.fleetengine.delivery.v1.DeliveryVehicleAttribute). Use them to define custom criteria for vehicles in your service to enhance filtering behavior when searching or listing vehicles. | | For a complete list of vehicle fields, see: - [`DeliveryVehicle message`](/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1#deliveryvehicle) - [`DeliveryVehicle resource`](/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.deliveryVehicles) |\n\nVehicle attributes field\n\nUse the vehicle `attributes` field to create customized criteria to enable your\nconsumers or fleet operators to find vehicles in your fleet across a wider\nvariety of search criteria. This enhances the capabilities of your apps to\nprovide better vehicle matches over what you would from using search criteria\nbased solely on other vehicle fields. Each vehicle can have at most 100\nattributes, and each one must have a unique key. Values can be strings,\nbooleans, or numbers.\n\nFor example, you could declare a custom attribute called *zone* to\ndifferentiate which zone of the city your delivery vehicles operate in. You'd\nuse string values such as the following to represent different zones: `1B`,\n`2C`, and `3A`. You could then use a filter in Fleet Tracking to only show\nvehicles working in a specific zone to the operator responsible for that zone.\n\nHowever, custom attribute values don't have to be mutually exclusive. You might\nuse criteria such as *available-at-night* and *has-refrigeration* . Each of these\ncould be a separate custom attribute that uses boolean values. A given vehicle\ncould be assigned all three of these custom attributes along with the *zone*\ncustom attribute set to the appropriate string value.\n\nUpdate vehicle attributes\n\nEach `attributes` key can only have one value **per vehicle** . You declare\ncustom vehicle attributes using the `attributes` in the field mask, and then\nproviding values based on the method below.\n\nThis `UpdateDeliveryVehicle` API does not allow updating only a single\nattribute. When using this method, any use of the `attributes` field in the\nfield mask results in the **entire set** of vehicle attributes being re-declared\nfor the vehicle. This results in an overwrite of any pre-existing attribute not\nexplicitly included in the field mask. If you use this method to declare a new\ncustom attribute, you must also re-declare every custom attribute you want the\nvehicle to retain. If you exclude the `attributes` in the field mask, then this\nmethod leaves existing custom attributes as previously defined for the vehicle.\nIf you use `attributes` in the field mask, but without setting values, that is\nequivalent to removing all custom attributes from the vehicle.\n\nUpdate vehicle fields example\n\nThis section shows how to update vehicle fields using\n`UpdateDeliveryVehicleRequest`, which includes an `update_mask` to indicate\nwhich fields to update. See the Protocol Buffers documentation on\n[field masks](/maps/documentation/mobility/fleet-engine/essentials/vehicles/protobuf.dev/reference/cpp/api-docs/google.protobuf.util.field_mask_util) for details.\n| **Note:** The `update_mask` field should always be set. Not setting the `update_mask` field defaults to writing all fields. This can result in unintended behavior.\n\nUpdates to fields other than `last_location` require *Fleet Engine Delivery\nAdmin* privileges.\n\nExample: set custom attribute\n\nThis example specifies a new attribute: `zone`. As noted in\n[Update vehicle attributes](#update_vehicle_attributes) earlier, updating the `attributes` field using\nthis approach requires you to indicate all custom attributes you want to retain.\nTherefore the example shows a `available-at-night` value written to preserve it\nfrom being overwritten during an update operation that specifies the\n`attributes` field.\n\nSee the [providers.deliveryVehicles.patch](/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.deliveryVehicles/patch) reference. \n\ngRPC \n\n static final String PROJECT_ID = \"my-delivery-co-gcp-project\";\n static final String VEHICLE_ID = \"vehicle-8241890\";\n\n DeliveryServiceBlockingStub deliveryService =\n DeliveryServiceGrpc.newBlockingStub(channel);\n\n // Vehicle settings\n String vehicleName = \"providers/\" + PROJECT_ID + \"/deliveryVehicles/\" + VEHICLE_ID;\n DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()\n .addAllAttributes(ImmutableList.of(\n DeliveryVehicleAttribute.newBuilder().setKey(\"zone\").setValue(\"1B\").build(),\n DeliveryVehicleAttribute.newBuilder().setKey(\"available-at-night\").setValue(\"true\").build()))\n .build();\n\n // DeliveryVehicle request\n UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =\n UpdateDeliveryVehicleRequest.newBuilder() // No need for the header\n .setName(vehicleName)\n .setDeliveryVehicle(myDeliveryVehicle)\n .setUpdateMask(FieldMask.newBuilder()\n .addPaths(\"attributes\"))\n .build();\n\n try {\n DeliveryVehicle updatedDeliveryVehicle =\n deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);\n } catch (StatusRuntimeException e) {\n Status s = e.getStatus();\n switch (s.getCode()) {\n case NOT_FOUND:\n break;\n case PERMISSION_DENIED:\n break;\n }\n return;\n }\n\nREST \n\n # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local\n # environment\n curl -X PATCH \"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=attributes\" \\\n -H \"Content-type: application/json\" \\\n -H \"Authorization: Bearer ${JWT}\" \\\n --data-binary @- \u003c\u003c EOM\n {\n \"attributes\": [\n {\"key\": \"zone\", \"value\": \"1B\"},\n {\"key\": \"available-at-night\", \"value\": \"true\"}\n ]\n }\n EOM\n\nWhat's next\n\n- [Update a delivery vehicle location](/maps/documentation/mobility/fleet-engine/essentials/vehicles/scheduled-tasks-update-vehicle-location)"]]
