Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Tài liệu này đề cập đến các trường quan trọng về xe mà bạn có thể cập nhật khi tạo và quản lý xe.
type: Loại xe giao hàng này. Điều này ảnh hưởng đến các tuyến đường được tạo cho xe này.
attributes[]: Một mảng lựa chọn thuộc loại DeliveryVehicleAttribute. Sử dụng các tiêu chí này để xác định tiêu chí tuỳ chỉnh cho xe trong dịch vụ của bạn nhằm nâng cao hành vi lọc khi tìm kiếm hoặc liệt kê xe.
Để xem danh sách đầy đủ các trường của xe, hãy xem:
Sử dụng trường attributes xe để tạo tiêu chí tuỳ chỉnh, giúp người tiêu dùng hoặc người vận hành đội xe tìm thấy xe trong đội xe của bạn dựa trên nhiều tiêu chí tìm kiếm hơn. Điều này giúp tăng cường khả năng của ứng dụng để cung cấp kết quả khớp xe chính xác hơn so với khi bạn chỉ sử dụng tiêu chí tìm kiếm dựa trên các trường khác của xe. Mỗi chiếc xe có thể có tối đa 100 thuộc tính và mỗi thuộc tính phải có một khoá riêng biệt. Giá trị có thể là chuỗi, boolean hoặc số.
Ví dụ: bạn có thể khai báo một thuộc tính tuỳ chỉnh có tên là zone để phân biệt khu vực nào trong thành phố mà xe giao hàng của bạn hoạt động. Bạn sẽ sử dụng các giá trị chuỗi như sau để biểu thị các múi giờ khác nhau: 1B, 2C và 3A. Sau đó, bạn có thể sử dụng bộ lọc trong tính năng Theo dõi đội xe để chỉ cho người vận hành chịu trách nhiệm về một khu vực cụ thể thấy những chiếc xe đang hoạt động trong khu vực đó.
Tuy nhiên, các giá trị thuộc tính tuỳ chỉnh không nhất thiết phải không trùng lặp. Bạn có thể sử dụng các tiêu chí như available-at-night và has-refrigeration. Mỗi thuộc tính này có thể là một thuộc tính tuỳ chỉnh riêng biệt sử dụng giá trị boolean. Bạn có thể chỉ định cả 3 thuộc tính tuỳ chỉnh này cho một chiếc xe cụ thể, cùng với thuộc tính tuỳ chỉnh khu vực được đặt thành giá trị chuỗi thích hợp.
Cập nhật thuộc tính xe
Mỗi khoá attributes chỉ có thể có một giá trị cho mỗi xe. Bạn khai báo các thuộc tính tuỳ chỉnh của xe bằng cách sử dụng attributes trong mặt nạ trường, sau đó cung cấp các giá trị dựa trên phương thức bên dưới.
API UpdateDeliveryVehicle này không cho phép chỉ cập nhật một thuộc tính duy nhất. Khi sử dụng phương thức này, mọi việc sử dụng trường attributes trong mặt nạ trường sẽ dẫn đến việc toàn bộ tập hợp thuộc tính xe được khai báo lại cho xe. Điều này dẫn đến việc ghi đè mọi thuộc tính có sẵn không được đưa rõ ràng vào mặt nạ trường. Nếu sử dụng phương thức này để khai báo một thuộc tính tuỳ chỉnh mới, bạn cũng phải khai báo lại mọi thuộc tính tuỳ chỉnh mà bạn muốn xe giữ lại. Nếu bạn loại trừ attributes trong mặt nạ trường, thì phương thức này sẽ giữ nguyên các thuộc tính tuỳ chỉnh hiện có như đã xác định trước đó cho xe.
Nếu bạn sử dụng attributes trong mặt nạ trường nhưng không đặt giá trị, thì điều đó tương đương với việc xoá tất cả thuộc tính tuỳ chỉnh khỏi xe.
Ví dụ về cách cập nhật các trường của xe
Phần này cho biết cách cập nhật các trường của xe bằng UpdateDeliveryVehicleRequest, bao gồm cả update_mask để cho biết những trường cần cập nhật. Hãy xem tài liệu về Vùng đệm giao thức liên quan đến mặt nạ trường để biết thông tin chi tiết.
Để cập nhật các trường khác ngoài last_location, bạn cần có đặc quyền Quản trị viên dịch vụ giao hàng của Fleet Engine.
Ví dụ: đặt thuộc tính tuỳ chỉnh
Ví dụ này chỉ định một thuộc tính mới: zone. Như đã lưu ý trong phần Cập nhật thuộc tính xe trước đó, việc cập nhật trường attributes bằng phương pháp này yêu cầu bạn chỉ định tất cả các thuộc tính tuỳ chỉnh mà bạn muốn giữ lại.
Do đó, ví dụ này cho thấy giá trị available-at-night được ghi để ngăn giá trị này bị ghi đè trong thao tác cập nhật chỉ định trường attributes.
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
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-09-05 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)"]]
