Trovare le attività

Questo documento descrive i modi in cui puoi trovare le informazioni sulle attività da un server o da un browser. Fleet Engine supporta due modi per trovare le attività:

  • Cerca attività: puoi cercare le attività in base ai seguenti ID:

    • ID attività: utilizzato da utenti come gli operatori del parco risorse che hanno accesso alla visualizzazione completa dei dati dell'attività.
    • ID monitoraggio: utilizzato dal software client per fornire informazioni limitate a un utente finale, ad esempio quando è prevista la consegna di un pacco a casa sua.

    Assicurati di comprendere la differenza tra l'ID attività e l'ID monitoraggio dell'attività. Non sono la stessa cosa. Consulta la sezione Campi delle attività di base nella guida alle attività pianificate.

  • Elenca attività: un accesso ampio alle attività, destinato solo agli utenti attendibili.

Cerca attività

Questa sezione descrive come cercare le attività in base all'ID attività o all'ID monitoraggio. I requisiti sono i seguenti:

  • Le ricerche per ID monitoraggio devono rispettare le regole di visibilità indicate in Regole di visibilità per gli oggetti monitorati.

  • Utilizza il token più specifico possibile per limitare i rischi per la sicurezza. Ad esempio, se utilizzi un token consumer di consegna, tutte le chiamate restituiscono solo informazioni pertinenti per l'utente finale, come il mittente o il destinatario di una spedizione. Fleet Engine oscura tutte le altre informazioni nelle risposte. Per saperne di più sui token, consulta Token web JSON.

Cerca l'attività per ID attività

Puoi cercare un'attività in base al relativo ID da un ambiente server utilizzando gRPC o REST. I seguenti esempi mostrano come utilizzare la libreria gRPC Java o una richiesta REST per GetTask.

gRPC

 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

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>

  • <id> è un identificatore univoco dell'attività.
  • <taskId> è l'ID dell'attività da cercare.
  • 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 degli account di servizio e Token web JSON.
  • Il corpo della richiesta deve essere vuoto.
  • Se la ricerca ha esito positivo, il corpo della risposta contiene un'entità dell'attività.

Comando curl di esempio:

    # 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}"

Cerca le attività per ID monitoraggio

Gli esempi seguenti mostrano come cercare le attività in base all'ID monitoraggio della spedizione utilizzando gRPC o una chiamata REST HTTP a GetTaskTrackingInfo.

gRPC

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

REST

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>

  • <tracking_id> è l'ID monitoraggio associato all'attività.

  • L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> ha il ruolo di service account corretto. Consulta Ruoli dei service account.

  • Se la ricerca ha esito positivo, il corpo della risposta contiene un'entità taskTrackingInfo.

Comando curl di esempio:

# 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}"

Elenca attività

La visualizzazione dell'elenco delle attività richiede un accesso ampio alle attività. La visualizzazione dell'elenco delle attività è destinata solo agli utenti attendibili. Utilizza i token di autenticazione Delivery Fleet Reader o Delivery Admin quando effettui richieste di elenco delle attività. Per saperne di più, consulta Ruoli dei service account.

Impagina gli elenchi

Gli elenchi di attività sono impaginati. È possibile specificare una dimensione della pagina nelle richieste di elenco delle attività. Se viene specificata una dimensione della pagina, il numero di attività restituite non è superiore alla dimensione della pagina specificata. Se non è presente alcuna dimensione della pagina, viene utilizzato un valore predefinito ragionevole. Se la dimensione della pagina richiesta supera un valore massimo interno, viene utilizzato il valore massimo interno.

Un elenco di attività può includere un token per la lettura della pagina di risultati successiva. Per recuperare la pagina successiva, invia nuovamente la stessa richiesta insieme al token di pagina. Quando il token di pagina restituito è vuoto, non sono disponibili altre attività da recuperare.

Campi durante l'elenco delle attività

Fleet Engine oscura i seguenti campi quando elenca le attività:

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

Utilizza i seguenti formati dei campi in base alle proposte di miglioramento delle API di Google:

Tipo di campo Formato Esempio
Timestamp RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Durata Numero di secondi seguito da s task_duration = 120s
Enum Stringa state = CLOSED AND type = PICKUP
Località point.latitude e point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Filtra le attività elencate

Puoi filtrare le attività elencate in base alla maggior parte delle proprietà delle attività. Per la sintassi delle query di filtro, consulta AIP-160. Se non viene specificata alcuna query di filtro, vengono elencate tutte le attività.

La tabella seguente mostra le proprietà delle attività valide che puoi utilizzare per i filtri:

Proprietà delle attività per filtrare gli elenchi
  • type
  • attributes
  • tracking_id
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_duration_outcome
  • task_outcome
  • task_outcome_location
  • task_outcome_time

Consulta AIP-160 per un elenco completo degli operatori di query di filtro.

Esempi di attività di elenco

L'esempio seguente mostra come elencare le attività per un deliveryVehicleId e un attributo dell'attività, sia con la libreria gRPC Java sia con la chiamata REST HTTP a ListTasks.

Una risposta corretta può comunque essere vuota. Una risposta vuota indica che non sono presenti attività associate al valore deliveryVehicleId fornito.

gRPC

 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

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks

Per applicare un filtro alle attività elencate, includi un parametro URL "filter" con una query di filtro con escape URL come valore.

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> ha il ruolo di service account corretto. Consulta Ruoli dei service account.

Una ricerca riuscita fornisce un corpo della risposta con la seguente struttura:

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

Comando curl di esempio:

 # 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}"

Passaggi successivi