La introducción a las tareas programadas, que abarca en detalle la relación entre las tareas, las paradas y los vehículos
En una situación de entrega del mundo real, las empresas asignan tareas de envío de entregas a los conductores, quienes luego usan un vehículo para entregarlas al destinatario en una ubicación planificada, como una residencia o una sala de entrega en un complejo de edificios. Para modelar esto en Fleet Engine, crea una tarea y emite una solicitud de actualización del vehículo de reparto, que luego actualiza la entidad del vehículo con una lista de paradas para viajar. Asigna a cada parada una lista de tareas que se deben completar en ella.
Puedes actualizar las tareas del vehículo en cualquier momento, pero, por lo general, lo haces para los siguientes fines:
Programar tareas para que las complete un vehículo Puedes hacerlo con una solicitud de actualización que agregue una nueva parada al vehículo o con una solicitud de actualización que agregue una nueva tarea a una parada existente.
Actualiza el orden de las tareas existentes asociadas a una parada de vehículo determinada.
Cambia la ubicación de la finalización de la tarea. De forma predeterminada, Fleet Engine marca la ubicación de finalización de la tarea como la misma ubicación que la parada del vehículo asociada a la tarea. Si lo prefieres, puedes especificar ubicaciones específicas para tareas individuales. Por ejemplo, es posible que un vehículo se detenga en un complejo grande para entregar varios paquetes, cada uno de los cuales tiene asignada una sala de entrega de correo específica.
Cierra las tareas asignadas anteriormente para que no se incluyan en el orden actualizado. Consulta Finaliza tareas para obtener más detalles.
Cómo programar o cambiar tareas de entrega
Puedes programar o cambiar las tareas asignadas a un vehículo desde un entorno de servidor o con el SDK de Driver si le brindas al conductor la capacidad de administrar tareas con un dispositivo de confianza. Usa solo un método para evitar condiciones de carrera y mantener una única fuente de información.
Para cambiar un envío de un vehículo a otro, cierra la tarea original y vuelve a crearla antes de asignarla a otro vehículo. Si actualizas un vehículo de reparto para incluir una tarea que ya está asignada a otro vehículo, recibirás un error.
Campos obligatorios para actualizar tareas
En esta sección, se documentan los campos obligatorios que se deben configurar cuando se actualiza una tarea para un vehículo. No se proporcionan campos opcionales. Fleet Engine ignora todos los demás campos de la entidad para la actualización.
Campo obligatorio
Valor
remainingVehicleJourneySegments
Es una lista de tramos del viaje para las tareas en el orden en que se deben ejecutar.
La primera tarea de la lista se ejecuta primero.
Es una lista de tareas que se deben realizar en esta parada del vehículo.
remainingVehicleJourneySegments[i].stop.state
State.NEW
Ejemplo de asignación de tareas
En los siguientes ejemplos, se muestra cómo usar la biblioteca de gRPC de Java y una llamada a UpdateDeliveryVehicle de REST HTTP para agregar dos tareas nuevas para el vehículo.
gRPC
staticfinalStringPROJECT_ID="my-delivery-co-gcp-project";staticfinalStringVEHICLE_ID="vehicle-8241890";staticfinalStringTASK1_ID="task-756390";staticfinalStringTASK2_ID="task-849263";DeliveryServiceBlockingStubdeliveryService=DeliveryServiceGrpc.newBlockingStub(channel);// Vehicle settingsStringvehicleName="providers/"+PROJECT_ID+"/deliveryVehicles/"+VEHICLE_ID;DeliveryVehicledeliveryVehicle=DeliveryVehicle.newBuilder().addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()// 1st stop.setStop(VehicleStop.newBuilder().setPlannedLocation(LocationInfo.newBuilder().setPoint(LatLng.newBuilder().setLatitude(37.7749).setLongitude(122.4194))).addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID)).setState(VehicleStop.State.NEW))).addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()// 2nd stop.setStop(VehicleStop.newBuilder().setPlannedLocation(LocationInfo.newBuilder().setPoint(LatLng.newBuilder().setLatitude(37.3382).setLongitude(121.8863))).addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID)).setState(VehicleStop.State.NEW))).build();// DeliveryVehicle requestUpdateDeliveryVehicleRequestupdateDeliveryRequest=UpdateDeliveryVehicleRequest.newBuilder()// No need for the header.setName(vehicleName).setDeliveryVehicle(deliveryVehicle).setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments")).build();try{DeliveryVehicleupdatedDeliveryVehicle=deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);}catch(StatusRuntimeExceptione){Statuss=e.getStatus();switch(s.getCode()){caseNOT_FOUND:break;casePERMISSION_DENIED:break;}return;}
<id> es un identificador único de un vehículo de reparto de tu flota para el que deseas actualizar el orden de las tareas. Es el identificador que especificaste cuando creaste el vehículo.
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, donde <token> lo emite tu servidor según los lineamientos que se describen en Roles de la cuenta de servicio y Tokens web JSON.
El cuerpo de la solicitud debe contener una entidad DeliveryVehicle.
[null,null,["Última actualización: 2025-08-31 (UTC)"],[[["\u003cp\u003eFleet Engine enables modeling real-world deliveries by creating tasks and assigning them to vehicles via stops, allowing for dynamic task management.\u003c/p\u003e\n"],["\u003cp\u003eYou can schedule, reorder, relocate, and close tasks for vehicles using server requests or the Driver SDK, ensuring a single source of truth for task management.\u003c/p\u003e\n"],["\u003cp\u003eTo move a task between vehicles, close the original task and recreate it for the new vehicle, preventing assignment errors.\u003c/p\u003e\n"],["\u003cp\u003eWhen scheduling multiple tasks at the same location, assign them to a single stop to streamline task status sharing and improve efficiency.\u003c/p\u003e\n"],["\u003cp\u003eUpdating tasks involves specifying remaining journey segments, stop locations, associated tasks, and setting the stop state to 'NEW' via gRPC or REST API calls.\u003c/p\u003e\n"]]],[],null,["This document assumes familiarity with the following:\n\n- [Create shipment tasks](/maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks)\n- The introduction to [Scheduled tasks](/maps/documentation/mobility/fleet-engine/essentials/tasks-intro), which covers the relationship between tasks, stops, and vehicles in detail.\n\nIn a real-world delivery scenario, businesses assign delivery shipment tasks to\ndrivers, who then use a vehicle to deliver them to the recipient at a planned\nlocation, such as a residence or a delivery room in a building complex. You\nmodel this in Fleet Engine by creating a task and issuing a delivery vehicle\nupdate request, which then updates the vehicle entity with a list of stops to\ntravel. You assign each stop a list of tasks to be completed at the stop.\n\nYou can update vehicle tasks at any time, but typically you do this for the\nfollowing purposes:\n\n- **Schedule tasks** for a vehicle to complete. You can do this either with an update request that adds a new stop to the vehicle, or by an update request that adds a new task to an existing stop.\n- **Update the order of existing tasks** associated with a given vehicle stop.\n- **Change the location of the task completion.** By default, Fleet Engine marks the task completion location as the same location as the vehicle stop associated with the task. If you prefer, you can specify specific locations for individual tasks. For example, you might have a vehicle stop at a large complex to delivery a number of packages, each of which is assigned a specific mail delivery room.\n- **Close any previously assigned tasks** to leave them out of the updated ordering. See [Finalize tasks](/maps/documentation/mobility/fleet-engine/journeys/tasks/finalize-tasks) for details.\n\nSchedule or change delivery tasks\n\nYou can schedule or change tasks assigned to a vehicle from either a server\nenvironment, or by using the Driver SDK if you provide the driver the ability to\nmanage tasks using a trusted device. Use only one method so that you avoid race\nconditions and maintain a single source of truth.\n\nTo change a shipment from one vehicle to another, [close the original task](/maps/documentation/mobility/fleet-engine/journeys/tasks/finalize-tasks#close-task)\nand recreate it before assigning to a different vehicle. If you update a\ndelivery vehicle to include a task that is already assigned to a different\nvehicle, you get an error.\n| **Note:** When you schedule a number of tasks for a vehicle to complete at the same location, you should create a one-to-many association between a stop and the tasks associated with that stop location. Avoid creating a list of stop-task pairs where the stop location is the same for each pair in the list. This helps when you want to share the task status with your consumers using journey sharing. For example, if a driver is making many deliveries to a single office building, you would assign all the delivery tasks to a single vehicle stop.\n\nRequired fields for updating tasks\n\nThis section documents the required fields to set when updating a task for a\nvehicle. No optional fields are provided. Fleet engine ignores all other fields\nin the entity for the update.\n\n\u003cbr /\u003e\n\n| Required field | Value |\n|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|\n| `remainingVehicleJourneySegments` | A list of journey segments for tasks in the order they should be executed. The first task in the list is executed first. |\n| `remainingVehicleJourneySegments[i].stop` | The stop for task *i* in the list. |\n| `remainingVehicleJourneySegments[i].stop.plannedLocation` | The planned location for the stop. |\n| `remainingVehicleJourneySegments[i].stop.tasks` | A list of tasks to be performed at this vehicle stop. |\n| `remainingVehicleJourneySegments[i].stop.state` | `State.NEW` |\n\n\u003cbr /\u003e\n\nAssign tasks example\n\nThe following examples show how to use the [Java gRPC library](/maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks) and an HTTP\nREST call to `UpdateDeliveryVehicle` to add two new tasks for the vehicle. \n\ngRPC \n\n static final String PROJECT_ID = \"my-delivery-co-gcp-project\";\n static final String VEHICLE_ID = \"vehicle-8241890\";\n static final String TASK1_ID = \"task-756390\";\n static final String TASK2_ID = \"task-849263\";\n\n DeliveryServiceBlockingStub deliveryService =\n DeliveryServiceGrpc.newBlockingStub(channel);\n\n // Vehicle settings\n String vehicleName = \"providers/\" + PROJECT_ID + \"/deliveryVehicles/\" + VEHICLE_ID;\n DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()\n .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop\n .setStop(VehicleStop.newBuilder()\n .setPlannedLocation(LocationInfo.newBuilder()\n .setPoint(LatLng.newBuilder()\n .setLatitude(37.7749)\n .setLongitude(122.4194)))\n .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))\n .setState(VehicleStop.State.NEW)))\n .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop\n .setStop(VehicleStop.newBuilder()\n .setPlannedLocation(LocationInfo.newBuilder()\n .setPoint(LatLng.newBuilder()\n .setLatitude(37.3382)\n .setLongitude(121.8863)))\n .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))\n .setState(VehicleStop.State.NEW)))\n .build();\n\n // DeliveryVehicle request\n UpdateDeliveryVehicleRequest updateDeliveryRequest =\n UpdateDeliveryVehicleRequest.newBuilder() // No need for the header\n .setName(vehicleName)\n .setDeliveryVehicle(deliveryVehicle)\n .setUpdateMask(FieldMask.newBuilder().addPaths(\"remaining_vehicle_journey_segments\"))\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 PATCH https://fleetengine.googleapis.com/v1/providers/\u003cproject_id\u003e/deliveryVehicles/\u003cid\u003e?updateMask=remainingVehicleJourneySegments`\n\n- *\\\u003cid\\\u003e* is a unique identifier for a delivery vehicle in your fleet\n for which you intend to update the task ordering. It is the identifier that\n you specified when creating the vehicle.\n\n- The request header must contain a field *Authorization* with the value\n *Bearer \\\u003ctoken\\\u003e* , where *\\\u003ctoken\\\u003e* is issued by your server\n according to the guidelines described in [Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) and\n [JSON Web tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt).\n\n- The request body must contain a `DeliveryVehicle` entity\n\nExample `curl` command:\n**Note:** This command overwrites any `remainingVehicleJourneySegments` already set on the delivery vehicle. \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=remainingVehicleJourneySegments\" \\\n -H \"Content-type: application/json\" \\\n -H \"Authorization: Bearer ${JWT}\" \\\n --data-binary @- \u003c\u003c EOM\n {\n \"remainingVehicleJourneySegments\": [\n {\n \"stop\": {\n \"state\": \"NEW\",\n \"plannedLocation\": {\n \"point\": {\n \"latitude\": 37.7749,\n \"longitude\": -122.084061\n }\n },\n \"tasks\": [\n {\n \"taskId\": \"${TASK1_ID}\"\n }\n ]\n }\n },\n {\n \"stop\": {\n \"state\": \"NEW\",\n \"plannedLocation\": {\n \"point\": {\n \"latitude\": 37.3382,\n \"longitude\": 121.8863\n }\n },\n \"tasks\": [\n {\n \"taskId\": \"${TASK2_ID}\"\n }\n ]\n }\n }\n ]\n }\n EOM\n\n| **Experimental:** As an experimental feature, the `LocationInfo` ([gRPC](/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1#locationinfo) or [REST](/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo)) field now supports using `place` ([gRPC](/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place) or [REST](/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo#FIELDS.place)), either alongside or instead of `LatLng`.\n\nWhat's next\n\n- [Update stop status](/maps/documentation/mobility/fleet-engine/journeys/tasks/update-stops)"]]
