Crear tareas de envío

En este documento, se supone que leíste la guía introductoria sobre las [tareas programadas][1] en la sección Introducción a Fleet Engine, así como [¿Qué es una tarea programada?][2] en esta sección.

Fleet Engine para tareas programadas proporciona diferentes categorías generales de tareas:

• Tareas de envío: Se usan para las tareas de conducción, incluida la recogida y la entrega de envíos.
• Tareas de falta de disponibilidad: Se usan para los momentos en que los conductores no están disponibles, como en los descansos obligatorios.
• Tareas de detención programadas: Se usan para tareas que no implican conducir en buzones o ubicaciones de clientes, como el tiempo para ingresar a un edificio o ubicar un punto de entrega.

En este documento, se explica cómo crear tareas de envío en tu servidor. Para conocer otros tipos de tareas, consulta Crea otros tipos de tareas.

Campos de la tarea de envío

En esta sección, se documentan los campos de tarea necesarios para las tareas de retiro y entrega.

Campos de tareas obligatorios

Para cada tarea que crees en Fleet Engine, debes proporcionar los campos obligatorios y, además, puedes proporcionar cualquiera de los campos opcionales. Fleet Engine ignora todos los demás campos y arroja una excepción si una solicitud de creación de tarea proporciona un deliveryVehicleId asignado. Para asignar tareas a un vehículo, usa UpdateDeliveryVehicleRequest. Para obtener más información, consulta Actualiza tareas.

Campo	Valor
type	Establece el tipo que coincida con el tipo de tarea, que es uno de los siguientes: PICKUP DELIVERY SCHEDULED_STOP UNAVAILABLE
state	State.OPEN
task_id	Es el ID ú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). Para obtener más información, consulta IDs de tareas.
tracking_id	Solo tareas de PICKUP o DELIVERY: Es el número o identificador que usas para hacer un seguimiento de un envío. No proporciones este campo para las tareas que no sean de envío.
planned_location	Solo para tareas PICKUP, DELIVERY o SCHEDULED_STOP: Es la ubicación en la que se debe completar la tarea. No es necesario para las tareas de UNAVAILABLE.
task_duration	Es el tiempo esperado que se agregará para completar la tarea. Por ejemplo, para buscar estacionamiento o caminar hasta la ubicación de entrega.

Campos opcionales de la tarea de envío

Campo	Valor
target_time_window	Es el período durante el cual se debe completar la tarea. Este campo no afecta el comportamiento del enrutamiento.
task_tracking_view_config	Solo tareas de PICKUP o DELIVERY: Es la configuración para el seguimiento de tareas que especifica qué elementos de datos son visibles para los usuarios finales en qué circunstancias.
attributes	Es una lista de atributos de tareas personalizados. Cada atributo debe tener una clave única.

Crea una tarea de retiro de envío

Para usar Fleet Engine y seguir la actividad de un conductor que recoge un envío, crea una tarea de retiro de envío. Esto implica establecer el atributo de tipo de tarea en PICKUP. En el siguiente ejemplo, se ilustra la recogida de un envío en el centro comercial Grand Indonesia East Mall.

En los siguientes ejemplos, se muestra cómo crear una tarea de retiro de envío con la [biblioteca de gRPC para Java][4] o cómo realizar una solicitud HTTP REST a [CreateTask][5].

gRPC

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

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

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

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que tu servidor emite <token> según los lineamientos descritos en [Roles de la cuenta de servicio][6] y [Tokens web JSON][7].

El cuerpo de la solicitud debe contener una entidad Task con los campos adecuados descritos en [Campos de la tarea de envío][8].

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

Experimental: Como función experimental, el campo LocationInfo (gRPC o REST) ahora admite el uso de place (gRPC o REST), ya sea junto con LatLng o en su lugar.

Crea una tarea de entrega de envío

Para usar Fleet Engine y seguir la actividad de un conductor que entrega un envío, crea una tarea de entrega de envío. Esto implica configurar el atributo de tipo de tarea como DELIVERY. En el siguiente ejemplo, se ilustra la entrega de un envío al centro comercial Grand Indonesia East Mall.

En los siguientes ejemplos, se muestra cómo crear una tarea de retiro de envío con la [biblioteca de gRPC para Java][4] o cómo realizar una solicitud HTTP REST a [CreateTask][5].

gRPC

  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 retiro de envío desde un entorno de servidor, realiza una llamada HTTP REST a CreateTask:

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

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

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que tu servidor emite <token> según los lineamientos descritos en [Roles de la cuenta de servicio][6] y [Tokens web JSON][7].

El cuerpo de la solicitud debe contener una entidad Task:

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
 ```

Experimental: Como función experimental, el campo LocationInfo (gRPC o REST) ahora admite el uso de place (gRPC o REST), ya sea junto con LatLng o en su lugar.

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

¿Qué sigue?

• [Crea otros tipos de tareas][13]
• [Actualiza tareas][3]

[1]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [2]: /maps/documentation/mobility/fleet-engine/journeys/tasks [3]: update-tasks [4]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks#java [5]: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/create [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts [7]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt [8]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks#shipment_task_fields [13]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-other-tasks