Trovare le attività

Questo documento descrive i modi in cui trovare informazioni sulle attività da un un server web o 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 versione completa dei dati dell'attività.
    • ID tracciamento: utilizzato dal software client per fornire informazioni limitate a un utente finale, ad esempio quando è previsto l'arrivo di un pacco a casa sua.

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

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

Cercare le attività

Questa sezione descrive come cercare le attività per ID attività o ID monitoraggio. Deve soddisfare i seguenti requisiti:

  • Le ricerche per ID monitoraggio devono rispettare le regole di visibilità in 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 consumer per la consegna, tutte le chiamate restituiscono solo le 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 ulteriori informazioni sui token, consulta la pagina Token web JSON.

Cerca attività per ID attività

Puoi cercare un'attività in base al suo ID da un ambiente server utilizzando gRPC REST. I seguenti esempi mostrano come utilizzare la libreria Java gRPC o una richiesta REST a 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à.
  • &lt;taskId&gt; è l'ID dell'attività da cercare.
  • L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è emesso dal tuo server secondo le linee guida descritte in Ruoli dell'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}"

Cercare le 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>

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

  • L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> indica il servizio corretto . 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à delle schede sono destinate esclusivamente utenti attendibili. Usa i token di autenticazione Lettore parco risorse o Amministratore consegna quando si effettuano richieste di attività di elenco. Per ulteriori informazioni, consulta Ruoli dell'account di servizio informazioni.

Elenchi paginati

Gli elenchi di attività sono suddivisi in pagine. Nelle richieste di elenco di attività è possibile specificare una dimensione di pagina. Se viene specificata una dimensione della pagina, il numero di attività restituite non è superiore alla dimensione della pagina specificata. Se non sono presenti dimensioni di pagina, un valore predefinito ragionevole . Se le dimensioni di pagina richieste superano un valore massimo interno, si utilizza 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 di nuovo la stessa richiesta insieme al token di pagina. Quando il token di pagina restituito è vuoto, non sono disponibili altre attività per il recupero.

Campi nell'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 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 seguiti 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à valide delle attività che puoi utilizzare per l'applicazione di 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

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 c'è 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 "filter" con una query di filtro con escape per URL come valore.

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> indica il servizio corretto . 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
    }

Esempio di comando curl:

 # 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