Aufgaben suchen

In diesem Dokument wird beschrieben, wie Sie Aufgabeninformationen von einem Server oder Browser abrufen können. Die Fleet Engine unterstützt zwei Möglichkeiten, Aufgaben zu finden:

  • Aufgaben suchen: Sie können Aufgaben anhand der folgenden IDs suchen:

    • Aufgaben-ID: Wird von Nutzern wie Flottenbetreibern verwendet, die Zugriff auf die vollständige Ansicht der Aufgabendaten haben.
    • Tracking-ID: Wird von Ihrer Clientsoftware verwendet, um einem Endnutzer begrenzte Informationen bereitzustellen, z. B. wann ein Paket bei ihm zu Hause erwartet wird.

    Achten Sie darauf, den Unterschied zwischen der Aufgaben-ID und der Aufgaben-Tracking-ID zu kennen. Sie sind jedoch nicht identisch. Weitere Informationen finden Sie im Leitfaden für geplante Aufgaben unter Grundlegende Aufgabenfelder.

  • Aufgaben auflisten: Umfassender Zugriff auf Aufgaben, nur für vertrauenswürdige Nutzer.

Aufgaben suchen

In diesem Abschnitt wird beschrieben, wie Sie Aufgaben anhand der Aufgaben-ID oder Tracking-ID suchen. Es hat folgende Anforderungen:

  • Suchvorgänge nach Tracking-ID müssen den Sichtbarkeitsregeln entsprechen, die unter Sichtbarkeitsregeln für getrackte Objekte angegeben sind.

  • Verwenden Sie das kleinstmögliche Token, um Sicherheitsrisiken zu minimieren. Wenn Sie beispielsweise ein Lieferverbrauchertoken verwenden, werden bei allen Aufrufen nur Informationen zurückgegeben, die für diesen Endnutzer relevant sind, z. B. der Absender oder der Empfänger einer Sendung. Alle anderen Informationen in den Antworten werden von der Fleet Engine entfernt. Weitere Informationen zu Tokens finden Sie unter JSON Web Tokens.

Aufgabe anhand der Aufgaben-ID suchen

Sie können eine Aufgabe anhand ihrer Aufgaben-ID in einer Serverumgebung mit gRPC oder REST suchen. In den folgenden Beispielen wird gezeigt, wie Sie die Java-gRPC-Bibliothek oder eine REST-Anfrage an GetTask verwenden.

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> ist eine eindeutige Kennung für die Aufgabe.
  • <taskId> ist die ID der Aufgabe, die Sie abrufen möchten.
  • Der Anfrageheader muss ein Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> von Ihrem Server gemäß den Richtlinien in Dienstkontorollen und JSON Web Tokens ausgestellt wird.
  • Der Anfragetext muss leer sein.
  • Wenn die Suche erfolgreich ist, enthält der Antworttext eine Aufgabenentität.

Beispiel eines curl-Befehls:

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

Aufgaben nach Tracking-ID suchen

In den folgenden Beispielen wird gezeigt, wie Sie Aufgaben anhand ihrer Sendungsverfolgungs-ID entweder über gRPC oder einen HTTP-REST-Aufruf an GetTaskTrackingInfo suchen.

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> ist die Tracking-ID, die mit der Aufgabe verknüpft ist.

  • Der Anfrageheader muss ein Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> die richtige Dienstkontorolle enthält. Siehe Dienstkontenrollen.

  • Wenn die Suche erfolgreich ist, enthält der Antworttext eine taskTrackingInfo-Entität.

Beispiel eines curl-Befehls:

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

Aufgaben auflisten

Für das Auflisten von Aufgaben ist ein umfassender Zugriff auf Aufgaben erforderlich. Das Auflisten von Aufgaben ist nur für vertrauenswürdige Nutzer vorgesehen. Verwenden Sie bei Anfragen zum Auflisten von Aufgaben Authentifizierungstokens für die Rolle „Delivery Fleet Reader“ oder „Delivery Admin“. Weitere Informationen finden Sie unter Dienstkontenrollen.

Listen paginieren

Aufgabenlisten sind paginiert. In Anfragen zum Auflisten von Aufgaben kann eine Seitengröße angegeben werden. Wenn eine Seitengröße angegeben ist, ist die Anzahl der zurückgegebenen Aufgaben nicht größer als die angegebene Seitengröße. Wenn keine Seitengröße vorhanden ist, wird ein angemessener Standardwert verwendet. Wenn die angeforderte Seitengröße einen internen Höchstwert überschreitet, wird der interne Höchstwert verwendet.

Eine Aufgabenliste kann ein Token zum Lesen der nächsten Ergebnisseite enthalten. Wenn Sie die nächste Seite abrufen möchten, senden Sie dieselbe Anfrage noch einmal zusammen mit dem Seitentoken. Wenn das zurückgegebene Seiten-Token leer ist, sind keine weiteren Aufgaben zum Abrufen verfügbar.

Felder beim Auflisten von Aufgaben

Die Fleet Engine entfernt die folgenden Felder, wenn Aufgaben aufgelistet werden:

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

Verwenden Sie die folgenden Feldformate, die auf den Google API Improvement Proposals basieren:

Feldtyp Format Beispiel
Zeitstempel RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Dauer Anzahl der Sekunden, gefolgt von einem s task_duration = 120s
Enum String state = CLOSED AND type = PICKUP
Standort point.latitude und point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Aufgelistete Aufgaben filtern

Sie können die aufgelisteten Aufgaben nach den meisten Aufgabenattributen filtern. Informationen zur Syntax von Filterabfragen finden Sie unter AIP-160. Wenn keine Filterabfrage angegeben ist, werden alle Aufgaben aufgelistet.

In der folgenden Tabelle sind gültige Aufgabenattribute aufgeführt, die Sie zum Filtern verwenden können:

Aufgabenattribute zum Filtern von Listen
  • type
  • attributes
  • tracking_id
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_duration_outcome
  • task_outcome
  • task_outcome_location
  • task_outcome_time

Eine vollständige Liste der Operatoren für Filterabfragen finden Sie unter AIP-160.

Beispiele für Aufgaben auflisten

Im folgenden Beispiel wird gezeigt, wie Sie Aufgaben für eine deliveryVehicleId und ein Aufgabenattribut auflisten, sowohl mit der Java gRPC-Bibliothek als auch mit einem HTTP-REST-Aufruf an ListTasks.

Eine erfolgreiche Antwort kann auch leer sein. Eine leere Antwort bedeutet, dass dem angegebenen deliveryVehicleId keine Aufgaben zugeordnet sind.

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

Wenn Sie einen Filter auf die aufgelisteten Aufgaben anwenden möchten, fügen Sie einen URL-Parameter „filter“ mit einer URL-codierten Filterabfrage als Wert hinzu.

Der Anfrageheader muss ein Feld Authorization mit dem Wert Bearer <token> enthalten, wobei <token> die richtige Dienstkontorolle enthält. Siehe Dienstkontenrollen.

Eine erfolgreiche Suche liefert einen Antworttext mit der folgenden Struktur:

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

Beispiel eines curl-Befehls:

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

Nächste Schritte