Questo documento presuppone che tu abbia letto la guida introduttiva alle attività pianificate nella sezione Introduzione a Fleet Engine, nonché la sezione Che cos'è un'attività pianificata? in questa sezione.
Fleet Engine per le attività pianificate fornisce diverse categorie generali di attività:
- Attività di spedizione: da utilizzare per le attività di guida, tra cui il ritiro e la consegna delle spedizioni.
- Attività di non disponibilità: da utilizzare per i periodi in cui i conducenti non sono disponibili, ad esempio per le pause obbligatorie.
- Attività di fermata pianificata: da utilizzare per attività non di guida presso casse di consegna o sedi dei clienti, ad esempio il tempo necessario per entrare in un edificio o individuare un punto di consegna.
Questo documento illustra come creare attività di caricamento sul server. Per altri tipi di attività, consulta Creare altri tipi di attività.
Campi delle attività di spedizione
Questa sezione descrive i campi delle attività necessari sia per le attività di ritiro sia per quelle di consegna.
Campi obbligatori delle 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 della task fornisce un deliveryVehicleId assegnato. Per assegnare attività a un veicolo,
utilizza UpdateDeliveryVehicleRequest. Per ulteriori informazioni, consulta la sezione Aggiornare le attività.
| Campo | Valore |
|---|---|
type |
Imposta il tipo che corrisponde al tipo di attività, che può essere uno dei seguenti:
|
state |
State.OPEN |
task_id |
ID attività univoco. Non deve essere il numero di riferimento della spedizione. Se non hai ID attività nel tuo sistema, puoi generare un identificatore univoco universale (UUID). Per informazioni specifiche, consulta ID attività. |
tracking_id |
Solo attività PICKUP o DELIVERY:
Il numero o l'identificatore che utilizzi per monitorare una spedizione. Non indicare questo campo per le attività diverse dalla spedizione. |
plannedLocation |
Solo attività PICKUP, DELIVERY o
SCHEDULED_STOP: la
posizione in cui deve essere completata l'attività. Non obbligatorio per le attività UNAVAILABLE. |
taskDuration |
Il tempo stimato per completare l'attività. Ad esempio, per cercare un parcheggio o raggiungere a piedi il luogo di consegna. |
Campi facoltativi delle attività di spedizione
| Campo | Valore |
|---|---|
targetTimeWindow |
La finestra temporale durante la quale l'attività deve essere completata. Questo campo non influisce sul comportamento di instradamento. |
task_tracking_view_config |
Solo attività PICKUP o DELIVERY:
la configurazione per il monitoraggio 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. |
Creare un'attività di ritiro della spedizione
Per utilizzare Fleet Engine per monitorare 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 il ritiro di una spedizione dal centro commerciale Grand Indonesia East.
Gli esempi riportati di seguito mostrano come creare un'attività di ritiro della spedizione utilizzando la libreria gRPC Java o come effettuare una richiesta HTTP REST a CreateTask.
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> è emesso dal server in base alle linee guida descritte in Ruoli dell'account di servizio e Token web JSON.
Il corpo della richiesta deve contenere un'entità Task con i campi appropriati
descritti in Campi delle attività di spedizione.
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
Creare un'attività di consegna della spedizione
Per utilizzare Fleet Engine per monitorare l'attività di un conducente che consegna una spedizione,
crea un'attività di consegna della spedizione. Ciò comporta l'impostazione dell'attributo tipo attività su DELIVERY. L'esempio seguente illustra la consegna di una spedizione al Grand
Indonesia East Mall.
Gli esempi riportati di seguito mostrano come creare un'attività di ritiro della spedizione utilizzando la libreria gRPC Java o come effettuare una richiesta HTTP REST a CreateTask.
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> è emesso dal server in base alle linee guida descritte in Ruoli dell'account di servizio e Token web JSON.
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
```