Comienza a usar Fleet Engine

La API de Fleet Engine Deliveries te permite modelar las actividades de tu flota para la primera y última milla de las entregas. La API de Deliveries se expone a través del SDK de Driver para iOS y Android, y también se puede usar directamente a través de llamadas de REST o gRPC de HTTP.

Configuración inicial

La API de Fleet Engine Deliveries se configura a través de la consola de Google Cloud. Para obtener información sobre los pasos a seguir en la consola y cómo crear un token web JSON para la autorización, consulta Autenticación y autorización. Si deseas obtener detalles sobre el uso de la consola, consulta la documentación de la consola de Google Cloud.

Verifica la configuración

Después de crear cuentas de servicio, debes verificar que la configuración esté completa y poder crear un vehículo de entrega. Si realizas la verificación en esta etapa de tu flujo de trabajo, te asegurarás de haber abordado problemas de autorización comunes que puedan surgir cuando configures tu proyecto. Sigue la guía Verifica tu configuración. En esta guía, se proporcionan detalles sobre cómo usar la utilidad de línea de comandos gcloud para probar dos partes clave de tu configuración: la firma de token de autorización y la creación de vehículos de entrega de prueba.

Como alternativa, puedes usar las secuencias de comandos de muestra de Fleet Engine para probar tu configuración.

Bibliotecas cliente

Publicamos bibliotecas cliente en varios lenguajes de programación comunes. Estas bibliotecas proporcionan una mejor experiencia para el desarrollador que REST o gRPC sin procesar. Si quieres obtener instrucciones para obtener las bibliotecas cliente de tu aplicación de servidor, consulta la sección Bibliotecas cliente.

En los ejemplos de Java que se incluyen en esta documentación, se da por sentado que tienes conocimientos de gRPC.

Estructuras de datos

La API de Deliveries usa dos estructuras de datos para modelar el retiro y la entrega de los envíos:

• Es el vehículo de entrega usado para transportar el envío.
• Las tareas de retiro y entrega del envío.

Además, puedes usar tareas para modelar las pausas de los conductores y las paradas programadas durante el día.

Vehículos de entrega

Estos vehículos transportan envíos de un depósito a una ubicación de entrega y desde un punto de partida hasta el depósito. En algunos casos, también pueden transportar un envío directamente desde el lugar de recogida hasta el lugar de entrega.

Puedes usar el SDK de Driver para crear un objeto DeliveryVehicle en Fleet Engine y enviar actualizaciones de ubicación para el envío y el seguimiento de la flota.

Tareas

Cada vehículo tiene tareas asignadas. Estos pueden incluir tareas de recogida o entrega, descansos requeridos para los conductores o paradas programadas en los buzones o las ubicaciones de los clientes. Cada tarea debe tener un ID de tarea único, pero puede compartir el mismo ID de seguimiento. Las tareas y el orden en que están programadas se utilizan para calcular los períodos de hora de llegada estimada de cada tarea.

Usa el Administrador de tareas del SDK de Driver para crear tareas en Fleet Engine.

Tareas de envío

Las tareas de envío están relacionadas con el retiro o la entrega del envío. Cuando cree una tarea de envío, debe especificar un número de seguimiento o un ID. También debes especificar un tiempo de permanencia a fin de tener en cuenta el tiempo adicional para completar la tarea, buscar estacionamiento o caminar hasta la ubicación de entrega.

• Crea una tarea de retiro para retirar un envío y especifica la ubicación de retiro y el número o ID de seguimiento.
• Crea una tarea de entrega a fin de entregar un envío. Para ello, especifica la ubicación de entrega y el número o ID de seguimiento.

Tareas de no disponibilidad

Crea una tarea de falta de disponibilidad durante un período en el que el vehículo no esté disponible para retiros o entregas. Esto puede ser un descanso para reabastecer el vehículo o para el descanso del conductor. Especifica la duración de la pausa cuando crees la tarea. No es necesario tomar descansos en una ubicación específica, pero especificar una ubicación proporciona ventanas de hora de llegada más precisas a lo largo del día.

Durante una tarea de falta de disponibilidad, no se comparte información de ubicación con un usuario final. Por ejemplo, la ubicación del vehículo de entrega está oculta para los administradores de flotas mediante la biblioteca de seguimiento de flota.

Tareas de detención programadas

Crea tareas de parada programadas para modelar las paradas que realizará un vehículo de entrega. Por ejemplo, puedes crear una tarea de parada programada para una parada de recopilación diaria programada en una ubicación específica, independientemente de otras entregas o retiros en la misma ubicación. También puedes crear tareas de parada programadas para la recolección de buzones o para modelar transferencias o paradas de vehículos de alimentación en centros de servicio y puntos de servicio.

Puedes ver los campos específicos contenidos en cada estructura de datos si consultas la documentación de referencia de la API para DeliveryVehicle (gRPC, REST) y Task (gRPC, REST).

• Los ID deben ser strings Unicode válidas.
• Los IDs deben tener 64 caracteres o menos.
• Los IDs se normalizarán según el formulario de normalización C de Unicode.
• Los ID no pueden contener ninguno de los siguientes caracteres ASCII: "/", ":", "\", "?" o "#".

Los siguientes son algunos ejemplos de buenos ID de tareas:

• 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
• e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
• NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk

En la siguiente tabla, se muestran ejemplos de IDs de tareas incorrectos:

Duración de un vehículo

El objeto DeliveryVehicle representa un vehículo de entrega en la primera o la última milla. Creas un objeto DeliveryVehicle mediante lo siguiente:

• Es el ID del proyecto de Google Cloud que contiene la cuenta de servicio que se usa para llamar a las API de Fleet Engine.
• El ID de un vehículo que es propiedad del cliente.

Los IDs de vehículo deben ser únicos para cada vehículo. No se deben volver a usar para otro vehículo, a menos que no haya tareas activas para ese vehículo.

Asegúrate de verificar si hay un error NOT_FOUND cuando realices una llamada a UpdateDeliveryVehicle y, luego, si es necesario, llama a CreateDeliveryVehicle para crear un vehículo nuevo. Un objeto DeliveryVehicle que no se actualizó con UpdateDeliveryVehicle se borra de forma automática después de siete días. Ten en cuenta que llamar a CreateDeliveryVehicle con un par de ID del proyecto/ID de vehículo que ya existe genera un error.

Atributos del vehículo

La entidad DeliveryVehicle contiene un campo repetido de DeliveryVehicleAttribute. La API de ListDeliveryVehicles incluye un campo filter que puede limitar las entidades DeliveryVehicle que se muestran a aquellas con los atributos especificados. Los DeliveryVehicleAttribute no afectan el comportamiento de enrutamiento de Fleet Engine.

No incluyas información sensible ni de identificación personal en los atributos, ya que los usuarios pueden ver este campo.

Ciclo de una tarea

Las tareas en Fleet Engine se pueden crear, consultar y actualizar mediante las interfaces de REST o gRPC de la API de Deliveries.

Un objeto Task tiene un campo de estado para realizar un seguimiento de su progreso en su ciclo de vida. Los valores van de OPEN a CLOSED. Las tareas nuevas se crean con el estado ABIERTO, lo que indica lo siguiente:

• La tarea aún no se asignó a un vehículo de entrega.
• El vehículo de entrega aún no pasó la parada del vehículo asignada para la tarea.

Una tarea solo se puede asignar a un vehículo cuando está en el estado OPEN.

Para cancelar una tarea, quítala de la lista de paradas de vehículos. Luego, su estado se establece automáticamente en CERRADO.

Cuando el vehículo de la tarea complete la parada del vehículo de la tarea, actualiza el campo de resultado de la tarea a SUCCEEDED o FAILED y especifica la marca de tiempo del evento. El resultado de la tarea se puede establecer en cualquier momento antes o después de que se complete la tarea, pero se puede establecer solo una vez.

Luego, la biblioteca de seguimiento de flota de JavaScript puede indicar el resultado de la tarea. El estado de la tarea se establece automáticamente en CERRADO. Para obtener más información, consulta Realiza un seguimiento de tu flota con la biblioteca de seguimiento de flota de JavaScript.

Al igual que con los vehículos, las tareas que no se actualizaron después de siete días se borran y, si se intenta crear una tarea con un ID que ya existe, se muestra un error.

Nota: Fleet Engine no admite la eliminación explícita de una tarea. El servicio borra las tareas de forma automática después de siete días sin actualizaciones. Si deseas conservar los datos de las tareas por más de siete días, debes implementar esa funcionalidad por tu cuenta.

Atributos de la tarea

La entidad Task contiene un campo repetido de TaskAttribute, que puede tener el valor de uno de los 3 tipos: string, número y bool. La API de ListTasks incluye un campo filter que puede limitar las entidades Task que se muestran a aquellas con los atributos especificados. Los TaskAttribute no afectan el comportamiento de enrutamiento de Fleet Engine.

No incluyas información sensible ni de identificación personal en los atributos, ya que los usuarios pueden ver este campo.

Cómo administrar el ciclo de vida de los vehículos y las tareas

Para administrar los ciclos de vida de vehículos y tareas en tu sistema, usa la API de Fleet Engine Deliveries a fin de crear, actualizar y realizar un seguimiento de tus vehículos y sus tareas asociadas. Tu sistema interno actúa como la fuente confiable de los datos que aumenta la API de Fleet Engine Deliveries en tu nombre.

Al mismo tiempo, la aplicación del controlador se comunica directamente con Fleet Engine para actualizar la ubicación del dispositivo y la información de ruta. Este modelo permite que Fleet Engine administre la ubicación en tiempo real de manera eficiente y la envíe directamente a la biblioteca de seguimiento, que luego puedes usar para los consumidores que necesitan actualizaciones de estado para su pedido.

Por ejemplo, supongamos que tienes la siguiente situación:

• Un conductor se acerca a una parada de entrega y Fleet Engine envía la ubicación del dispositivo a la biblioteca de seguimiento, que tu aplicación de consumidor usa para alertar al consumidor sobre la proximidad de su paquete.
• Una vez que el conductor completa el envío, hace clic en el botón "Envío entregado" en la aplicación del conductor.
• Esto envía la información a tu sistema de backend, que realiza los pasos necesarios de validación y verificación del negocio.
• El sistema confirmará la tarea como COMPLETA y actualizará Fleet Engine con la API de Deliveries.

En el siguiente diagrama, se ilustran estos procesos a un nivel genérico. También muestra la relación estándar entre tu sistema, el cliente y Fleet Engine.

Administración de tokens de cliente

Todas las actualizaciones de ubicación que se originan en la aplicación del controlador y se envían directamente a Fleet Engine requieren tokens de autorización. El enfoque recomendado para manejar las actualizaciones del cliente a Fleet Engine es proporcionar a la aplicación del controlador un token de permiso limitado para que solo pueda actualizar la ubicación del dispositivo en Fleet Engine. Para este tipo de token, usa una función de cuenta de servicio conocida como Usuario de controlador no confiable de entrega de Fleet Engine. Esto garantiza que las llamadas que se originan en dispositivos móviles (que se consideran entornos de baja confianza) cumplan con el principio de privilegio mínimo.

Otras funciones de la cuenta de servicio

En cambio, si deseas autorizar que las aplicaciones del controlador realicen actualizaciones directas de Fleet Engine más allá de las restringidas a la función de controlador no confiable, como para ciertas actualizaciones de tareas, puedes usar la función de controlador de confianza. Para obtener información sobre un modelo que usa la función de conductor de confianza, consulta el modelo de controlador de confianza.

Para obtener más información sobre los usos de las funciones de controlador no confiables y de confianza, consulta la configuración del proyecto de Cloud.

Cómo modelar una jornada laboral

En la siguiente tabla, se describe cómo puede ser un día laboral para los conductores de ruta de acceso o red de acceso en una empresa de entregas y logística. Los detalles de tu empresa pueden variar, pero puedes ver cómo podrías modelar un día de trabajo.

Información sobre las actualizaciones de ubicación

Las actualizaciones de ubicación se envían a Fleet Engine una vez que un vehículo de entrega se dirige desde una parada (incluido el depósito) hasta que llega a la siguiente parada. Debido a que estos eventos no se detectan automáticamente, debes marcarlos de manera programática. Usa bibliotecas que detecten cambios en el medio de transporte para activar el envío de las notificaciones necesarias a Fleet Engine.

Las actualizaciones de ubicación deben suspenderse cuando el conductor no está conduciendo, ya que la calidad de los indicadores de ubicación se degrada drásticamente cuando alguien está dentro de un edificio.

La frecuencia de actualización de la ubicación se puede configurar en el SDK de Driver. La configuración predeterminada es enviar actualizaciones cada 10 segundos.

Paradas de vehículos y ubicaciones de entrega

La parada de un vehículo es la parte en la que un vehículo de entregas completa una tarea de envío o alguna otra tarea. Es un punto de acceso, como un conector de carga o una ubicación ajustada a la ruta.

La ubicación de entrega es donde se entrega o se recoge el envío. Es posible que debas ir a la ubicación de entrega y volver a ella a pie desde la parada del vehículo.

Por ejemplo, cuando un conductor entrega un envío a una tienda de un centro comercial, el vehículo de reparto se detiene en el estacionamiento del centro comercial cerca de la entrada más cercana a la tienda. Esta es la parada del vehículo. Luego, el conductor camina desde la parada del vehículo hasta la ubicación dentro del centro comercial en la que se encuentra la tienda. Esta es la ubicación de entrega.

A fin de brindar la mejor experiencia de seguimiento del envío para tus usuarios, considera cómo se asignan las tareas de envío a las paradas del vehículo y ten en cuenta que se informa al usuario la cantidad de paradas restantes para tareas de envío a fin de ayudarlo a ver el progreso del envío.

Por ejemplo, si un conductor realiza muchas entregas en un solo edificio de oficinas, considera asignar todas las tareas de entrega a una sola parada del vehículo. Si cada tarea de entrega se asigna a su propia parada del vehículo, la experiencia de seguimiento de envío sería menos útil para los usuarios, ya que el seguimiento solo está disponible una vez que el vehículo se encuentra dentro de una cantidad limitada de paradas antes de su destino. Tener muchas paradas del vehículo completadas en poco tiempo no le dará al usuario mucho tiempo para hacer un seguimiento del progreso de la entrega.

Cómo usar los SDK para dispositivos móviles

Antes de realizar llamadas al SDK de Driver, asegúrate de inicializarlo.

Cómo inicializar la API de Delivery Driver

Antes de inicializar la API de Delivery Driver en el SDK de Driver, asegúrate de inicializar el SDK de Navigation. Luego, inicializa la API de Delivery Driver como se muestra en el siguiente ejemplo:

static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";

NavigationApi.getNavigator(
   this, // Activity.
   new NavigatorListener() {
     @Override
     public void onNavigatorReady(Navigator navigator) {
       DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
         .setNavigator(navigator)
         .setProviderId(PROVIDER_ID)
         .setVehicleId(VEHICLE_ID)
         .setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
         .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
         .setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
         .setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
             Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
         .build));
     }

     @Override
     public void onError(int errorCode) {
       Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
     }
   });

Casos de uso

En esta sección, se describe cómo usar la API de Deliveries para modelar casos de uso comunes.

Identificadores de entidad únicos

El formato y el valor de los identificadores de entidad únicos que se usan en las llamadas de REST son opacos para Fleet Engine. Evita usar IDs de incremento automático y asegúrate de que el identificador no contenga información de identificación personal (PII), como el número de teléfono del conductor.

Crea un vehículo

Puedes crear un vehículo desde el SDK del controlador o desde el entorno del servidor.

gRPC

Para crear un vehículo nuevo, realiza una llamada CreateDeliveryVehicle a Fleet Engine. Usa el objeto CreateDeliveryVehicleRequest para definir los atributos del nuevo vehículo de entrega. Ten en cuenta que cualquier valor especificado en el campo Name se ignorará según los lineamientos de la API para los IDs especificados por el usuario. Debes usar el campo DeliveryVehicleId para establecer el ID del vehículo.

Cuando creas un objeto DeliveryVehicle, tienes la opción de especificar dos campos:

• Atributos
• LastLocation

No se deben configurar todos los demás campos. De lo contrario, Fleet Engine mostrará un error porque esos campos son de solo lectura o solo se pueden actualizar mediante llamadas UpdateDeliveryVehicle.

Para crear un vehículo sin configurar ningún campo opcional, puedes dejar el campo DeliveryVehicle sin configurar en CreateDeliveryVehicleRequest.

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para crear un vehículo:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
  .addAttributes(DeliveryVehicleAttribute.newBuilder()
    .setKey("route_number").setValue("1"))  // Opaque to the Fleet Engine
  .build();

// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
  CreateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setDeliveryVehicleId(VEHICLE_ID)     // Vehicle ID assigned by the Provider
      .setDeliveryVehicle(vehicle)
      .build();

// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.

try {
  DeliveryVehicle createdVehicle =
    deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para crear un vehículo a partir de un entorno de servidor, realiza una llamada HTTP REST a CreateDeliveryVehicle:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>

<id> es un identificador único de un vehículo de entrega de su flota.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de POST representa la entidad DeliveryVehicle que se creará. Puedes especificar los siguientes campos opcionales:

• attributes
• Última ubicación

Comando curl de ejemplo

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
  "attributes": [{"key": "model", "value": "sedan"}],
  "lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM

Fleet Engine ignora el campo name de la entidad DeliveryVehicle según la guía de API para los IDs especificados por el usuario. No se deben configurar todos los demás campos. De lo contrario, Fleet Engine mostrará un error porque esos campos son de solo lectura o solo se pueden actualizar a través de llamadas a UpdateDeliveryVehicle.

Para crear un vehículo sin configurar ningún campo, puedes dejar el cuerpo de la solicitud POST vacío. Se extraerá un ID del vehículo del vehículo recién creado del parámetro deliveryVehicleId en la URL de POST.

Comando curl de ejemplo

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}"

Cómo crear una tarea de retiro de envíos

Puedes crear una tarea de retiro de envíos desde el SDK del controlador o desde el entorno del servidor.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para crear una tarea de retiro de envíos:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para crear una tarea de retiro de envíos desde un entorno de servidor, realiza una llamada HTTP REST a “CreateTask”:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> es un identificador único de la tarea. No debe ser el número de seguimiento del envío. Si no tienes ID de tarea en tu sistema, puedes generar un identificador único universal (UUID).

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

• Campos obligatorios:

  Campo	Valor
  tipo	Tipo.PICKUP
  final	Estado.OPEN
  IDdeseguimiento	El número o identificador que se utiliza para rastrear un envío.
  ubicación planificada	La ubicación donde se debe completar la tarea, en este caso, la ubicación de retiro del envío.
  Duración de la tarea	El tiempo previsto, en segundos, que se necesitará para retirar el envío en el lugar de recogida.

• Campos opcionales:

  Campo	Valor
  targetTimeWindow	El período durante el cual se debe completar la tarea. Por el momento, esto no afecta el comportamiento del enrutamiento.
  attributes	Una lista de atributos personalizados de Task. Cada atributo debe tener una clave única.

Todos los demás campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Debes asignar tareas con UpdateDeliveryVehicleRequests. Para obtener más información, consulta Asigna tareas a un vehículo.

Comando curl de ejemplo

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "PICKUP",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Cómo crear una tarea de entrega de envíos

Puedes crear una tarea de entrega de envíos desde el SDK de Driver o desde el entorno del servidor.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para crear una tarea de entrega de envíos:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para crear una tarea de entrega de envíos desde un entorno de servidor, realiza una llamada HTTP REST a “CreateTask”:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> es un identificador único de la tarea. No debe ser el número de seguimiento del envío. Si no tienes ID de tarea en tu sistema, puedes generar un identificador único universal (UUID).

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

• Campos obligatorios:

  Campo	Valor
  tipo	Tipo.ENTREGA
  final	Estado.OPEN
  IDdeseguimiento	El número o identificador que se utiliza para rastrear un envío.
  ubicación planificada	La ubicación donde se debe completar la tarea, en este caso, la ubicación de entrega de este envío.
  Duración de la tarea	El tiempo esperado, en segundos, que llevará dejar el envío en la ubicación de entrega.

• Campos opcionales:

  Campo	Valor
  targetTimeWindow	El período durante el cual se debe completar la tarea. Por el momento, esto no afecta el comportamiento del enrutamiento.
  attributes	Una lista de atributos personalizados de Task. Cada atributo debe tener una clave única.

Todos los demás campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Debes asignar tareas con UpdateDeliveryVehicleRequests. Para obtener más información, consulta Asigna tareas a un vehículo.

Comando curl de ejemplo

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "DELIVERY",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Tareas de creación por lotes

Puedes crear un lote de tareas desde el entorno del servidor.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para crear dos tareas, una para una entrega y otra para un retiro en la misma ubicación:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Delivery Task settings
Task deliveryTask = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("delivery-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8312508")  // Task ID assigned by the Provider
      .setTask(deliveryTask)      // Initial state
      .build();

// Pickup Task settings
Task pickupTask = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("pickup-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(pickupTask)        // Initial state
      .build();

// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;

// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
  BatchCreateTasksRequest.newBuilder()
      .setParent(parent)
      .addRequests(createDeliveryTaskRequest)
      .addRequests(createPickupTaskRequest)
      .build();

// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.

try {
  BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
    batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para crear una tarea de entrega y retiro desde el entorno del servidor, realiza una llamada REST HTTP a BatchCreateTasks:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad BatchCreateTasksRequest:

• Campos obligatorios:

  Campo	Valor
  solicitudes	Arreglo<CreateTasksRequest>

• Campos opcionales:

  Campo	Valor
  encabezado	"DeliveryRequestHeader"

Cada elemento CreateTasksRequest en requests debe pasar las mismas reglas de validación que una solicitud CreateTask, con la excepción de que los campos parent y header son opcionales. Si se configuran, deben ser idénticos a sus respectivos campos en el BatchCreateTasksRequest de nivel superior. Consulta cómo crear una tarea de retiro de envíos y una tarea de entrega de envíos a fin de obtener reglas de validación específicas para cada una.

Si deseas obtener más información, consulta la documentación de referencia de la API para BatchCreateTasks (gRPC, REST).

Comando curl de ejemplo

# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "requests" : [
    {
      "taskId": "${DELIVERY_TASK_ID}",
      "task" : {
        "type": "DELIVERY",
        "state": "OPEN",
        "trackingId": "${DELIVERY_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    },
    {
      "taskId": "${PICKUP_TASK_ID}",
      "task" : {
        "type": "PICKUP",
        "state": "OPEN",
        "trackingId": "${PICKUP_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    }
  ]
}
EOM

Falta de disponibilidad programada

Puedes crear una tarea que indique la falta de disponibilidad (por ejemplo, para pausas de conductores o recargas de vehículos) desde el SDK del conductor o desde el entorno del servidor. Una tarea de no disponibilidad programada no debe incluir un ID de seguimiento. De manera opcional, puedes proporcionar una ubicación.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para crear una tarea de no disponibilidad:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.UNAVAILABLE)
  .setState(Task.State.OPEN)
  .setTaskDuration(
    Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para crear una tarea de falta de disponibilidad desde un entorno de servidor, realiza una llamada HTTP REST a “CreateTask”:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> es un identificador único de la tarea. Si no tienes ID de tarea en tu sistema, puedes generar un identificador único universal (UUID).

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

• Campos obligatorios:

  Campo	Valor
  tipo	Tipo.UNAVAILABLE
  final	Estado.OPEN
  Duración de la tarea	La duración de la pausa en segundos.

• Campos opcionales:

  Campo	Valor
  ubicación planificada	Corresponde a la ubicación de la pausa si debe tomarse en una ubicación específica.

Todos los demás campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Debes asignar tareas con UpdateDeliveryVehicleRequests. Para obtener más información, consulta Asigna tareas a un vehículo.

Comando curl de ejemplo

# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "UNAVAILABLE",
  "state": "OPEN",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "300s"
}
EOM

Paradas programadas

Puedes crear una tarea de detención programada desde el SDK del controlador o desde el entorno del servidor. Es posible que una tarea de detención programada no incluya un ID de seguimiento.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para crear una tarea de detención programada:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.SCHEDULED_STOP)
  .setState(Task.State.OPEN)
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTrip(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para crear una tarea de detención programada desde un entorno de servidor, realiza una llamada HTTP REST a CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> es un identificador único de la tarea. Si no tienes ID de tarea en tu sistema, puedes generar un identificador único universal (UUID).

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

• Campos obligatorios:

  Campo	Valor
  tipo	Escribe.SCHEDULED_STOP
  final	Estado.OPEN
  ubicación planificada	Es la ubicación de la parada.
  Duración de la tarea	Indica la duración anticipada de la parada en segundos.

• Campos opcionales:

  • Ninguna

Todos los demás campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Debes asignar tareas con UpdateDeliveryVehicleRequests. Para obtener más información, consulta Asigna tareas a un vehículo.

Comando curl de ejemplo

# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "SCHEDULED_STOP",
  "state": "OPEN",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "600s"
}
EOM

El margen de tiempo objetivo es el TimeWindow durante el cual se debe completar la tarea. Por ejemplo, si comunicas un período de entrega a los destinatarios de la entrega, puedes usar la ventana de tiempo objetivo de la tarea para capturar este período y generar alertas o analizar el rendimiento posterior al viaje con el campo.

El período de tiempo objetivo consta de una hora de inicio y una hora de finalización, y se puede configurar en cualquier tipo de tarea. Por el momento, el período establecido no afecta el comportamiento del enrutamiento.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para establecer un período de tiempo de tareas:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para configurar un período de tiempo de tarea con HTTP, llama a UpdateTask:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow

<id> es un identificador único de la tarea.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

• Campos obligatorios:

  Campo	Valor
  targetTimeWindow	El período durante el cual se debe completar la tarea. Por el momento, esto no afecta el comportamiento del enrutamiento

• Campos opcionales:

  • Ninguna

Todos los demás campos de la entidad se ignoran para la actualización.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Establece la configuración de visibilidad del seguimiento de tareas

La visibilidad de los datos en la biblioteca de seguimiento de envíos y de esos datos que se muestran de una llamada a GetTaskTrackingInfo se puede controlar por tarea si configuras un TaskTrackingViewConfig en la tarea. Consulta Tareas activas de vehículos para obtener más información. Esto se puede hacer cuando se crea o se actualiza la tarea. El siguiente es un ejemplo de actualización de la tarea con esta configuración:

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para establecer la configuración de la vista de seguimiento de tareas:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}

REST

Para configurar la ventana de configuración de la vista de seguimiento de tareas con HTTP, llama a UpdateTask:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig

<id> es un identificador único de la tarea.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

• Campos obligatorios:

  Campo	Valor
  taskTrackingViewConfig	La configuración del seguimiento de tareas que especifica qué elementos de datos son visibles para los usuarios finales en qué circunstancias.

• Campos opcionales:

  • Ninguna

Todos los demás campos de la entidad se ignoran para la actualización.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

Asigna tareas a un vehículo

Las tareas se asignan a un vehículo de entrega mediante la actualización del pedido de tareas del vehículo. El pedido de tareas para un vehículo se determina según la lista de paradas del vehículo de entrega. A cada parada de vehículo se le pueden asignar una o más tareas.

La actualización del orden de las tareas para una tarea que antes estaba asignada a otro vehículo genera un error.

Para cambiar un envío de un vehículo a otro, cierra la tarea original y, luego, vuelve a crearla antes de asignarle el vehículo nuevo.

Actualiza el orden de las tareas

Puedes actualizar el orden de ejecución de las tareas asignadas a un vehículo desde el SDK del controlador o desde el entorno del servidor. Para evitar condiciones de carrera, no debes combinar los dos métodos.

La actualización del orden de tareas también asignará tareas a un vehículo si no se las asignó previamente y cerrará aquellas que ya estaban asignadas a un vehículo y que quedaron fuera del pedido actualizado. Asignar una tarea a un vehículo diferente si ya se había asignado a otro vehículo genera un error. Primero, cierra la tarea existente y, luego, crea una tarea nueva antes de asignarla al vehículo nuevo.

El orden de las tareas se puede actualizar en cualquier momento.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para actualizar el orden de tareas del vehículo:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = 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 request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

A fin de actualizar el orden de tareas para un vehículo desde un entorno de servidor, realiza una llamada REST HTTP a "UpdateDeliveryVehicle":

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments

<id> es un identificador único de un vehículo de entrega de tu flota para el que quieres 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>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

• Campos obligatorios:

  Campo	Valor
  Segmentosderecorridodeelvehículo restante	Una lista de segmentos de recorrido para las tareas en el orden en que deben ejecutarse. La primera tarea de la lista se ejecuta primero.
  Segmentosderecorridodevehículos[i].parada	La parada para la tarea i en la lista.
  restanteVehicleJourneySegments[i].stop.planeLocation[i].	Es la ubicación planificada de la parada.
  Segmentosderecorridodeelvehículo restante[i].stop.tareas	Una lista de tareas que se deben realizar en esta parada del vehículo.
  restanteVehicleJourneySegments[i].stop.state	Estado.NUEVO

• Campos opcionales:

  • Ninguna

Todos los demás campos de la entidad se ignoran para la actualización.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Se debe notificar a Fleet Engine cuando un vehículo sale de una parada o comienza la navegación. Puedes notificar a Fleet Engine desde el SDK del controlador o desde el entorno del servidor. No se deben combinar los dos métodos para evitar condiciones de carrera y mantener una única fuente de información.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca de gRPC de Java para notificar a Fleet Engine que un vehículo está en camino a su siguiente parada.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Next stop marked as ENROUTE
    .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.ENROUTE)))
    // All other stops marked as 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 request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para notificar a Fleet Engine que un vehículo está en camino a su siguiente parada desde un entorno de servidor, realiza una llamada de REST HTTP a "UpdateDeliveryVehicle":

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments

<id> es un identificador único del vehículo de entrega de tu flota para el que quieres 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>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

• Campo obligatorio:

  Campo	Valor
  Segmentosderecorridodeelvehículo restante	Lista de las paradas restantes de los vehículos con sus estados marcados como State.NEW. El estado de la primera parada de la lista debe estar marcado como State.ENROUTE.

• Campos opcionales:

  • Ninguna

Todos los demás campos de la entidad se ignoran para la notificación.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ENROUTE",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Se debe notificar a Fleet Engine cuando un vehículo llega a una parada. Puedes notificar a Fleet Engine desde el SDK del controlador o desde el entorno del servidor. No se deben combinar los dos métodos para evitar condiciones de carrera y mantener una única fuente de información.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca de gRPC de Java para notificar a Fleet Engine que un vehículo llegó a una parada:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Marking the arrival at stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as 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))) // Remaining stops must be NEW.
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para notificar a Fleet Engine sobre la llegada de un vehículo en una parada desde un entorno de servidor, realiza una llamada de REST HTTP a "UpdateDeliveryVehicle":

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments

<id> es un identificador único del vehículo de entrega de tu flota para el que quieres 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>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

• Campos obligatorios:

  Campo	Valor
  Segmentosderecorridodeelvehículo restante	La parada a la que llegaste y su estado se estableció como State.ARRIVED, seguida de una lista de las paradas restantes del vehículo con sus estados marcados como State.NEW.

• Campos opcionales:

  • Ninguna

Todos los demás campos de la entidad se ignoran para la actualización.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ARRIVED",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Se debe notificar a Fleet Engine cuando un vehículo completa una parada. Esto hace que todas las tareas asociadas con la parada se establezcan en un estado CERRADO. Puedes notificar a Fleet Engine desde el SDK del controlador o desde el entorno del servidor. No se deben combinar los dos métodos para evitar condiciones de carrera y mantener una única fuente de información.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca de gRPC de Java para notificar a Fleet Engine que un vehículo se detuvo.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // This stop has been completed and is commented out to indicate it
    // should be removed from the list of vehicle journey segments.
    // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
    //    .setStop(VehicleStop.newBuilder()
    //        .setPlannedLocation(LocationInfo.newBuilder()
    //            .setPoint(LatLng.newBuilder()
    //                .setLatitude(37.7749)
    //                .setLongitude(122.4194)))
    //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
    //        .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    // The next stop could be marked as ENROUTE if the vehicle has begun
    // its journey to the next stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next 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 request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // no need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para notificar a Fleet Engine sobre la finalización de una parada de un entorno de servidor, realiza una llamada REST HTTP a "UpdateDeliveryVehicle":

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments

<id> es un identificador único del vehículo de entrega de tu flota para el que quieres 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>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

• Campos obligatorios:

  Campo	Valor
  segmentos_de_recorrido_del_vehículo_restante	La parada que completaste ya no debería estar en la lista de paradas restantes de vehículos.

• Campos opcionales:

  • Ninguna

Todos los demás campos de la entidad se ignoran para la actualización.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}",
            "taskDuration": "120s"
          }
        ]
      }
    }
  ]
}
EOM

Este es un ejemplo de cómo actualizar una tarea a través de gRPC.

REST

Este es un ejemplo de actualización de una tarea mediante REST.

Para cerrar una tarea asignada a un vehículo, informa a Fleet Engine que el vehículo completó la parada en la que se realiza la tarea o quítalo de la lista de paradas de vehículos. Para ello, puedes configurar la lista de las paradas restantes del vehículo como cuando actualizas el orden de la tarea para un vehículo.

Si a una tarea aún no se le asignó un vehículo y debe cerrarse, actualízala a un estado CERRADA. Sin embargo, no podrás reabrir una tarea CERRADA.

El cierre de una tarea no indica éxito o fracaso. Indica que la tarea ya no se considera en curso. Para el seguimiento de la flota, es importante indicar el resultado real de una tarea a fin de que se pueda mostrar un resultado de entrega.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setState(Task.State.CLOSED) // It's only possible to directly CLOSE a
  .build();                    // task which is NOT assigned to a vehicle.

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("state"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state

<id> es un identificador único de la tarea.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

• Campos obligatorios:

  Campo	Valor
  final	Estado.CLOSED

• Campos opcionales:

  Campo	Valor
  Resultado de la tarea	Resultado.SUCCEEDED o Resultado.ERROR
  TaskResultTime	La hora en que se completó la tarea.
  TaskResultLocation (Ubicación)	La ubicación donde se completó la tarea. Fleet Engine aplicará esta configuración de forma predeterminada a la última ubicación del vehículo, a menos que el proveedor la anule manualmente.

Todos los demás campos de la entidad se ignoran para la actualización.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "state": "CLOSED",
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)"
}
EOM

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para establecer el resultado de una tarea como COMPLETA y establecer la ubicación en la que se completó:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskOutcome(TaskOutcome.SUCCEEDED)
  .setTaskOutcomeTime(now())
  .setTaskOutcomeLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation

<id> es un identificador único de la tarea.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

• Campos obligatorios:

  Campo	Valor
  Resultado de la tarea	Resultado.SUCCEEDED o Resultado.ERROR
  TaskResultTime	La marca de tiempo del momento en que se estableció el resultado de la tarea (desde el proveedor). Este es el momento en que se completó la tarea.

• Campos opcionales:

  Campo	Valor
  TaskResultLocation (Ubicación)	La ubicación donde se completó la tarea. Fleet Engine aplicará esta configuración de forma predeterminada a la última ubicación del vehículo, a menos que el proveedor la anule manualmente.

Todos los demás campos de la entidad se ignoran para la actualización.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)",
  "taskOutcomeLocation": {
    "point": {
      "latitude": -6.195139,
      "longitude": 106.820826
    }
  }
}
EOM

Redirigir un envío

Una vez que se crea una tarea de envío, no se puede cambiar su ubicación planificada. Para redireccionar un envío, cierra la tarea de envío sin establecer un resultado y, luego, crea una tarea nueva con la ubicación planificada actualizada. Después de crear la tarea nueva, asígnala al mismo vehículo. Para obtener más información, consulta cómo cerrar la tarea de envío y cómo asignar la tarea.

Usar comederos y vehículos de reparto

Si usas vehículos de alimentación para transportar envíos a vehículos de entrega a lo largo del día, modela la transferencia de envíos como una tarea de parada programada para el vehículo de entrega. A fin de garantizar un seguimiento exacto de la ubicación, solo asigna una tarea de entrega para un envío transferido después de que se cargue en el vehículo de entrega. Para obtener más información, consulta Parada programada.

Almacena el estado del envío y otra metainformación

Cuando se completa una tarea de envío, el estado y el resultado de la tarea se registran en ella. Sin embargo, es posible que quieras actualizar otra información meta específica del envío. Para almacenar otra metainformación a la que puedas hacer referencia fuera del servicio de Fleet Engine, usa el tracking_id asociado con la tarea como clave en una tabla externa.

Para obtener más información, consulta Ciclo de una tarea.

Cómo buscar un vehículo

Puedes buscar un vehículo desde el SDK del controlador o desde el entorno del servidor.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para buscar un vehículo:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder()  // No need for the header
    .setName(name)
    .build();

try {
  DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para buscar un vehículo desde un entorno de servidor, realiza una llamada HTTP REST a “GetVehicle” de la siguiente manera:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>

<id> es un identificador único de la tarea.

<vehicleId> es el ID del vehículo que se buscará.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe estar vacío.

Si la búsqueda se realiza correctamente, el cuerpo de la respuesta contendrá una entidad de vehículo.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"

Cómo buscar una tarea

Puedes buscar una tarea desde un entorno de servidor. El SDK de Driver no admite la búsqueda de tareas.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para buscar una tarea:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
    .setName(taskName)
    .build();

try {
  Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para buscar una tarea desde un entorno de servidor, realiza una llamada HTTP REST a `GetTask':

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>

<id> es un identificador único de la tarea.

<taskId> es el ID de la tarea que se debe buscar.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe estar vacío.

Si la búsqueda se realiza correctamente, el cuerpo de la respuesta contendrá una entidad de tarea.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

Cómo buscar información de la tarea de envío por su ID de seguimiento

Puedes buscar información de tareas de envío de las siguientes maneras, cada una de las cuales tiene un propósito diferente:

• Por un ID de tarea: La usan los usuarios, como los operadores de flotas, que tienen acceso a la vista completa de los datos de la tarea.
• Por ID de seguimiento: El software cliente lo usa para proporcionar información limitada a un usuario final, como cuándo llega un paquete a su casa.

En esta sección, se explica cómo buscar información de tareas mediante un ID de seguimiento. Si deseas buscar una tarea por el ID de tarea, ve a Cómo buscar una tarea.

Para buscar información mediante un ID de seguimiento, puede utilizar cualquiera de las siguientes opciones:

• Búsquedas con Java mediante gRPC
• Búsquedas con HTTP

Requisitos para la búsqueda

• La información de envío que proporciona un ID de seguimiento cumple con las reglas de visibilidad establecidas en Cómo controlar la visibilidad de las ubicaciones con seguimiento.

• Usa Fleet Engine para buscar información de envío por ID de seguimiento. El SDK de Driver no admite las búsquedas de información por ID de seguimiento. Para hacerlo con Fleet Engine, usarás un entorno de servidor o de navegador.

• Usa el token más estrecho posible para limitar los riesgos de seguridad. Por ejemplo, si usas un token de consumidor de entrega, cualquier llamada a la API de Fleet Engine Deliveries mostrará solo información relevante para ese usuario final, como el transportista o el receptor de un envío. Se oculta el resto de la información de las respuestas. Para obtener más información sobre los tokens, consulta Crea un token web JSON (JWT) para autorización.

Búsquedas con Java mediante gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para buscar información sobre una tarea de envío según su ID de seguimiento.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Búsquedas con HTTP

Para buscar una tarea de envío desde un navegador, realiza una llamada REST HTTP a GetTaskTrackingInfo:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>

<tracking_id> es el ID de seguimiento asociado con la tarea.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.

Si la búsqueda se realiza correctamente, el cuerpo de la respuesta contendrá una entidad taskTrackingInfo.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

Enumerar tareas

Puedes enumerar tareas de un entorno de servidor o navegador. El SDK de Driver no admite la creación de listas de tareas.

Para enumerar tareas, se requiere un acceso amplio a ellas. La enumeración de tareas está destinada solo a usuarios de confianza. Usa el lector de flota de entrega o los tokens de autenticación de superusuario de entrega cuando realices solicitudes de tareas de lista.

Las tareas enumeradas tienen los siguientes campos ocultos:

• VehicleStop.schedule_location
• VehículoParada.estado
• VehicleStop.TaskInfo.taskId

Las tareas enumeradas se pueden filtrar según las propiedades de la mayoría de las tareas. Para ver la sintaxis de la consulta de filtros, consulta AIP-160. En la siguiente lista, se muestran las propiedades de tareas válidas que puedes usar para filtrar:

• attributes
• id_vehículo_entrega
• final
• ubicación_planificada
• duración_tarea
• resultado_tarea
• ubicación_de_resultado_tarea
• fuente_de_ubicación_de_los_resultados_tarea
• hora_de_resultado_tarea
• id_seguimiento
• tipo

Usa los siguientes formatos de campos basados en las propuestas de mejoras de la API de Google:

Consulta AIP-160 para obtener una lista completa de los operadores de consulta de filtro.

Si no se especifica una consulta de filtro, se enumeran todas las tareas.

Las listas de tareas están paginadas. Se puede especificar el tamaño de una página en las solicitudes de tareas de lista. Si se especifica el tamaño de una página, la cantidad de tareas que se muestran no es mayor que el tamaño de página especificado. Si no hay un tamaño de página, se usa un valor predeterminado razonable. Si el tamaño de la página solicitado supera un valor máximo interno, se usará el máximo interno.

Una lista de tareas puede incluir un token para leer la siguiente página de resultados. Usa el token de la página con una solicitud idéntica a la anterior para recuperar la siguiente página de tareas. Cuando el token de la página que se muestra está vacío, no hay más tareas disponibles para recuperar.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para enumerar tareas de un deliveryVehicleId y un atributo de tarea. Una respuesta correcta puede estar vacía de todos modos. Una respuesta vacía indica que no hay tareas asociadas al deliveryVehicleId proporcionado.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
    .build();

try {
  ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para enumerar las tareas desde un navegador, haz una llamada REST HTTP a ListTasks:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks

Para aplicar un filtro a las tareas enumeradas, incluye un parámetro de URL "filter" con una consulta de filtro con escape de URL como su valor.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

Si la búsqueda se realiza correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

// JSON representation
{
  "tasks": [
    {
      object (Task)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Una respuesta correcta puede estar vacía de todos modos. Una respuesta vacía indica que no se encontraron tareas que cumplan con los criterios de filtro especificados.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

Enumerar los vehículos de entrega

Puedes obtener una lista de los vehículos de entrega desde un entorno de servidor o navegador. El SDK de Driver no admite la creación de fichas de vehículos de entrega.

La ficha de vehículos de entrega solicita un acceso amplio a los vehículos de entrega y está dirigido solo a usuarios de confianza. Usa el lector de flota de entrega o los tokens de autenticación de superusuario de entrega cuando realices solicitudes de vehículos de entrega de listas.

Los vehículos de entrega enumerados tienen los siguientes campos ocultos debido a su impacto en el tamaño de la respuesta:

• Segmento de ruta actual
• Segmentos de recorrido del vehículo restantes

Puedes filtrar los vehículos de entrega de listas por su propiedad attributes. Por ejemplo, para consultar un atributo con la clave my_key y el valor my_value, usa attributes.my_key = my_value. Para buscar varios atributos, une las consultas mediante los operadores lógicos AND y OR, como en attributes.key1 = value1 AND attributes.key2 = value2. Consulta AIP-160 para obtener una descripción completa de la sintaxis de consulta de filtro.

Puedes filtrar los vehículos de entrega que se muestran por ubicación mediante el parámetro de la solicitud viewport. El parámetro de solicitud viewport define los viewports mediante dos coordenadas de límite: una latitud y longitud high (nordeste) y low (sudoeste). Las solicitudes se rechazan si contienen una latitud alta que es geográficamente inferior a una latitud baja.

Las listas de vehículos de entrega se paginan de forma predeterminada con un tamaño de página razonable. Si especificas un tamaño de página, la solicitud mostrará solo la cantidad de vehículos que se especifica en el límite o menos. Si el tamaño de la página solicitado supera un valor máximo interno, se usará el máximo interno. El tamaño máximo y predeterminado de las páginas son de 100 vehículos.

Una lista de vehículos de entrega puede incluir un token para leer la siguiente página de resultados. Un token de página solo está presente en una respuesta cuando hay más páginas de vehículos de entrega disponibles para su recuperación. Para recuperar la página siguiente de tareas, usa el token de la página con una solicitud idéntica a la anterior.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para enumerar los vehículos de entrega en una región específica con un atributo determinado. Una respuesta correcta puede estar vacía de todos modos. Cuando eso sucede, significa que no hay vehículos con el atributo especificado actualmente en el viewport especificado.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
  ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setViewport(
            Viewport.newBuilder()
              .setHigh(LatLng.newBuilder()
                  .setLatitude(37.45)
                  .setLongitude(-122.06)
                  .build())
              .setLow(LatLng.newBuilder()
                  .setLatitude(37.41)
                  .setLongitude(-122.11)
                  .build())
      .setFilter("attributes.my_key = my_value")
      .build();

try {
  ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
      deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
          break;

      case PERMISSION_DENIED:
          break;
  }
  return;
}

REST

Para enumerar las tareas desde un navegador, haz una llamada REST HTTP a ListDeliveryVehicles:

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles

Para aplicar un filtro a las tareas enumeradas, incluye un parámetro de URL "filter" con una consulta de filtro con escape de URL como su valor.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token creado por una fábrica de tokens de Fleet Engine.

Si la búsqueda se realiza correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

// JSON representation
{
  "deliveryVehicles": [
    {
      object (DeliveryVehicle)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Una respuesta correcta puede estar vacía de todos modos. Cuando eso sucede, significa que no se encontraron vehículos de entrega que cumplan con la consulta de filtro y el viewport especificados.

Comando curl de ejemplo

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"

Seguimiento de la flota

Tienes dos opciones para usar la API de Fleet Engine Deliveries a fin de habilitar el seguimiento de flota:

• Opción preferida: Usa la biblioteca de seguimiento de flota de JavaScript. La biblioteca te permite visualizar la ubicación de los vehículos y las ubicaciones de interés a las que se les realiza un seguimiento en Fleet Engine. Contiene un componente de mapa de JavaScript que es un reemplazo directo de un objeto google.maps.Map estándar y componentes de datos para conectarse con Fleet Engine. Esto te permite proporcionar una experiencia de seguimiento de flota animada y personalizable desde tu aplicación web o para dispositivos móviles.

• Implementa tu propio seguimiento de flota sobre la API de Fleet Engine Deliveries.

Registros

Puedes habilitar una opción para permitir que Fleet Engine envíe registros de RPC a Cloud Logging. Para obtener más información, consulta Logging.

Como se describe en Integra la API de Deliveries y las notas de autorización para casos de uso individuales, realizar llamadas a Fleet Engine requiere autenticación con tokens web JSON que se hayan firmado con credenciales de cuenta de servicio. Las cuentas de servicio que se usan para crear esos tokens pueden tener uno o más roles, y cada uno concede un conjunto diferente de permisos.

Para obtener más información, consulta Autenticación y autorización.

Solución de problemas

Resiliencia

Fleet Engine no se considera una fuente de información. Eres responsable de restablecer el estado de tu sistema, si es necesario, sin depender de Fleet Engine.

Estado perdido en Fleet Engine

Cuando trabajes con Fleet Engine, implementa clientes para que el sistema se recupere si hay una falla. Por ejemplo, cuando Fleet Engine intenta actualizar un vehículo, es posible que responda con un error que indique que el vehículo no existe. Luego, el cliente debe volver a crear el vehículo en el estado nuevo. Esto no suele ocurrir; el sistema debe ser resiliente en caso de que surja.

En la situación extremadamente improbable de una falla catastrófica de Fleet Engine, es posible que debas volver a crear la mayoría de los vehículos y las tareas, o todos ellos. Si la tasa de creación es demasiado alta, algunas solicitudes pueden volver a fallar debido a problemas de cuota, ya que se realizan verificaciones de cuota para evitar ataques de denegación del servicio (DoS). En este caso, disminuye la tasa de recreación mediante una estrategia de retirada para los reintentos.

Pérdida de estado en la app del conductor

Si falla la app del controlador, esta debe volver a crear el estado actual dentro del SDK de Driver. La app debe intentar recrear las tareas para asegurarse de que existan y restablecer sus estados actuales. La app también debe recrear y establecer de forma explícita la lista de paradas para el SDK de Driver.

Ten en cuenta que estos restablecimientos deben realizarse de forma autónoma sin depender de información de Fleet Engine, excepto en los errores que indican si ya existe una entidad en la base de datos y cuándo. Si una entidad ya existe, ese error se puede absorber y la entidad se puede actualizar con su ID.

Preguntas frecuentes

¿Qué sucede si un conductor se detiene por una tarea desordenada?

En este caso, primero debes actualizar el orden de las tareas y, luego, continuar con normalidad, marcando la llegada a la parada, la finalización de la tarea, etc. De lo contrario, el sistema puede volverse inconsistente. Las horas de llegada estimadas pueden ser incorrectas y se pueden informar errores inesperados.