Comienza a usar Fleet Engine para Fleet Performance

Modela las actividades de tu flota para la primera y última milla de las entregas con la API de entregas de Fleet Engine. Puedes usar esta API con el SDK de Driver para iOS y Android, o directamente con REST HTTP o llamadas gRPC.

Configuración inicial

Configura la API de entregas de Fleet Engine en la consola de Google Cloud.

Verifica la configuración

Después de crear cuentas de servicio, verifica que la configuración esté completa y que puedas crear un vehículo de entrega. Verificar tu configuración de inmediato garantiza que hayas solucionado los problemas de autorización comunes que pueden surgir cuando configuras tu proyecto. Existen dos maneras de verificar la configuración:

Bibliotecas cliente

Para una mejor experiencia de desarrollador sobre gRPC o REST sin procesar, usa las bibliotecas cliente en varios lenguajes de programación comunes. Si deseas obtener instrucciones para obtener bibliotecas cliente para la aplicación de servidor, consulta Bibliotecas cliente

En los ejemplos de Java que se incluyen en esta documentación, se supone que estás familiarizado con gRPC.

Estructuras de datos

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

  • Es el vehículo de entrega que se usó para transportar el envío.
  • Las tareas de retiro y entrega del envío.

También puedes usar tareas para modelar los descansos de los conductores y las paradas programadas a lo largo del día.

Vehículos de entrega

Los vehículos de entrega transportan envíos desde un depósito a una ubicación de entrega y desde una ubicación de retiro hasta el depósito. En algunos casos, también es posible que transporten un envío directamente desde la ubicación de retiro hasta la de entrega.

Usa 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.

Nota: Puedes asignar hasta 500 tareas y 300 segmentos de recorrido del vehículo restantes a los objetos DeliveryVehicle.

Tareas

Debes asignar tareas según el tipo de acción para las acciones que realiza un vehículo durante el día:

  • En el caso de los retiros y las entregas, asigna tareas de envío.
  • En los momentos en que los conductores no están disponibles, como las pausas necesarias, asigna Tareas de no disponibilidad.
  • En el caso de las tareas que no son de conducción en los buzones de entrega o las ubicaciones de los clientes, asigna tareas de detención programadas.

Cada tarea que asignas debe tener un ID de tarea único, pero las tareas pueden compartir el mismo ID de seguimiento. Cuando Fleet Engine calcula las ventanas de hora de llegada estimada para cada tarea, utiliza todas las tareas y el orden en el que están programadas para hacer estimaciones. Para obtener más información sobre los IDs de tareas, consulta Lineamientos de los IDs de tareas.

Para crear tareas en Fleet Engine, usa el Administrador de tareas del SDK de Driver.

Tareas de envío

Crea tareas de envío para el retiro y la entrega de un envío y, además, incluye la siguiente información:

  • Es la ubicación del punto de partida o de la entrega.
  • Un número o ID de seguimiento.
  • Un tiempo de permanencia para tener en cuenta el tiempo adicional para completar la tarea, buscar estacionamiento o caminar a la ubicación de transferencia.
  • Un ID de tarea único. Consulta los lineamientos del ID de tarea.

Para obtener más información, consulta los siguientes temas:

Android

iOS

Tareas de no disponibilidad

Las tareas de no disponibilidad abarcan los períodos en los que un vehículo no está disponible para retiros o entregas, como las pausas para reabastecer el vehículo o las pausas para el descanso del conductor.

Crea una tarea de no disponibilidad con la siguiente información:

  • La duración del descanso.
  • De forma opcional, la ubicación de la pausa. No es necesario que proporciones una ubicación específica, pero hacerlo permite generar ventanas de hora de llegada más precisas a lo largo del día.

Para obtener más información, consulta los siguientes temas:

Android

iOS

Tareas de detención programadas

Crea tareas de parada programadas para modelar las paradas que debe hacer un vehículo de entregas. Por ejemplo, crea una tarea de parada programada para una parada de recolección programada diaria en una ubicación específica, independiente de otras entregas o retiros en la misma ubicación. También puedes crear tareas de paradas programadas para cobros desde buzones de despedida o para transbordos o paradas de vehículos de alimentación en centros de servicio y puntos de servicio.

Para obtener más información, consulta los siguientes temas:

Android

iOS

Lineamientos del ID de tarea

Cuando crees los IDs de tarea, sigue estos lineamientos de contenido y formato:

  • Crea IDs de tareas únicos
  • No expongas información de identificación personal (PII) ni datos de texto claro.
  • Usa cadenas Unicode válidas.
  • Usa 64 caracteres como máximo.
  • No incluyas ninguno de los siguientes caracteres ASCII: "/", ":", "\", "?" o "#".
  • Normaliza según el Formulario de normalización C de Unicode.

A continuación, se incluyen algunos ejemplos de ID de tareas útiles:

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

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

IDs de tareas no compatibles Motivo
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 Infringe los requisitos de PII y caracteres: comas, puntos, dos puntos y barras diagonales.
JohnDoe-577b484da26f-Cupertino-SantaCruz Infringe los requisitos de PII.
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a Infringe los requisitos de PII y caracteres: espacios en blanco, comas y comillas. Tiene más de 64 caracteres.

Más recursos

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

Duración de un vehículo

El objeto DeliveryVehicle representa un vehículo de entrega de tramo inicial o de último kilómetro. Para crear un objeto DeliveryVehicle, debes usar lo siguiente:

  • El ID del proyecto de Google Cloud que contiene la cuenta de servicio que se usa para llamar a las APIs de Fleet Engine.
  • El ID del vehículo del cliente.

Usa IDs de vehículos que sean únicos para cada vehículo. No vuelvas a usar un ID de vehículo, a menos que no haya tareas activas para el vehículo original.

Fleet Engine borra de forma automática los objetos DeliveryVehicle que no se hayan actualizado con UpdateDeliveryVehicle después de siete días. Para ver si existe un vehículo, haz lo siguiente:

  1. Haz una llamada a UpdateDeliveryVehicle.
  2. Si recibes un error NOT_FOUND, llama a CreateDeliveryVehicle para volver a crear el vehículo. Si la llamada devuelve un vehículo, este seguirá disponible para actualizarse.

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. DeliveryVehicleAttribute no afecta el comportamiento del enrutamiento de Fleet Engine.

No incluyas información de identificación personal (PII) ni información sensible en los atributos, ya que este campo puede ser visible para los usuarios.

El ciclo de vida de una tarea

Puedes crear, actualizar y consultar tareas en Fleet Engine con 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 a lo largo de su ciclo de vida. Los valores pasarán de OPEN a CLOSED. Las tareas nuevas se crean en el estado OPEN, 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 de vehículos asignada para la tarea.

Lineamientos para las tareas

Solo puedes asignar una tarea a un vehículo cuando está en estado ABIERTO.

Si deseas cancelar una tarea, quítala de la lista de paradas del vehículo, lo que establece el estado de la tarea como CERRADO automáticamente.

Cuando el vehículo de la tarea complete la parada del vehículo, ocurrirá lo siguiente:

  1. Actualiza el campo de resultado de la tarea a SUCCEEDED o FAILED.

  2. Especifica la marca de tiempo del evento.

    Luego, la biblioteca de seguimiento de flota de JavaScript indica el resultado de la tarea y su estado se establece en CLOSED automáticamente. 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, Fleet Engine borra las tareas que no se actualizaron después de siete días, y si intentas 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 retener datos de tareas por más de siete días, debes implementar esa función por tu cuenta.

Atributos de la tarea

La entidad Task contiene un campo repetido de TaskAttribute, que puede tener un 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 atributos de la tarea no afectan el comportamiento de enrutamiento de Fleet Engine.

No incluyas información de identificación personal (PII) ni otra información sensible en los atributos, ya que pueden ser visibles para los usuarios.

Administra el ciclo de vida del vehículo y las tareas

Recordatorio: Tu sistema interno actúa como la fuente confiable de los datos que la API de Fleet Engine Deliveries aumenta en tu nombre.

Para administrar los ciclos de vida de vehículos y tareas en tu sistema, usa la API de entregas de Fleet Engine para crear, actualizar y realizar un seguimiento de tus vehículos y sus tareas asociadas.

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. Envía la ubicación directamente a la biblioteca de seguimiento, que luego puedes usar para actualizar a los consumidores sobre el estado de su pedido.

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

  • Un conductor se acerca a una parada de entrega. La aplicación del controlador envía su ubicación a Fleet Engine.
  • 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 acerca de la proximidad de su paquete.
  • Después de que el conductor complete el envío, debe hacer clic en el botón "Envío entregado" en la aplicación del conductor.
  • La acción “Envío entregado” 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 confirma la tarea como COMPLETA y actualiza Fleet Engine con la API de entregas.

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

Integra el diagrama de la API de Deliveries>

Administra tokens de cliente

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. Este es el enfoque recomendado para controlar las actualizaciones del cliente a Fleet Engine:

  1. Genera el token con el rol de cuenta de servicio Usuario de controlador no confiable de entrega de Fleet Engine.

  2. Proporciona a la aplicación del controlador un token de permiso limitado. Este permiso solo le permite actualizar la ubicación del dispositivo en Fleet Engine.

Este enfoque garantiza que las llamadas que se originan desde dispositivos móviles (que se consideran entornos de baja confianza) cumplan con el principio de privilegio mínimo.

Otros roles de la cuenta de servicio

Si, en cambio, deseas autorizar las aplicaciones del controlador para que 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 el rol de controlador de confianza. Para obtener información sobre un modelo que usa la función de controlador 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 confiables, consulta Configuración de proyectos de Cloud.

Cómo modelar un día laboral

En la siguiente tabla, se describe cómo sería un día laboral para los conductores que conducen el primer o el último tramo en una empresa de entregas y logística. Tu empresa puede diferir en los detalles, pero puedes ver cómo podrías adaptar un día laboral.

TiempoActividadModelado
Dentro de las 24 horas posteriores al inicio del día El despachador asigna los envíos a vehículos o rutas de entrega. Puedes crear tareas para entregas de envíos, recogidas, descansos y otras en Fleet Engine con anticipación. Por ejemplo, puedes crear una tarea de retiro de envío, una tarea de entrega de envío, una no disponibilidad programada o una parada programada.

Asigna tareas a un vehículo una vez que se finalicen el conjunto de paquetes de entrega y el orden en que deben entregarse.
Inicio del día El conductor inicia el día en el depósito accediendo a la app del conductor. Inicializa la API de Delivery Driver. Crea el vehículo de entrega en Fleet Engine según sea necesario.
El conductor carga los envíos en el vehículo de entrega y escanea los envíos. Si las tareas de entrega de envíos no se crearon con anticipación, crea tareas de entrega de envíos en el momento del análisis.
El conductor confirma el orden de las tareas que deben realizarse. Si no se crearon con anticipación, crea tareas de retiro de envío, detenciones programadas y paradas programadas.
El conductor abandona el depósito y se confirma la siguiente cantidad de tareas que se deben completar. Confirma el orden de finalización para asignar todas las tareas o un subconjunto de tareas al vehículo.
El conductor entrega un envío. Después de llegar a la parada de entrega, realiza acciones relacionadas con un vehículo que llega a una parada. Después de entregar el envío, cierra la tarea de entrega y, de forma opcional, almacena el estado del envío y otra metainformación. Después de completar todas las tareas en la parada y antes de comenzar a conducir a la siguiente parada, realiza acciones relacionadas con el vehículo completa una parada y el vehículo se dirige a la siguiente parada.
El conductor se encuentra con un vehículo de alimentación para transferir envíos adicionales al vehículo de entrega. El punto de encuentro para un transbordo entre vehículos alimentadores y de entrega debe modelarse como una parada programada.

Después de transferir y escanear los envíos, crea tareas de entrega si aún no se han creado. Luego, actualiza el orden de finalización de las tareas asignando tareas a un vehículo y actualizando el orden de las tareas.
El conductor recibe una notificación de una solicitud de recogida. Después de aceptar la solicitud de retiro, crea una tarea de retiro de envío. Luego, actualiza el orden de ejecución de la tarea asignando tareas a un vehículo y actualizando el orden de las tareas.
Mediodía El conductor se toma el descanso para almorzar. Si una ubicación está asociada con la tarea de no disponibilidad, trátala como a cualquier otra tarea. Realiza acciones relacionadas con un vehículo que llegue a una parada, el vehículo completa una parada y el vehículo se dirige a la siguiente parada.

De lo contrario, no es necesario que realices ninguna otra acción hasta el final de la pausa. Para quitar la tarea, confirma las tareas siguientes y restantes, y actualiza el orden de las tareas.
El conductor recoge un envío. Se modela como una parada de entrega. Realiza acciones relacionadas con un vehículo que llegue a una parada y cierra una tarea y, de manera opcional, almacena el estado del envío y otra metainformación. Después de completar todas las tareas en la parada y antes de comenzar a conducir hacia la siguiente parada, realiza acciones relacionadas con el vehículo completa una parada y el vehículo se dirige a la siguiente parada. Nota: Para garantizar una facturación correcta, todos los lugares de retiro deben tener una tarea de entrega correspondiente. Si el lugar de partida debe entregarse en otra ubicación de la misma ruta del conductor ese día, recomendamos modelar esa tarea de entrega como cualquier otra tarea de entrega en la ruta. Si el conductor llevará de vuelta al depósito, te recomendamos que crees una tarea de entrega en el destino del depósito.
Un conductor hace una parada programada para recoger los envíos de un buzón. Este modelo tiene el mismo modelo que cualquier otra parada de recogida. Realiza acciones relacionadas con un vehículo que llega a una parada y cierra una tarea. Después de completar todas las tareas en la parada y comenzar a conducir a la siguiente parada, realiza acciones relacionadas con el vehículo completa una parada y el vehículo se dirige a la siguiente parada.
El conductor recibe una notificación sobre el desvío de un envío a una ubicación alternativa. Establece el estado original de la tarea de entrega de envío como COMPLETADO y crea una nueva tarea de entrega de envío para la nueva ubicación de entrega. Para obtener más información, consulta Cómo redireccionar un envío.
El conductor intentó entregar un paquete, pero no pudo hacerlo. Este modelo se modela de manera similar a una parada de entrega exitosa, que marca la tarea de entrega como completada. Realiza acciones relacionadas con un vehículo que llega a una parada. Si no logras entregar el envío, cierra la tarea y, de forma opcional, almacena el estado del envío y otra metainformación. Después de completar todas las tareas en la parada y antes de comenzar a conducir hacia la siguiente parada, realiza acciones relacionadas con el vehículo completa una parada y el vehículo se dirige a la siguiente parada.
Se notificó al conductor que debía retener (no entregar) un envío. Después de recibir y confirmar la notificación, establece el estado de la tarea como COMPLETED.
Se notificó al conductor que realizara un determinado envío a continuación, lo que cambió el pedido de entrega comprometido. Actualiza el orden de las tareas.
El conductor elige entregar el envío desordenado. Actualiza el orden de las tareas y, luego, procede con normalidad.
El conductor entrega varios envíos a una sola ubicación. Este modelo se modela de manera similar a una única parada de entrega de envíos. Después de llegar a la parada, realiza acciones relacionadas con el vehículo que llega a la parada. Después de entregar cada envío, cierra cada tarea y, de forma opcional, almacena el estado del envío y otra metainformación. Después de completar todas las tareas en la parada y antes de comenzar a conducir hacia la siguiente parada, realiza acciones relacionadas con el vehículo completa una parada y el vehículo se dirige a la siguiente parada.
Fin del día El conductor regresa al depósito. Si el conductor vuelve al depósito con los envíos recogidos en su ruta, también debes crear y cerrar cada paquete como una tarea de entrega para garantizar una facturación correcta. Para ello, modela el depósito como cualquier otra parada de entrega. Si el depósito no se usa como una parada de entrega, aún puedes modelarlo como una parada programada. Modelar la parada permite a los conductores ver la ruta de regreso al depósito y brindar visibilidad de su hora estimada de llegada.

Cómo funcionan las actualizaciones de ubicación

Para obtener el mejor rendimiento con Fleet Engine, proporciónale un flujo de actualizaciones de la ubicación de los vehículos. Utiliza cualquiera de los siguientes métodos para proporcionar estas actualizaciones:

  1. Usa el SDK de Driver para iOS o Android. Es la opción más simple.
  2. Usa un código personalizado, que es útil si las ubicaciones se retransmiten mediante tu backend o si usas dispositivos que no son Android o iOS.

Sin importar cómo proporciones actualizaciones de la ubicación del vehículo, el backend es responsable de actualizar Fleet Engine cuando un vehículo de entrega está en camino a una parada (incluido el depósito) y cuando llega a una parada. Fleet Engine no detecta estos eventos de forma automática.

Paradas de vehículos y ubicaciones de entrega

La parada de un vehículo es donde un vehículo de reparto completa una tarea de envío u otra tarea. Puede ser un punto de acceso, como un conector de carga o una ubicación ajustada a la ruta.

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

Por ejemplo, cuando un conductor entrega un envío a una tienda de un centro comercial, el vehículo de entrega 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 el que se encuentra la tienda. Esta es la ubicación de entrega.

Para brindar la mejor experiencia de seguimiento del envío a tus usuarios, considera cómo se asignan las tareas de envío a las paradas de los vehículos y ten en cuenta que se informa al usuario la cantidad de paradas restantes del vehículo en las tareas de envío para ayudarlo a ver el progreso de su 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, tu experiencia con el seguimiento de envíos sería menos útil para tus usuarios, ya que el seguimiento solo está disponible una vez que el vehículo se encuentra dentro de una cantidad limitada de paradas del vehículo antes de su destino. Tener muchas paradas de vehículos completadas en poco tiempo no le da al usuario mucho tiempo para hacer un seguimiento del progreso de su entrega.

Usa los SDK para dispositivos móviles

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

Inicializa 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 de Driver o desde un entorno de servidor con gRPC o REST.

gRPC

Para crear un vehículo nuevo, debes realizar 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 para el campo Name se ignora 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 DeliveryVehicle, tienes la opción de especificar estos campos:

  • Atributos
  • LastLocation
  • Tipo

No configures ningún otro campo. Si lo haces, Fleet Engine muestra un error porque esos campos son de solo lectura o solo se pueden actualizar con una llamada a 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 desde un entorno de servidor, realiza una llamada REST de HTTP 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>, donde <token> es un token emitido 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
  • lastLocation
  • Tipo

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 los lineamientos de la API para los IDs especificados por el usuario. No configures ningún otro campo. Si lo haces, Fleet Engine muestra un error porque esos campos son de solo lectura o solo se pueden actualizar mediante una llamada a UpdateDeliveryVehicle.

Para crear un vehículo sin configurar ningún campo, deja el cuerpo de la solicitud POST vacío. Luego, el vehículo recién creado extrae un ID de vehículo 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ío

Puedes crear una tarea de retiro de envío desde el SDK de Driver o desde un entorno de servidor con gRPC o REST.

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ío 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 IDs 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>, donde <token> es un token emitido por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

  • Campos obligatorios:

    CampoValor
    Tipo Type.PICKUP
    state State.OPEN
    trackingId El número o identificador que usas para rastrear un envío.
    plannedLocation Es la ubicación donde se debe completar la tarea, en este caso, el lugar de retiro del envío.
    taskDuration El tiempo esperado, en segundos, que se tarda en retirar el envío en el lugar de retiro.

  • Campos opcionales:

    CampoValor
    targetTimeWindow Es el período durante el cual se debe completar la tarea. Esto no afecta el comportamiento del enrutamiento.
    attributes Una lista de atributos personalizados de Tasks. Cada atributo debe tener una clave única.

El resto de los campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Las tareas se asignan con UpdateDeliveryVehicleRequest. Para obtener más información, consulta Cómo asignar tareas a un vehículo y UpdateDeliveryVehicleRequest.

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

Crea una tarea de entrega de envíos desde el SDK de Driver o desde un entorno de servidor con gRPC o REST.

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 con gRPC o REST, realiza una llamada REST HTTP 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 IDs 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>, donde <token> es un token emitido por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

  • Campos obligatorios:

    CampoValor
    Tipo Type.DELIVERY
    state State.OPEN
    trackingId El número o identificador que usas para rastrear un envío.
    plannedLocation La ubicación donde se debe completar la tarea, en este caso, la ubicación de entrega para este envío.
    taskDuration El tiempo esperado, en segundos, que tarda en entregarse el envío en la ubicación de entrega.

  • Campos opcionales:

    CampoValor
    targetTimeWindow Es el período durante el cual se debe completar la tarea. Esto no afecta el comportamiento del enrutamiento.
    attributes Una lista de atributos personalizados de Tasks. Cada atributo debe tener una clave única.

El resto de los campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Las tareas se asignan con UpdateDeliveryVehicleRequest. Para obtener más información, consulta Cómo asignar tareas a un vehículo y UpdateDeliveryVehicleRequest.

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 un entorno de servidor con gRPC o REST.

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 un entorno de servidor, realiza una llamada REST de 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 emitido por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad BatchCreateTasksRequest:

  • Campos obligatorios:

    CampoValor
    solicitudes Arreglo<CreateTasksRequest>

  • Campos opcionales:

    CampoValor
    encabezado "DeliveryRequestHeader"

Cada elemento CreateTasksRequest de 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 nivel superior BatchCreateTasksRequest. Consulta Crea una tarea de entrega de envío y Crea una tarea de entrega de envíos para conocer las reglas de validación específicas para cada una.

Para 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 no disponibilidad (por ejemplo, para descansos de conductores o recargas de combustible de vehículos) desde el SDK de Driver o desde un entorno de servidor con gRPC o REST. Una tarea de indisponibilidad 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 no disponibilidad desde un entorno de servidor, realiza una llamada REST HTTP 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 IDs 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>, donde <token> es un token emitido por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

  • Campos obligatorios:

    CampoValor
    Tipo Type.UNAVAILABLE
    state State.OPEN
    taskDuration Es la duración de la pausa en segundos.

  • Campos opcionales:

    CampoValor
    plannedLocation Es la ubicación de la pausa si se debe tomar en una ubicación específica.

El resto de los campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Las tareas se asignan con UpdateDeliveryVehicleRequest. Para obtener más información, consulta Cómo asignar tareas a un vehículo y UpdateDeliveryVehicleRequest.

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 de Driver o desde un entorno de servidor con gRPC o REST. 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 REST HTTP 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 un 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>, donde <token> es un token emitido por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

  • Campos obligatorios:

    CampoValor
    Tipo Type.SCHEDULED_STOP
    state State.OPEN
    plannedLocation Es la ubicación de la parada.
    taskDuration Es la duración anticipada de la parada en segundos.

  • Campos opcionales:

    • Ninguno

El resto de los campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Las tareas se asignan con UpdateDeliveryVehicleRequest. Para obtener más información, consulta Cómo asignar tareas a un vehículo y UpdateDeliveryVehicleRequest.

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

Establecer período de tiempo objetivo

El período 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 el período 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. El período de tiempo objetivo 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>, donde <token> es un token emitido por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

  • Campos obligatorios:

    CampoValor
    targetTimeWindow Es el período durante el cual se debe completar la tarea. Este parámetro de configuración no afecta el comportamiento del enrutamiento

  • Campos opcionales:

    • Ninguno

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 los datos que se muestran de una llamada a GetTaskTrackingInfo se puede controlar por tarea si configuras un TaskTrackingViewConfig en la tarea. Para obtener más información, consulta Tareas activas del vehículo. Esto puede hacerse 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 establecer la ventana de configuración de la vista del 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>, donde <token> es un token emitido por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

  • Campos obligatorios:

    CampoValor
    taskTrackingViewConfig Es la configuración del seguimiento de tareas que especifica qué elementos de datos son visibles para los usuarios finales y en qué circunstancias.

  • Campos opcionales:

    • Ninguno

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

Cómo asignar tareas a un vehículo

Para asignar tareas a un vehículo de entregas, debes actualizar los pedidos de la tarea del vehículo. El pedido de tareas para un vehículo se determina según la lista de paradas del vehículo, y puedes asignar una o más tareas a cada parada del vehículo. Para obtener más información, consulta Cómo actualizar el orden de las tareas.

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. Si actualizas el orden de una tarea que ya está asignada a otro vehículo, se mostrará un error.

Actualizar el orden de las tareas

Puedes actualizar el orden de las tareas asignadas a un vehículo desde el SDK de Driver o desde el entorno del servidor. No uses ambos para evitar condiciones de carrera y mantener una sola fuente de información.

Cuando actualizas el pedido de tareas para un vehículo, también se hace lo siguiente:

  • Asigna tareas que son nuevas para el vehículo.
  • Cierra todas las tareas que se asignaron previamente al vehículo, pero que no están en el orden actualizado.

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. Si actualizas el orden de una tarea que ya está asignada a otro vehículo, se mostrará un error.

Puedes actualizar el orden de las tareas en cualquier momento.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para actualizar el orden de las 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

Para actualizar el orden de tareas de 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 deseas actualizar el orden de la tarea. Es el identificador que especificaste cuando creaste el vehículo.

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

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

  • Campos obligatorios:

    CampoValor
    remainingVehicleJourneySegments 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.
    restantesVehicleJourneySegments[i].parada La parada para la tarea i en la lista.
    Segmentosderecorridodevehículos[i].detención.planificadaUbicación La ubicación planificada de la parada.
    Segmentosderecorridodeelvehículo restantes[i].detención.tareas Una lista de tareas que se deben realizar en esta parada del vehículo.
    remainingVehicleJourneySegments[i].stop.state State.NEW

  • Campos opcionales:

    • Ninguno

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

El vehículo está en camino a la siguiente parada

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 de Driver o desde un entorno de servidor con gRPC o REST. No uses ambos para evitar condiciones de carrera y mantener una sola fuente de información.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para notificar a Fleet Engine que un vehículo se dirige 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 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 deseas actualizar el orden de la tarea. Es el identificador que especificaste cuando creaste el vehículo.

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

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

  • Campo obligatorio:

    CampoValor
    remainingVehicleJourneySegments Lista de paradas restantes de vehículos con estados marcados como State.NEW. El estado de la primera parada de la lista debe estar marcado como State.ENROUTE.

  • Campos opcionales:

    • Ninguno

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

Actualiza la ubicación del vehículo

Si no usas el SDK de Driver para actualizar la ubicación del vehículo, puedes realizar una llamada directa a Fleet Engine con esa ubicación. Para cualquier vehículo activo, Fleet Engine espera una actualización de ubicación al menos una vez por minuto y como máximo una vez cada 5 segundos.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para actualizar la ubicación de un vehículo en Fleet Engine:

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 myDeliveryVehicle = DeliveryVehicle.newBuilder()
    .setLastLocation(DeliveryVehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(myDeliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("last_location"))
      .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 actualizar la ubicación de un vehículo en Fleet Engine mediante REST de HTTP, realiza una llamada a UpdateDeliveryVehicle:

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

<id> es un identificador único del vehículo de entrega de tu flota o que quieres actualizar la ubicación. Es el identificador que especificaste cuando creaste el vehículo.

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

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

  • Campo obligatorio:

    CampoValor
    lastLocation.supplementalLocation Es la ubicación del vehículo.
    lastLocation.supplementalLocationTime La última marca de tiempo conocida en la que el vehículo estuvo en esta ubicación
    lastLocation.supplementalLocationSensor Debe completarse con CUSTOMER_SUPPLIED_LOCATION.

  • Campos opcionales:

    CampoValor
    lastLocation.supplementalLocationAccuracy Precisión de la ubicación proporcionada en metros.

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
{
  "lastLocation": {
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
  }
}
EOM

El vehículo llega a una parada

Se debe notificar a Fleet Engine cuando un vehículo llega a una parada. Puedes notificar a Fleet Engine desde el SDK de Driver o desde un entorno de servidor con gRPC o REST. No uses ambos para evitar condiciones de carrera y mantener una sola fuente de información.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca 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 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 deseas actualizar el orden de la tarea. Es el identificador que especificaste cuando creaste el vehículo.

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

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

  • Campos obligatorios:

    CampoValor
    remainingVehicleJourneySegments La parada a la que llegaste con el estado establecido como State.ARRIVED, seguida de una lista de las paradas restantes de los vehículos con el estado marcado como State.NEW.

  • Campos opcionales:

    • Ninguno

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

El vehículo completa una parada

Se debe notificar a Fleet Engine cuando un vehículo completa una parada. Esto hace que todas las tareas asociadas con la parada tengan el estado CLOSED. Puedes notificar a Fleet Engine desde el SDK de Driver o desde un entorno de servidor con gRPC o REST. No uses ambos 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 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 desde 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 deseas actualizar el orden de la tarea. Es el identificador que especificaste cuando creaste el vehículo.

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

El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

  • Campos obligatorios:

    CampoValor
    remaining_vehicle_journey_segments La parada que hayas completado ya no debe estar en la lista de paradas restantes de vehículos.

  • Campos opcionales:

    • Ninguno

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}"
              }
            ]
          }
        }
      ]
    }
    EOM

Cómo actualizar una tarea

La mayoría de los campos de tareas son inmutables. Sin embargo, puedes modificar el estado, el resultado de la tarea, el tiempo del resultado de la tarea, la ubicación del resultado de la tarea y los atributos mediante la actualización directa de la entidad de la tarea. Por ejemplo, en los casos en que una tarea no se haya asignado a un vehículo, puedes cerrarla actualizando el estado directamente.

gRPC

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

REST

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

Cómo cerrar una tarea

Para cerrar una tarea asignada a un vehículo, notifica a Fleet Engine que el vehículo completó la parada en la que se realiza la tarea o quítala 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 CERRADO. Sin embargo, no puedes volver a abrir 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 flotas, es importante indicar el resultado real de una tarea a fin de que se pueda mostrar el resultado de la entrega.

gRPC

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) // You can only directly CLOSE a
  .build();                    // task that 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;
}

REST

Para marcar una tarea como cerrada desde un entorno de servidor, realiza una llamada REST HTTP a UpdateTask:

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

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

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

Debes incluir una entidad Task en el cuerpo de la solicitud:

  • Campos obligatorios:

    CampoValor
    state State.CLOSED

  • Campos opcionales:

    CampoValor
    taskOutcome Result.SUCCEEDED o Result.FAILED
    taskOutcomeTime Es la hora en que se completó la tarea.
    taskOutcomeLocation Es la ubicación donde se completó la tarea. Fleet Engine establece de forma predeterminada esto en la última ubicación del vehículo, a menos que el proveedor lo 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

Establecer el resultado de la tarea y la ubicación del resultado

El cierre de una tarea no indica éxito o fracaso, indica que la tarea ya no se considera en curso. Para el seguimiento de flotas, es importante indicar el resultado real de una tarea de modo que se pueda mostrar un resultado de entrega y que los servicios se facturen de forma adecuada. Una vez establecida, no puedes cambiar el resultado de la tarea. Sin embargo, puedes modificar el tiempo del resultado de la tarea y la ubicación del resultado de la tarea después de que se hayan configurado.

El resultado de las tareas que están en estado CLOSED puede ser SUCCEEDED o FAILED. Fleet Engine solo cobra las tareas de entrega con el estado SUCCEEDED.

Cuando marcas el resultado de una tarea, Fleet Engine completa automáticamente la ubicación del resultado de la tarea con la ubicación conocida del vehículo más reciente. Puedes anular este comportamiento.

gRPC

Tienes la opción de establecer la ubicación del resultado de la tarea cuando configuras el resultado. Establecer la ubicación evita que Fleet Engine la establezca en el valor predeterminado de la última ubicación del vehículo. También puedes reemplazar la ubicación de resultado de la tarea que estableció Fleet Engine más adelante. Fleet Engine nunca reemplaza una ubicación de resultado de tarea que proporciones. No puedes establecer una ubicación de resultados de tareas para una tarea que no tiene un conjunto de resultados de tareas. Puedes establecer el resultado de la tarea y la ubicación del resultado de la tarea dentro de la misma solicitud.

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ó la tarea:

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;
}

REST

Para marcar una tarea como completada desde un entorno de servidor, realiza una llamada REST HTTP a UpdateTask:

`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>, donde <token> es un token emitido por una fábrica de tokens de Fleet Engine.

El cuerpo de la solicitud debe contener una entidad Task:

  • Campos obligatorios:

    CampoValor
    taskOutcome Result.SUCCEEDED o Result.FAILED
    taskOutcomeTime La marca de tiempo del momento en que se configuró el resultado de la tarea (desde el proveedor). Este es el momento en que se completó la tarea.

  • Campos opcionales:

    CampoValor
    taskOutcomeLocation Es la ubicación donde se completó la tarea. Fleet Engine establece de forma predeterminada esto en la última ubicación del vehículo, a menos que el proveedor lo 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

Cómo redireccionar un envío

Una vez que se crea una tarea de envío, no se puede cambiar la ubicación planificada. Para redirigir 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 asigna la tarea.

Usar vehículos de alimentación y entrega

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. Para garantizar un seguimiento exacto de la ubicación, solo asigna una tarea de entrega de envío 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 la tarea. Sin embargo, te recomendamos que actualices otros metadatos específicos del envío. Para almacenar otra metainformación a la que puedas hacer referencia fuera del servicio de Fleet Engine, usa el ID de seguimiento asociado con la tarea como clave en una tabla externa.

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

Buscar un vehículo

Puedes buscar un vehículo desde el SDK de Driver o desde un entorno de servidor con gRPC o REST.

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 REST HTTP a GetVehicle:

`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>, donde <token> es un token emitido 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 con gRPC o REST. El SDK de Driver no admite la búsqueda de una tarea.

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 buscará.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, donde <token> es un token emitido 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}"

Buscar información de la tarea de envío por su ID de seguimiento

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

  • Por un ID de tarea: Lo usan los usuarios, como los operadores de flotas, que tienen acceso a la vista completa de los datos de la tarea.
  • Por un ID de seguimiento: El software de tu cliente lo usa para proporcionar información limitada a un usuario final, como cuando se espera un paquete en su casa.

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

Para buscar información por un ID de seguimiento, puedes usar cualquiera de las siguientes opciones:

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 Controla 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 búsquedas de información por ID de seguimiento. Para hacer esto con Fleet Engine, usa 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 solo muestra 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 la autorización.

Realiza 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 por 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 contiene 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 desde un entorno de servidor o navegador. El SDK de Driver no admite la creación de listas de tareas.

Enumerar tareas solicita un acceso amplio a ellas. La enumeración de tareas está destinada solo a usuarios de confianza. Usa el lector de flotas de entrega o los tokens de autenticación de superusuario de entrega cuando realices solicitudes de tareas de listas.

Las tareas enumeradas tienen los siguientes campos ocultos:

  • VehicleStop.planned_location
  • VehicleStop.state
  • VehicleStop.TaskInfo.taskId

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

  • attributes
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_outcome
  • task_outcome_location
  • task_outcome_location_source
  • task_outcome_time
  • tracking_id
  • Tipo

Usa los siguientes formatos de campo basados en las propuestas de mejoras de las APIs de Google:

Tipo de campo Formato Ejemplo
Marca de tiempo RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Duración Cantidad de segundos seguidos de un s task_duration = 120s
Enum String state = CLOSED AND type = PICKUP
Location point.latitude y point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

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 será mayor que el tamaño de la página especificado. Si no hay ningún 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 su recuperación.

gRPC

En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para enumerar las tareas de un deliveryVehicleId y un atributo de tarea. Una respuesta exitosa aún puede estar vacía. Una respuesta vacía indica que no hay tareas asociadas con el 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, realiza 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 búsqueda de filtro con escape de URL como su valor.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, donde <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á datos con la siguiente estructura:

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

Una respuesta correcta puede estar vacía aún. 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}"

Enumera los vehículos de entrega

Puedes enumerar los vehículos de entrega desde un entorno de servidor o navegador. El SDK de Driver no admite la creación de listas de vehículos de entrega.

Enumerar vehículos de entrega solicita un acceso amplio a estos vehículos y está destinado solo a usuarios de confianza. Usa el lector de flotas 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 que se muestran tienen los siguientes campos ocultos debido a su impacto en el tamaño de la respuesta:

  • CurrentRouteSegment
  • RemainingVehicleJourneySegments

Puedes filtrar la lista de vehículos de entrega 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 con 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 enumerados por ubicación con el parámetro de solicitud viewport. El parámetro de solicitud viewport define viewports con dos coordenadas de límite: un par de coordenadas de latitud y longitud high (nordeste) y low (sudoeste). Las solicitudes se rechazan si contienen una latitud alta geográficamente menor que 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 solo mostrará 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. Los tamaños de página predeterminados y máximos 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 aún. Cuando eso sucede, significa que ningún vehículo con el atributo especificado ya está 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, realiza 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>, donde <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á datos con la siguiente estructura:

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

Una respuesta correcta puede estar vacía aún. 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 flota

Tienes dos opciones para usar la API de entregas de Fleet Engine para habilitar el seguimiento de flotas:

  • Preferido: 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 que se rastrean en Fleet Engine. Contiene un componente de mapa de JavaScript que es un reemplazo directo de un objeto google.maps.Map estándar, además de componentes de datos para conectarse con Fleet Engine. Este componente te permite proporcionar una experiencia de seguimiento de flota personalizada y animada desde tu aplicación web o para dispositivos móviles.

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

La clave es buscar tareas de flota por ID de seguimiento.

Logging

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

Roles y tokens de autorización

Como se describe en Administra el ciclo de vida de vehículos y tareas 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 cuentas de servicio. Las cuentas de servicio que se usan para emitir esos tokens pueden tener uno o más roles, y cada función otorga un conjunto diferente de permisos.

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

Soluciona los problemas comunes.

Consulta las siguientes secciones para obtener ayuda si tienes algún problema.

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, puede responder con un error que indica que el vehículo no existe. Luego, el cliente debe volver a crear el vehículo en el estado nuevo. Si bien este problema rara vez ocurre, asegúrate de que el sistema sea lo suficientemente resistente para manejarlo.

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. 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, reduce la frecuencia de recreación con una estrategia de retirada para los reintentos.

Estado perdido en la app del conductor

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

Preguntas frecuentes

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

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