Modela las actividades de tu flota para el primer y el último kilómetro de las entregas con la API de Fleet Engine Deliveries. Puedes usar esta API con el SDK de Driver para iOS y Android, o directamente con llamadas de REST o gRPC de HTTP.
Configuración inicial
Configura la API de Fleet Engine Deliveries en la consola de Google Cloud.
Si deseas obtener información sobre los pasos que se deben seguir en la consola y cómo crear un token web JSON para la autorización, consulta Autenticación y autorización.
Para obtener detalles sobre el uso de la consola, consulta la documentación de la consola de Google Cloud.
Verifica la configuración
Después de crear las cuentas de servicio, verifica que se haya completado la configuración y que puedas crear un vehículo de entrega. Verificar la configuración de inmediato garantiza que hayas solucionado los problemas comunes de autorización que pueden surgir cuando configuraste el proyecto. Existen dos maneras de verificar la configuración:
Prueba dos partes clave de tu configuración: la firma del token de autorización y la creación de vehículos de entrega de prueba con la utilidad de línea de comandos
gcloud. Para obtener más detalles, consulta la guía Verifica tu configuración.Prueba la configuración con las secuencias de comandos de muestra de autenticación de Flet Engine.
Bibliotecas cliente
Para obtener una mejor experiencia del desarrollador con gRPC o REST sin procesar, usa las bibliotecas cliente en varios lenguajes de programación comunes. Si deseas obtener instrucciones sobre cómo obtener bibliotecas cliente para tu aplicación de servidor, consulta Bibliotecas cliente.
En los ejemplos de Java en esta documentación, se supone que estás familiarizado con gRPC.
Estructuras de datos
La API de Fleet Engine Deliveries usa dos estructuras de datos para modelar el retiro y la entrega de los envíos:
- Indica el vehículo de entrega que se usa para transportar el envío.
- Las tareas de retiro y entrega del envío
También usas tareas para modelar las pausas del conductor y las paradas programadas a lo largo del día.
Vehículos de reparto
Los vehículos de entrega transportan envíos de un depósito a una ubicación de entrega y de un lugar de retiro al depósito. En algunos casos, también pueden transportar un envío directamente desde la ubicación de retiro a la ubicación de entrega.
Usa el SDK del controlador para crear un objeto DeliveryVehicle en Fleet Engine y enviar actualizaciones de ubicación para el envío y el seguimiento de la flota.
Tareas
Para las acciones que realiza un vehículo durante el día, debes asignar tareas según el tipo de acción:
- Para los retiros y las entregas, asigna tareas de envío.
- Para los momentos en que los conductores no están disponibles, como los descansos obligatorios, asigna Tareas de falta de disponibilidad.
- Para las tareas no relacionadas con la conducción en buzones o ubicaciones de 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 los períodos de ETA para cada tarea, usa todas las tareas y el orden en el que están programadas para realizar estimaciones. Para obtener más información sobre los IDs de tareas, consulta Lineamientos sobre 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 e incluye la siguiente información:
- Es la ubicación del retiro o la entrega.
- Un número de seguimiento o ID.
- Un tiempo de permanencia que tiene en cuenta el tiempo adicional para completar la tarea, buscar estacionamiento o caminar hasta la ubicación de transferencia.
- Un ID de tarea único. Consulta los Lineamientos sobre ID de tareas.
Para obtener más información, consulta los siguientes temas:
Android
iOS
Tareas de falta de disponibilidad
Las tareas de no disponibilidad abarcan los períodos en los que un vehículo no está disponible para retirarse o entregarse, como los recesos para cargar combustible o los descansos del conductor.
Crea una tarea de falta de disponibilidad con la siguiente información:
- Es la duración de la pausa.
- La ubicación de la pausa (opcional). No es necesario que proporciones una ubicación específica, pero, si lo haces, obtendrás ventanas de hora de llegada estimadas 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 paradas programadas para modelar las paradas que debe hacer un vehículo de reparto. Por ejemplo, crea una tarea de parada programada para una parada de recolección programada diaria en una ubicación específica, independientemente de otras entregas o retiros en la misma ubicación. También puedes crear tareas de paradas programadas para las recopilaciones desde buzones de entrega o hasta trasbordos o paradas de vehículos alimentadores y alimentadores en centros de servicio y puntos de servicio.
Para obtener más información, consulta los siguientes temas:
Android
iOS
Lineamientos sobre IDs de tareas
Cuando crees IDs de tareas, sigue estos lineamientos de contenido y formato:
- Crea IDs de tarea únicos
- No expongas información de identificación personal (PII) ni datos de texto en blanco.
- Usa cadenas Unicode válidas.
- Usa 64 caracteres como máximo.
- No incluyas ninguno de los siguientes caracteres ASCII: “/”, ":", “\", “?” o “#”.
- Normaliza de acuerdo con el formulario C de normalización de Unicode.
Los siguientes son algunos ejemplos de buenos IDs de tarea:
- 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 la PII y los requisitos de 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 para el tramo inicial o el último tramo.
Se crea un objeto DeliveryVehicle con 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.
- Un ID de vehículo de propiedad del cliente.
Usa IDs de vehículos ú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 actualizaron con UpdateDeliveryVehicle después de siete días. Para ver si un vehículo existe, haz lo siguiente:
- Realiza una llamada a
UpdateDeliveryVehicle. - Si recibes un error NOT_FOUND, llama a
CreateDeliveryVehiclepara volver a crear el vehículo. Si la llamada devuelve un vehículo, aún estará disponible para su actualización.
Tipos de vehículos
La entidad VehicleType contiene un campo opcional de VehicleType, que contiene una enum Category que puedes especificar como AUTO, TWO_WHEELER, BICYCLE o PEDESTRIAN. Si no configuras el campo, el valor predeterminado es AUTO.
En todas las rutas para vehículos, se utiliza el RouteTravelMode correspondiente para el tipo de vehículo.
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 de 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.
Ciclo de una tarea
Puedes crear, actualizar y consultar tareas en Fleet Engine con las interfaces gRPC o REST de la API de Deliveries.
Un objeto Task tiene un campo de estado para hacer un seguimiento de su progreso a lo largo de su ciclo de vida. Los valores se mueven de OPEN a CLOSED. Las tareas nuevas se crean en el estado ABIERTO, lo que indica lo siguiente:
- La tarea aún no se asignó a ningún vehículo de entrega.
- El vehículo de entrega aún no ha pasado la parada vehicular asignada a la tarea.
Lineamientos de las tareas
Solo puedes asignar una tarea a un vehículo cuando está en estado ABIERTO.
Para cancelar una tarea, la quitas de la lista de paradas del vehículo, lo que establece automáticamente el estado de la tarea en CERRADA.
Cuando el vehículo de la tarea complete la detención vehicular de la tarea, ocurrirá lo siguiente:
Actualiza el campo de resultado de la tarea a SUCCEEDED o FAILED.
Especifica la marca de tiempo del evento.
Luego, la biblioteca de JavaScript Shipment Tracking indica el resultado de la tarea, y su estado se establece como CERRADA automáticamente. Para obtener más información, consulta Realiza un seguimiento de tu envío con la biblioteca JavaScript Shipment Tracking.
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 que se borre una tarea de forma explícita. El servicio borra las tareas de forma automática después de siete días sin actualizaciones. Si deseas conservar los datos de las tareas durante más de siete días, debes implementar esa capacidad 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 las tareas no afectan el comportamiento de enrutamiento de Fleet Engine.
No incluyas información de identificación personal (PII) ni otro tipo de información sensible en los atributos, ya que estos 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 Flet Engine Deliveries aumenta en tu nombre.
Para administrar los ciclos de vida de los vehículos y las tareas en tu sistema, usa la API de Fleet Engine Deliveries para crear, actualizar y hacer 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 las rutas. Este modelo permite que Fleet Engine administre la ubicación en tiempo real de forma eficiente. Envía la ubicación directamente a la biblioteca de seguimiento, que luego puedes usar para informar a los consumidores sobre el estado de su pedido.
Por ejemplo, supongamos que se te presenta la siguiente situación:
- Un conductor se acerca a una parada de entrega. La aplicación del controlador envía su ubicación a Flet 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 sobre la proximidad de su paquete.
- Después de que el conductor completa el envío, hace 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.
- Tu sistema confirma la tarea como SUCCEEDED y actualiza Fleet Engine con la API de Deliveries.
En el siguiente diagrama, se ilustran estos procesos a un nivel genérico. También muestra la relación estándar entre tu sistema, el cliente y Fleet Engine.
Administrar 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:
Genera el token con la función de la cuenta de servicio Fleet Engine Delivery Untrusted Driver User.
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
En cambio, si deseas autorizar a las aplicaciones del controlador a realizar actualizaciones directas de Flet Engine más allá de aquellas restringidas a la función de controlador no confiable, como para ciertas actualizaciones de tareas, puedes usar la función de controlador de confianza. Para obtener información sobre un modelo que usa la función de controlador de confianza, consulta 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.
Modelar un día laboral
En la siguiente tabla, se describe cómo podría ser un día laboral para los conductores de primera o última milla en una empresa de entregas y logística. Es posible que haya diferencias en los detalles de la empresa, pero puedes ver cómo podrías elaborar un día de trabajo.
| Tiempo | Actividad | Modelado |
|---|---|---|
| Dentro de las 24 horas del comienzo del día | El despachador asigna envíos a los vehículos o rutas de entrega. | Puedes crear tareas para entregas de envíos, retiros, pausas y
otras tareas en Fleet Engine de forma anticipada. 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 finalices el conjunto de paquetes de entrega y el orden en el que deben entregarse. |
| Inicio del día | El conductor accede a la app de Driver para comenzar el día en el depósito. | 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 los escanea. | Si las tareas de entrega de envíos no se crearon con anticipación, crea tareas de entrega de envío en el momento del análisis. | |
| El conductor confirma el orden de las tareas a realizar. | Si no se crearon con anticipación, crea tareas de retiro de envío, la falta de disponibilidad programada y paradas programadas. | |
| El controlador sale del depósito y se confirma en la siguiente cantidad de tareas que deben completarse. | Asigna todas las tareas o un subconjunto de tareas al vehículo confirmando su orden de finalización. | |
| 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 manera opcional, el estado del envío de la tienda 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 las 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 alimentador para transferir envíos adicionales al vehículo de reparto. | El punto de encuentro de un transbordo entre vehículos de alimentación 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, asigna tareas a un vehículo y actualiza el orden para actualizar el orden de finalización de las tareas. |
|
| El conductor recibe la notificación de una solicitud de recogida. | Después de aceptar la solicitud de retiro, crea una tarea de retiro del envío. Luego, actualiza el orden de ejecución de las tareas a través de la asignación de tareas a un vehículo y la actualización del orden de las tareas. | |
| Mediodía | El conductor se toma el descanso para almorzar. | Si una ubicación está asociada con la tarea de falta de disponibilidad, trátala como a cualquier otra tarea. Realizar acciones relacionadas con un vehículo que llega a una parada, el vehículo finaliza 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. | Este tiene el mismo aspecto que un punto de entrega. Realizar acciones relacionadas con el vehículo que llega a una parada y el cierre de una tarea, y, de manera opcional, almacenar 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. Nota: Para garantizar una facturación correcta, todos los retiros deben tener una tarea de entrega correspondiente. Si el punto de partida se entregará en otra ubicación en 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 lleva el punto de partida al depósito, recomendamos crear una tarea de entrega en el destino del depósito. | |
| El conductor hace una parada programada para recoger los envíos en un buzón. | Este modelo tiene el mismo aspecto que cualquier otra parada de recogida. Realizar acciones relacionadas con un vehículo que llega a una parada y cerrar una tarea. Después de completar todas las tareas en la parada y comenzar a conducir a la siguiente parada, realiza las acciones relacionadas con el vehículo completa una parada y el vehículo se dirige a la siguiente parada. | |
| El conductor recibe la notificación de que un envío se desvía a una ubicación alternativa. | Establece el estado de la tarea de entrega del envío original como COMPLETED y crea una tarea de entrega de envíos original para la nueva ubicación de entrega. Para obtener más información, consulta Redirige un envío. | |
| El conductor intentó entregar un paquete, pero no pudo hacerlo. | Esto se modela de manera similar a una parada de entrega exitosa, lo que marca la tarea de entrega como completada. Realizar acciones relacionadas con el vehículo que llega a una parada. Si no se puede entregar el envío, cierra la tarea y, de manera opcional, el estado del envío de la tienda 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. | |
| Se notificó al conductor que debe 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 debía entregar un determinado envío a continuación y cambiar el orden de entrega comprometido. | Actualiza el orden de las tareas. | |
| El conductor elige entregar un envío desordenado. | Actualiza el orden de las tareas y, luego, continúa como de costumbre. | |
| El conductor entrega múltiples envíos a una sola ubicación. | Esto se modela de manera similar a una sola parada de entrega de envío. Después de llegar a la parada, realiza acciones relacionadas con un vehículo que llega a una parada. Después de entregar cada envío, cierra cada tarea y, de manera opcional, el estado del envío a la tienda 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. | |
| Fin del día | El conductor vuelve al depósito. | Si el conductor vuelve al depósito con los envíos recogidos durante la ruta, también debes crear y cerrar cada paquete como tarea de entrega para garantizar una facturación correcta. Para hacerlo, puedes modelar el depósito como cualquier otra parada de entrega. Aunque el depósito no se use como parada de entrega, tienes la opción de modelarlo como una parada programada. Si modelas la parada, los conductores podrán 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 del vehículo. Usa cualquiera de las siguientes formas para proporcionar estas actualizaciones:
- Usa el SDK de Driver (Android o iOS) es la opción más sencilla.
- Usa un código personalizado, que es útil si las ubicaciones se retransmiten a través de tu backend o si usas dispositivos que no sean Android o iOS.
Sin importar cómo proporciones las actualizaciones de la ubicación del vehículo, tu 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 automáticamente.
Paradas y ubicaciones de entrega de vehículos
La parada de un vehículo es cuando un vehículo de entrega completa una tarea de envío o alguna 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 aquella en la que el envío se entrega o se recoge. Es posible que sea necesario caminar un poco desde la parada del vehículo para ir y volver del lugar 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 donde se encuentra la tienda. Esta es la ubicación de entrega.
Para obtener la mejor experiencia de seguimiento de envíos para tus usuarios, considera cómo se asignan las tareas de envío a las paradas de vehículos y ten en cuenta que la cantidad de paradas restantes del vehículo para las tareas de envío se informa al usuario para ayudarlo a ver el progreso de su envío.
Por ejemplo, si un conductor realiza muchas entregas a un solo edificio de oficinas, considera asignar todas las tareas de entrega a una sola parada del vehículo. Si cada tarea de entrega se asigna a su propia parada del vehículo, la experiencia de seguimiento de envíos sería menos útil para los usuarios, ya que el seguimiento solo está disponible una vez que el vehículo se encuentra en una cantidad limitada de paradas antes de su destino. El hecho de que el vehículo se detenga en poco tiempo no le brinda mucho tiempo al usuario para hacer un seguimiento del progreso de la entrega.
Cómo usar los SDK para dispositivos móviles
Antes de realizar llamadas al SDK del controlador, asegúrate de inicializarlo.
Cómo inicializar la API de Delivery Driver
Antes de inicializar la API de Delivery Driver en el SDK de Driver, asegúrate de inicializar el SDK de Navigation. Luego, inicializa la API de Delivery Driver como se muestra en el siguiente ejemplo:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
Casos de uso
En esta sección, se describe cómo usar la API de Deliveries para modelar casos de uso comunes.
Identificadores de entidad única
El formato y el valor de los identificadores de entidades únicos que se usan en las llamadas a REST son opacos para Fleet Engine. Evita usar ID 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 que se especifique en el campo Name se ignorará según los lineamientos de la API para los IDs especificados por el usuario.
Debes usar el campo DeliveryVehicleId para configurar el ID del vehículo.
Cuando creas un DeliveryVehicle, tienes la opción de especificar estos campos:
- Atributos
- LastLocation
- Tipo
No establezcas 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 a partir de un entorno de servidor, realiza una llamada REST HTTP a CreateDeliveryVehicle:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> es un identificador único para un vehículo de entrega de tu flota.
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 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 la orientación de la API para los IDs especificados por el usuario.
No establezcas 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 vacío el cuerpo de la solicitud POST. 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}"
Crear una tarea de retiro de envío
Puedes crear una tarea de retiro 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 retiro de envío:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para crear una tarea de retiro de envíos desde un entorno de servidor, realiza una llamada de 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 tareas en tu sistema, puedes generar un identificador único universal (UUID).
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
El cuerpo de la solicitud debe contener una entidad Task:
Campos obligatorios:
Campo Valor Tipo Type.PICKUP state State.OPEN trackingId Es el número o identificador que utiliza para realizar el seguimiento de un envío. plannedLocation La ubicación en la que se debe completar la tarea, en este caso, la ubicación de retiro del envío. taskDuration Es el tiempo esperado, en segundos, que tarda el retiro del envío en la ubicación de retiro. Campos opcionales:
Campo Valor targetTimeWindow El período durante el cual se debe completar la tarea. Esto no afecta el comportamiento del enrutamiento. attributes Una lista de atributos de tareas personalizadas. Cada atributo debe tener una clave única.
Todos los demás campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Las tareas se asignan mediante UpdateDeliveryVehicleRequest. Para obtener más información, consulta Asigna 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
Crear una tarea de entrega de envíos
Crea una tarea de entrega de envíos desde el SDK del controlador 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 de 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 tareas en tu sistema, puedes generar un identificador único universal (UUID).
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
El cuerpo de la solicitud debe contener una entidad Task:
Campos obligatorios:
Campo Valor Tipo Type.DELIVERY state State.OPEN trackingId Es el número o identificador que utiliza para realizar el seguimiento de un envío. plannedLocation La ubicación en la que se debe completar la tarea, en este caso, la ubicación de entrega del envío. taskDuration Es el tiempo esperado, en segundos, que tomará dejar el envío en la ubicación de entrega. Campos opcionales:
Campo Valor targetTimeWindow El período durante el cual se debe completar la tarea. Esto no afecta el comportamiento del enrutamiento. attributes Una lista de atributos de tareas personalizadas. Cada atributo debe tener una clave única.
Todos los demás campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Las tareas se asignan mediante UpdateDeliveryVehicleRequest. Para obtener más información, consulta Asigna 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 con el fin de 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:
Campo Valor solicitudes Arreglo< CreateTasksRequest>Campos opcionales:
Campo Valor encabezado "DeliveryRequestHeader"
Cada elemento CreateTasksRequest en requests debe pasar las mismas reglas de validación que una solicitud CreateTask, con la excepción de que los campos parent y header son opcionales. Si se configuran, deben ser idénticos a sus respectivos campos en el BatchCreateTasksRequest de nivel superior. Consulta
cómo crear una tarea de retiro del envío y
cómo crear una tarea de entrega de envío
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 falta de disponibilidad (por ejemplo, para descansos del conductor o recarga de combustible del vehículo) desde el SDK del controlador o desde un entorno de servidor con gRPC o REST. Una tarea de falta de disponibilidad programada no debe incluir un ID de seguimiento. De manera opcional, puedes proporcionar una ubicación.
gRPC
En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para crear una tarea de falta de disponibilidad:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para crear una tarea de falta de disponibilidad desde un entorno de servidor, realiza una llamada de 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 tareas en tu sistema, puedes generar un identificador único universal (UUID).
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
El cuerpo de la solicitud debe contener una entidad Task:
Campos obligatorios:
Campo Valor Tipo Type.UNAVAILABLE state State.OPEN taskDuration Es la duración de la pausa en segundos. Campos opcionales:
Campo Valor plannedLocation La ubicación de la pausa si debe tomarse en una ubicación específica.
Todos los demás campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Las tareas se asignan mediante UpdateDeliveryVehicleRequest. Para obtener más información, consulta Asigna 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 del controlador 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 de 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 tareas en tu sistema, puedes generar un identificador único universal (UUID).
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
El cuerpo de la solicitud debe contener una entidad Task:
Campos obligatorios:
Campo Valor Tipo Type.SCHEDULED_STOP state State.OPEN plannedLocation Es la ubicación de la parada. taskDuration Es la duración prevista de la parada en segundos. Campos opcionales:
- Ninguno
Todos los demás campos de la entidad se ignoran para la creación. Fleet Engine arroja una excepción si la solicitud incluye un deliveryVehicleId asignado. Las tareas se asignan mediante UpdateDeliveryVehicleRequest. Para obtener más información, consulta Asigna 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 objetivo
El período 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 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 objetivo consta de una hora de inicio y una de finalización, y se puede configurar en cualquier tipo de tarea. El período 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 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)
.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 establecer un período de tarea con HTTP, llama a UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<id> es un identificador único de la tarea.
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
El cuerpo de la solicitud debe contener una entidad Task:
Campos obligatorios:
Campo Valor targetTimeWindow El período durante el cual se debe completar la tarea. Este parámetro de configuración no afecta el comportamiento de 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 Shipment Tracking y los datos que se muestran de una llamada a GetTaskTrackingInfo se puede controlar por tarea si se configura un TaskTrackingViewConfig en la tarea. Consulta Tareas de vehículos activos para obtener más información. Esto se puede hacer cuando se crea o
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 del 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 de seguimiento de tareas con HTTP, llama a UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<id> es un identificador único de la tarea.
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
El cuerpo de la solicitud debe contener una entidad Task:
Campos obligatorios:
Campo Valor taskTrackingViewConfig Es la configuración del seguimiento de tareas que especifica qué elementos de datos son visibles para los usuarios finales 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
Asigna tareas a un vehículo
Para asignar tareas a un vehículo de entrega, actualiza el pedido de tareas del vehículo. El orden de las tareas de un vehículo se determina mediante la lista de paradas vehiculares del vehículo de reparto, y puedes asignar una o más tareas a cada parada del vehículo. Para obtener más detalles, 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 vuelve a crearla antes de asignarle el vehículo nuevo. Si actualizas el orden de tareas para una tarea que ya está asignada a otro vehículo, se mostrará un error.
Actualizar el orden de las tareas
Puedes actualizar el orden en que se realizan las tareas asignadas a un vehículo desde el SDK de Driver o el entorno del servidor. No uses ambos métodos para evitar las condiciones de carrera y mantener una única fuente de información.
Cuando actualizas el pedido de tareas de un vehículo, también se hace lo siguiente:
- Asigna tareas que son nuevas en el vehículo.
- Cierra cualquier tarea que se haya asignado previamente al vehículo, pero que no tiene el orden actualizado.
Para cambiar un envío de un vehículo a otro, cierra la tarea original y vuelve a crearla antes de asignarle el vehículo nuevo. Si actualizas el orden de tareas para 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 pedido de tareas para un vehículo desde un entorno de servidor, realiza una llamada REST de 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>, 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 DeliveryVehicle:
Campos obligatorios:
Campo Valor 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].stop La parada de la tarea i en la lista. restantesVehicleJourneySegments[i].stop.scheduledLocation Es la ubicación planificada para la parada. restantesVehicleJourneySegments[i].stop.tasks 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
Fleet Engine debe recibir una notificación 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 métodos para evitar condiciones de carrera y mantener una única fuente de verdad.
gRPC
En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para notificar a Fleet Engine que un vehículo está en camino a su próxima 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 próxima parada desde un entorno de servidor, realiza una llamada REST de 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>, 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 DeliveryVehicle:
Campo obligatorio:
Campo Valor remainingVehicleJourneySegments Lista de paradas vehiculares restantes con sus estados marcados como State.NEW. La primera parada de la lista debe tener su estado marcado como State.ENROUTE. Campos opcionales:
- Ninguno
Todos los demás campos de la entidad se ignoran en 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 del conductor para actualizar la ubicación del vehículo, puedes realizar una llamada directa a Fleet Engine con la ubicación del vehículo. Para cualquier vehículo activo, Flet Engine espera una actualización de la 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 con 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 en tu flota o cuya ubicación deseas actualizar. Es el identificador que especificaste cuando creaste el vehículo.
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:
Campo obligatorio:
Campo Valor lastLocation.supplementalLocation 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 Se debe completar con CUSTOMER_SUPPLIED_LOCATION. Campos opcionales:
Campo Valor 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
Fleet Engine debe recibir una notificación cuando un vehículo llega a una parada. Puedes notificar a Flet 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 verdad.
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 a una parada desde un entorno de servidor, realiza una llamada REST de 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>, 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 DeliveryVehicle:
Campos obligatorios:
Campo Valor remainingVehicleJourneySegments La parada a la que llegaste, con su estado configurado como State.ARRIVED, seguida de una lista de las paradas de vehículos restantes con sus estados marcados 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
Fleet Engine debe recibir una notificación cuando un vehículo finaliza una parada. Esto hace que todas las tareas asociadas con la parada se establezcan en el estado CERRADA. 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 verdad.
gRPC
En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para notificar a Fleet Engine que se detuvo 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 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 detención desde un entorno de servidor, realiza una llamada REST de 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>, 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 DeliveryVehicle:
Campos obligatorios:
Campo Valor remaining_vehicle_journey_segments La parada que completaste ya no debería estar en la lista de paradas del vehículo restantes. 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
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 de resultado de la tarea, la ubicación del resultado de la tarea y los atributos si actualizas directamente la entidad de la tarea. Por ejemplo, en los casos en los que una tarea no se asignó a un vehículo, puedes cerrarla actualizando el estado directamente.
gRPC
Este es un ejemplo de cómo actualizar una tarea con gRPC.
REST
Este es un ejemplo de cómo actualizar una tarea con REST.
Cómo cerrar una tarea
Para cerrar una tarea que se asignó 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 para vehículos. Para ello, puedes configurar la lista de las paradas restantes del vehículo como cuando actualizas el orden de tareas de un vehículo.
Si a una tarea aún no se le asignó un vehículo y se debe cerrar, actualiza la tarea al estado CERRADA. Sin embargo, no puedes volver a abrir una tarea CERRADA.
El cierre de una tarea no indica el éxito o el fracaso de la tarea. Indica que la tarea ya no se considera en curso. Para el seguimiento de envíos, es importante indicar el resultado real de una tarea para que se pueda mostrar un resultado de 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 de 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>, en el que <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:
Campo Valor state State.CLOSED Campos opcionales:
Campo Valor taskOutcome Resultado.SUCCEEDED o resultado.FAILED taskOutcomeTime La hora en la que se completó la tarea. taskOutcomeLocation La ubicación donde se completó la tarea. De forma predeterminada, Fleet Engine usa la ubicación más reciente 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 su ubicación
El cierre de una tarea no indica éxito o fracaso, indica que la tarea ya no se considera en progreso. Para el seguimiento de envíos, es importante indicar el resultado real de una tarea para que se pueda mostrar un resultado de entrega y la facturación de los servicios sea adecuada. Una vez que se establece, no puedes cambiar el resultado de la tarea. Sin embargo, puedes modificar la hora y la ubicación del resultado de la tarea después de que se hayan establecido.
Las tareas que se encuentran en estado CERRADO pueden tener su resultado configurado como COMPLETA o CON ERRORES. 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 última ubicación conocida del vehículo. Puedes anular este comportamiento.
gRPC
Tienes la opción de establecer la ubicación del resultado de la tarea cuando estableces el resultado. Configurar la ubicación evita que Fleet Engine establezca la ubicación predeterminada de la última ubicación del vehículo. También puedes reemplazar la ubicación de resultados de la tarea establecida en Fleet Engine más adelante. Fleet Engine nunca reemplaza una ubicación de resultados de tareas que proporciones. No puedes establecer la ubicación del resultado de una tarea que no tiene un conjunto de resultados de tareas. Puedes establecer tanto el resultado de la tarea como 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 SUCCEEDED y 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>, 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 Task:
Campos obligatorios:
Campo Valor taskOutcome Resultado.SUCCEEDED o resultado.FAILED Campos opcionales:
Campo Valor taskOutcomeLocation La ubicación donde se completó la tarea. Si no la estableces, Fleet Engine establece de forma predeterminada la ubicación del último vehículo. taskOutcomeTime La marca de tiempo de cuando se completó la tarea.
Todos los demás campos de la entidad se ignoran para la actualización.
Comando curl de ejemplo
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
Redirigir un envío
Una vez que se crea una tarea de envío, no se puede cambiar su ubicación planificada. Para volver a enrutar 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 asignar la tarea.
Usar alimentadores y vehículos de reparto
Si usas vehículos de alimentación para transportar envíos a vehículos de entrega a lo largo del día, modela la transferencia de envíos como una tarea de parada programada para el vehículo de entrega. Para garantizar un seguimiento de la ubicación exacto, asigna solo una tarea de entrega para un envío transferido después de que se cargue en el vehículo de entrega. Para obtener más información, consulta Parada programada.
Estado del envío de la tienda 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 actualizar otra metainformación específica del envío. Para almacenar otra metainformación a la que puedas hacer referencia fuera del servicio de Fleet Engine, usa el tracking_id asociado con la tarea como una 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 debe buscar.
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 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 el entorno de un servidor con gRPC o REST. El SDK de Driver no admite la búsqueda de tareas.
gRPC
En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para buscar una tarea:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder() // No need for the header
.setName(taskName)
.build();
try {
Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para buscar una tarea desde un entorno de servidor, realiza una llamada REST HTTP 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>, en el que <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 las tareas de envío por su ID de seguimiento
Puedes buscar información de las tareas de envío de las siguientes maneras, cada una de las cuales tiene un propósito diferente:
- Por un ID de tarea: Lo usan usuarios, como operadores de flota, que tienen acceso a la vista completa de los datos de la tarea.
- Por un ID de seguimiento: El software 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 analiza la búsqueda de información de tareas mediante un ID de seguimiento. Si quieres buscar una tarea por su ID, ve a Cómo buscar una tarea.
Para buscar información con un ID de seguimiento, puedes utilizar cualquiera de las siguientes opciones:
Requisitos de búsqueda
La información de envío que proporciona un ID de seguimiento cumple con las reglas de visibilidad establecidas en Controlar la visibilidad de las ubicaciones a las que se les realiza seguimiento.
Usa Fleet Engine para buscar información de envío por ID de seguimiento. El SDK del controlador no admite búsquedas de información por ID de seguimiento. Para hacer esto con Fleet Engine, usas un entorno de servidor o de navegador.
Usar 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 mostrará 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. Si quieres obtener más información sobre los tokens, consulta Cómo crear un token web JSON (JWT) para autorización.
Búsquedas con Java mediante gRPC
En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para buscar información sobre una tarea de envío 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 a través de HTTP
Para buscar una tarea de envío desde un navegador, realiza una llamada REST de HTTP a GetTaskTrackingInfo:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`
<tracking_id> es el ID de seguimiento asociado con la tarea.
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
Si la búsqueda se realiza correctamente, el cuerpo de la respuesta contendrá una entidad taskTrackingInfo.
Comando curl de ejemplo
# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"
Enumerar tareas
Puedes enumerar tareas 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 las tareas. La enumeración de tareas está destinada solo a los usuarios de confianza. Usa el lector de flotas de entrega o los tokens de autenticación de superusuario de entrega cuando realices solicitudes de listas de tareas.
Las tareas enumeradas tienen los siguientes campos ocultos:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
Las tareas enumeradas se pueden filtrar por la mayoría de las propiedades de las tareas. Para conocer la sintaxis de consulta de filtro, consulta AIP-160. En la siguiente lista, se muestran las propiedades de tareas 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 según las propuestas de mejora de la API 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 |
| Ubicación | 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 un tamaño de página en las solicitudes de lista de tareas. Si se especifica un tamaño de página, la cantidad de tareas que se muestran no es mayor que el tamaño de página especificado. Si no hay un tamaño de página, se usa un valor predeterminado razonable. Si el tamaño de página solicitado supera un valor máximo interno, se usa ese máximo.
Una lista de tareas puede incluir un token para leer la página siguiente de resultados. Utiliza el token de la página con una solicitud que sea idéntica a la solicitud anterior para recuperar la página siguiente de tareas. Cuando el token de la página que se muestra está vacío, no hay más tareas disponibles para recuperarse.
gRPC
En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para enumerar tareas para un deliveryVehicleId y un atributo de tarea. Una respuesta correcta 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 tareas de 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 como valor un parámetro de URL "filter" con una consulta de filtro con escape de URL.
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token emitido por una fábrica de tokens de Fleet Engine.
Si la búsqueda se realiza correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
Una respuesta correcta aún puede estar vacía. Una respuesta vacía indica que no se encontraron tareas que cumplieran 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}"
Mostrar vehículos de entrega
Puedes enumerar vehículos de entrega desde un entorno de servidor o navegador. El SDK del controlador no admite mostrar fichas de vehículos de entrega.
Enumerar los vehículos de entrega solicita un acceso amplio a los vehículos de entrega y 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 listas de vehículos de entrega.
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 de attributes. Por ejemplo, para consultar un atributo con la clave my_key y el valor my_value, usa attributes.my_key = my_value. Para consultar varios atributos, une las consultas mediante los operadores lógicos AND y OR, como en attributes.key1 = value1 AND
attributes.key2 = value2. Consulta AIP-160 para obtener una descripción completa de la sintaxis de consulta de filtros.
Puedes filtrar los vehículos de entrega de la lista según la ubicación mediante 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 (suroeste). Las solicitudes se rechazan si contienen una latitud alta que es 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 muestra la cantidad de vehículos especificada en el límite, o menos. Si el tamaño de página solicitado supera un valor máximo interno, se usa ese máximo. 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 recuperar. Para recuperar la página siguiente de tareas, usa el token de la página con una solicitud que sea idéntica a la solicitud anterior.
gRPC
En el siguiente ejemplo, se muestra cómo usar la biblioteca gRPC de Java para enumerar vehículos de entrega en una región particular con un atributo determinado. Una respuesta correcta puede estar vacía. Cuando eso sucede, significa que ya no hay vehículos con el atributo especificado 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 tareas de 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 "filtro" con una consulta de filtro con escape de URL como su valor.
El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> es un token 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 aún puede estar vacía. Cuando eso sucede, significa que no se encontraron vehículos de entrega que cumplieran 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 envíos
Tienes dos opciones para usar la API de Fleet Engine Deliveries a fin de habilitar el seguimiento de envíos:
Preferido: Usa la biblioteca de seguimiento de envíos 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 y componentes de datos para conectarse con Fleet Engine. Este componente te permite proporcionar una experiencia de seguimiento de envíos animada y personalizable desde tu aplicación web o para dispositivos móviles.
Implementa tu propio seguimiento de envíos sobre la API de Fleet Engine Deliveries.
La clave es buscar las tareas de envío por ID de seguimiento.
Si usas un rol de consumidor de entrega, cualquier llamada a la API de Fleet Engine Deliveries solo mostrará información relevante para un transportista o receptor. Se oculta el resto de la información de las respuestas. Eres responsable de autenticar a los usuarios finales. Además, la información de ubicación se filtra en función de la tarea que ya se realizó. Durante una tarea de falta de disponibilidad, no se comparte información de ubicación con un usuario final.
Logging
Puedes configurar Fleet Engine para enviar registros de RPC a Cloud Logging. Para obtener más información, consulta Registro.
Roles y tokens de autorización
Como se describe en Administra el ciclo de vida de un vehículo y una tarea y las notas de autorización para casos de uso individuales, las llamadas a Fleet Engine requieren autenticación con tokens web JSON que se hayan firmado con las credenciales de la cuenta 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 Flet Engine.
Estado perdido en Fleet Engine
Cuando trabajes con Fleet Engine, implementa clientes para que el sistema se recupere por sí mismo si hay una falla. Por ejemplo, cuando Fleet Engine intenta actualizar un vehículo, puede mostrar un error que indica que el vehículo no existe. Luego, el cliente debe recrear el vehículo en el estado nuevo. Si bien este problema rara vez ocurre, asegúrate de que tu sistema sea lo suficientemente resiliente para controlarlo.
En la situación extremadamente improbable de una falla catastrófica de Fleet Engine, es posible que debas recrear la mayoría de los vehículos y las tareas, o todos ellos. Si la tasa de creación aumenta demasiado, es posible que algunas solicitudes vuelvan a fallar debido a problemas de cuota, ya que se realizaron verificaciones de cuota para evitar ataques de denegación del servicio (DoS). En este caso, reduce la velocidad de recreación con una estrategia de retirada para los reintentos.
Estado perdido en la app del conductor
Si falla la app del controlador, esta debe volver a crear el estado actual en el SDK del controlador. La app debe intentar volver a crear las tareas para garantizar 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 del controlador.
Preguntas frecuentes
¿Qué sucede si un conductor se detiene a realizar una tarea desordenada?
En este caso, primero actualiza el orden de las tareas y, luego, procede con normalidad y marca la llegada a la parada, la finalización de la tarea y otros detalles. De lo contrario, es posible que el sistema se vuelva incoherente, que los ETA sean incorrectos y que se informen errores inesperados.