Creare attività di spedizione

Questo documento presuppone che tu abbia letto la guida introduttiva alle [Attività pianificate][1] nella sezione Introduzione a Fleet Engine e [Che cos'è un'attività pianificata?][2] in questa sezione.

Fleet Engine per le attività pianificate offre diverse categorie generali di attività:

  • Attività di spedizione: utilizza questa opzione per le attività di guida, tra cui il ritiro e la consegna delle spedizioni.
  • Attività di non disponibilità: utilizzale per i periodi in cui i conducenti non sono disponibili, ad esempio per le pause obbligatorie.
  • Attività di sosta pianificata: utilizza questa opzione per le attività non di guida presso le cassette per la posta o le sedi dei clienti, ad esempio il tempo necessario per entrare in un edificio o individuare un punto di consegna.

Questo documento spiega come creare attività di spedizione sul tuo server. Per altri tipi di attività, consulta Crea altri tipi di attività.

Campi delle attività di spedizione

Questa sezione documenta i campi delle attività necessari per le attività di ritiro e consegna.

Campi obbligatori per le attività

Per ogni attività creata in Fleet Engine, devi fornire i campi obbligatori e puoi anche fornire uno qualsiasi dei campi facoltativi. Fleet Engine ignora tutti gli altri campi e genera un'eccezione se una richiesta di creazione di un'attività fornisce un deliveryVehicleId assegnato. Per assegnare attività a un veicolo, utilizza UpdateDeliveryVehicleRequest. Per ulteriori informazioni, consulta Aggiorna le attività.

CampoValore
type

Impostalo sul tipo corrispondente al tipo di attività, ovvero uno dei seguenti:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id ID attività univoco. Non deve essere il numero di tracciamento della spedizione. Se non disponi di ID attività nel tuo sistema, puoi generare un identificatore univoco universale (UUID). Per maggiori dettagli, consulta ID attività.
tracking_id Solo attività PICKUP o DELIVERY: il numero o l'identificatore che utilizzi per monitorare una spedizione. Non fornire questo campo per le attività non di spedizione.
planned_location Solo attività PICKUP, DELIVERY o SCHEDULED_STOP: la località in cui deve essere completata l'attività. Non richiesto per le attività UNAVAILABLE.
task_duration Il tempo previsto da aggiungere per completare l'attività. Ad esempio, per cercare un parcheggio o raggiungere a piedi il luogo di consegna.

Campi facoltativi delle attività di spedizione

CampoValore
target_time_window La finestra temporale durante la quale l'attività deve essere completata. Questo campo non influisce sul comportamento di routing.
task_tracking_view_config Solo attività PICKUP o DELIVERY: la configurazione per il monitoraggio dei tracker delle attività che specifica quali elementi di dati sono visibili agli utenti finali e in quali circostanze.
attributes Un elenco di attributi delle attività personalizzate. Ogni attributo deve avere una chiave univoca.

Crea un'attività di ritiro della spedizione

Per utilizzare Fleet Engine per seguire l'attività di un conducente che ritira una spedizione, crea un'attività di ritiro della spedizione. Ciò comporta l'impostazione dell'attributo del tipo di attività su PICKUP. L'esempio seguente illustra un ritiro della spedizione presso il Grand Indonesia East Mall.

Gli esempi seguenti mostrano come creare un'attività di ritiro della spedizione utilizzando la [libreria gRPC Java][4] o come effettuare una richiesta 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

Per creare un'attività di ritiro della spedizione da un ambiente server, effettua una chiamata HTTP REST a CreateTask:

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

<id> è un identificatore univoco dell'attività.

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> viene emesso dal tuo server in base alle linee guida descritte in [Ruoli dei service account][6] e [Token web JSON][7].

Il corpo della richiesta deve contenere un'entità Task con i campi appropriati descritti in [Campi delle attività di spedizione][8].

Comando curl di esempio:

 # 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

Crea un'attività di consegna della spedizione

Per utilizzare Fleet Engine per seguire l'attività di un conducente che consegna una spedizione, crea un'attività di consegna della spedizione. Ciò comporta l'impostazione dell'attributo del tipo di attività su DELIVERY. L'esempio seguente illustra una consegna al Grand Indonesia East Mall.

Gli esempi seguenti mostrano come creare un'attività di ritiro della spedizione utilizzando la [libreria gRPC Java][4] o come effettuare una richiesta 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

Per creare un'attività di ritiro della spedizione da un ambiente server, effettua una chiamata HTTP REST a CreateTask:

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

<id> è un identificatore univoco dell'attività.

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> viene emesso dal tuo server in base alle linee guida descritte in [Ruoli dei service account][6] e [Token web JSON][7].

Il corpo della richiesta deve contenere un'entità Task:

Comando curl di esempio:

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

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

Passaggi successivi

  • [Crea altri tipi di attività][13]
  • [Aggiorna le attività][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