Trovare le attività

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

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

    • ID attività: utilizzato da utenti come gli operatori del parco veicoli che hanno accesso alla visualizzazione completa dei dati delle attività.
    • ID monitoraggio: utilizzato dal software client per fornire informazioni limitate a un utente finale, ad esempio quando è previsto 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 di attività di base nella guida sulle attività pianificate.

  • Elenca attività: accesso ampio alle attività destinato solo a utenti attendibili.

Cercare le attività

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

  • Le ricerche per ID monitoraggio devono rispettare le regole di visibilità specificate nella sezione Regole di visibilità per gli oggetti monitorati.

  • Utilizza il token più limitato possibile per limitare i rischi per la sicurezza. Ad esempio, se utilizzi un token consumatore per la consegna, ogni chiamata restituisce solo informazioni pertinenti per l'utente finale in questione, come il corriere o il destinatario di una spedizione. Fleet Engine oscura tutte le altre informazioni nelle risposte. Per ulteriori informazioni sui token, consulta la pagina Token web JSON.

Attività di ricerca per ID attività

Puoi cercare un'attività tramite il relativo ID da un ambiente server utilizzando gRPC o REST. Gli esempi seguenti mostrano come utilizzare la libreria gRPC per 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 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à.

Esempio di comando curl:

    # 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 attività per ID monitoraggio

Gli esempi riportati di seguito mostrano come cercare le attività in base al relativo ID tracciabilità 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>

  • &lt;tracking_id&gt; è l'ID monitoraggio associato all'attività.

  • L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> corrisponde al ruolo corretto per l'account di servizio. Vedi Ruoli dell'account di servizio.

  • Se la ricerca va a buon fine, il corpo della risposta contiene un'entità taskTrackingInfo.

Esempio di comando curl:

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

L'elenco delle attività richiede l'accesso ampio alle attività. Le attività di elenco sono destinate solo agli utenti fidati. Utilizza i token di autenticazione Delivery Fleet Reader o Delivery Admin quando effettui richieste di attività dell'elenco. Per ulteriori informazioni, consulta la sezione Ruoli degli account di servizio.

Impagina gli elenchi

Gli elenchi di attività sono suddivisi in pagine. È possibile specificare una dimensione di pagina nelle richieste di attività di elenco. Se viene specificata una dimensione della pagina, il numero di attività restituite non è superiore alla dimensione della pagina specificata. Se non è presente alcuna dimensione di pagina, viene utilizzata una predefinita ragionevole. Se le dimensioni di pagina richieste superano un valore massimo interno, viene utilizzato il valore massimo interno.

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

Campi per la visualizzazione 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 basati sulle 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

Filtrare le attività elencate

Puoi filtrare le attività elencate in base alla maggior parte delle proprietà. 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 filtrare:

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

Per un elenco completo degli operatori di query di filtro, vedi AIP-160.

Elenco esempi di attività

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

Una risposta corretta può essere ancora vuota. Una risposta vuota indica che non ci sono attività associate all'oggetto 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 "filtro" con una query di filtro con escape come valore.

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> indica il ruolo corretto dell'account di servizio. Vedi Ruoli dell'account di servizio.

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