Znajdowanie zadań

Z tego dokumentu dowiesz się, jak znaleźć informacje o zadaniach na serwerze lub w przeglądarce. Fleet Engine obsługuje 2 sposoby wyszukiwania zadań:

  • Wyszukiwanie zadań: możesz wyszukiwać zadania według tych identyfikatorów:

    • Identyfikator zadania: używany przez użytkowników, takich jak operatorzy floty, którzy mają dostęp do pełnego widoku danych zadania.
    • Identyfikator śledzenia: używany przez oprogramowanie klienta do przekazywania użytkownikowi końcowemu ograniczonych informacji, np. o przewidywanym czasie dostawy paczki.

    Pamiętaj o różnicy między identyfikatorem zadania a identyfikatorem śledzenia zadania. Są to jednak różne rzeczy. Więcej informacji znajdziesz w sekcji Podstawowe pola zadania w przewodniku po zaplanowanych zadaniach.

  • Wyświetlanie listy zadań: szeroki dostęp do zadań, przeznaczony tylko dla zaufanych użytkowników.

Wyszukiwanie zadań

W tej sekcji opisano, jak wyszukiwać zadania według identyfikatora zadania lub identyfikatora śledzenia. Wymagania:

  • Wyszukiwanie według identyfikatora śledzenia musi być zgodne z regułami widoczności określonymi w sekcji Reguły widoczności śledzonych obiektów.

  • Aby ograniczyć zagrożenia dla bezpieczeństwa, używaj jak najwęższego tokena. Jeśli na przykład używasz tokena konsumenta dostawy, wszystkie wywołania zwracają tylko informacje istotne dla tego użytkownika, np. nadawcę lub odbiorcę przesyłki. Fleet Engine usuwa wszystkie inne informacje w odpowiedziach. Więcej informacji o tokenach znajdziesz w sekcji Tokeny sieciowe JSON.

Wyszukiwanie zadania według identyfikatora zadania

Zadanie możesz wyszukać według jego identyfikatora zadania w środowisku serwera za pomocą gRPC lub REST. Poniższe przykłady pokazują, jak użyć biblioteki Java gRPC lub żądania REST do wywołania 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> to unikalny identyfikator zadania.
  • <taskId> to identyfikator zadania, które chcesz wyszukać.
  • Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> jest wydawany przez serwer zgodnie z wytycznymi opisanymi w sekcji Role konta usługi i tokeny sieciowe JSON.
  • Treść żądania musi być pusta.
  • Jeśli wyszukiwanie się powiedzie, treść odpowiedzi będzie zawierała encję zadania.

Przykład polecenia 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}"

Wyszukiwanie zadań według identyfikatora śledzenia

Poniższe przykłady pokazują, jak wyszukiwać zadania według ich identyfikatora śledzenia przesyłki za pomocą gRPC lub wywołania HTTP REST do 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> to identyfikator śledzenia powiązany z zadaniem.

  • Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> ma prawidłową rolę konta usługi. Więcej informacji znajdziesz w sekcji Role konta usługi.

  • Jeśli wyszukiwanie się powiedzie, treść odpowiedzi będzie zawierała encję taskTrackingInfo.

Przykład polecenia 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}"

Wyświetlenie listy zadań

Żądania wyświetlenia listy zadań zapewniają szeroki dostęp do zadań. Wyświetlanie listy zadań jest przeznaczone tylko dla zaufanych użytkowników. W przypadku żądań wyświetlenia listy zadań używaj tokenów uwierzytelniania czytelnika floty dostaw lub administratora dostaw. Więcej informacji znajdziesz w sekcji Role konta usługi.

Stronicowanie list

Listy zadań są podzielone na strony. W żądaniach wyświetlenia listy zadań można określić rozmiar strony. Jeśli określisz rozmiar strony, liczba zwracanych zadań nie będzie większa niż określony rozmiar strony. Jeśli nie podasz rozmiaru strony, zostanie użyta rozsądna wartość domyślna. Jeśli żądany rozmiar strony przekracza wewnętrzną wartość maksymalną, zostanie użyta wewnętrzna wartość maksymalna.

Lista zadań może zawierać token do odczytania następnej strony wyników. Aby pobrać następną stronę, ponownie wyślij to samo żądanie wraz z tokenem strony. Gdy zwrócony token strony jest pusty, nie można pobrać więcej zadań.

Pola podczas wyświetlania listy zadań

Fleet Engine usuwa te pola podczas wyświetlania listy zadań:

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

Użyj tych formatów pól na podstawie propozycji ulepszeń interfejsu Google API:

Typ pola Format Przykład
Sygnatura czasowa RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Czas trwania Liczba sekund, po której następuje litera s task_duration = 120s
Typ wyliczeniowy Ciąg znaków state = CLOSED AND type = PICKUP
Lokalizacja point.latitude i point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Filtrowanie wyświetlanych zadań

Wyświetlane zadania możesz filtrować według większości właściwości zadania. Składnię zapytań filtra znajdziesz w AIP-160. Jeśli nie określisz zapytania filtra, zostaną wyświetlone wszystkie zadania.

W tej tabeli znajdziesz prawidłowe właściwości zadania, których możesz użyć do filtrowania:

Właściwości zadania do filtrowania list
  • type
  • attributes
  • tracking_id
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_duration_outcome
  • task_outcome
  • task_outcome_location
  • task_outcome_time

Pełną listę operatorów zapytań filtra znajdziesz w AIP-160.

Przykłady wyświetlania listy zadań

Ten przykład pokazuje, jak wyświetlić listę zadań dla deliveryVehicleId i atrybutu zadania za pomocą biblioteki Java gRPCi wywołania HTTP REST do ListTasks.

Pomyślna odpowiedź może być pusta. Pusta odpowiedź oznacza, że nie ma zadań powiązanych z podanym deliveryVehicleId.

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

Aby zastosować filtr do wyświetlanych zadań, dodaj parametr URL „filter” z zapytaniem filtra w postaci zakodowanej w adresie URL.

Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> ma prawidłową rolę konta usługi. Więcej informacji znajdziesz w sekcji Role konta usługi.

Pomyślne wyszukiwanie zwraca treść odpowiedzi o tej strukturze:

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

Przykład polecenia 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}"

Co dalej?