Aufgaben suchen

In diesem Dokument wird beschrieben, wie Sie Aufgabeninformationen von einem Server oder Browser abrufen können. 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 alle Ansicht der Aufgabendaten.
    • Tracking-ID: wird von Ihrer Client-Software verwendet, um eingeschränkte Informationen bereitzustellen an Endnutzer gesendet werden, z. B. wenn ein Paket bei sich zu Hause erwartet wird.

    Achten Sie darauf, den Unterschied zwischen der Aufgaben-ID und der Aufgaben-Tracking-ID zu verstehen. Sie sind jedoch nicht identisch. Siehe Grundlegende Aufgabenfelder in der Geplante Aufgabenübersicht.

  • Aufgabenliste: 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 der Tracking-ID suchen. Es gelten folgende Anforderungen:

  • Suchanfragen nach der Tracking-ID müssen den Sichtbarkeitsregeln entsprechen, die unter Sichtbarkeitsregeln für getrackte Objekte beschrieben sind.

  • Verwenden Sie das möglichst eng gefasste Token, um Sicherheitsrisiken zu begrenzen. Wenn Sie beispielsweise ein Delivery Consumer Token verwenden, werden alle Aufrufe nur Informationen, die für diesen Endnutzer relevant sind, wie etwa das Versandunternehmen oder Empfänger einer Sendung. Alle anderen Informationen in den Antworten werden von 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 abrufen. In den folgenden Beispielen wird gezeigt, wie Sie die Java gRPC-Bibliothek oder eine REST-Anfrage verwenden, um GetTask aufzurufen.

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 gesucht werden soll.
  • Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten. Dabei wird <token> von deinem Server gemäß den in den Abschnitten Dienstkontorollen und JSON Web Tokens beschriebenen Richtlinien ausgestellt.
  • Der Anfragetext muss leer sein.
  • Wenn die Suche erfolgreich war, 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 Sendungs-ID mit gRPC oder einem 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 das Feld Authorization mit dem Wert Bearer <token> enthalten. Dabei muss <token> die richtige Rolle für das Dienstkonto haben. Siehe Dienstkontorollen.

  • Wenn die Suche erfolgreich ist, enthält der Antworttext ein 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

Wenn Sie Aufgaben auflisten, wird ein umfassender Zugriff auf Aufgaben angefordert. Das Auflisten von Aufgaben ist nur für vertrauenswürdigen Nutzern. Verwenden Sie Authentifizierungstokens für Leser oder Administratoren von Fleet Engine Delivery, wenn Sie Anfragen für Listenaufgaben stellen. Weitere Informationen finden Sie unter Dienstkontorollen. Informationen.

Listen paginieren

Aufgabenlisten sind paginiert. Eine Seitengröße kann in Anfragen vom Typ „Aufgaben auflisten“ 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 angegeben ist, wird eine angemessene Standardgröße verwendet. Wenn die angeforderte Seitengröße einen internen Maximalwert überschreitet, wird der interne Maximalwert verwendet.

Eine Aufgabenliste kann ein Token zum Lesen der nächsten Ergebnisseite enthalten. Bis die nächste Seite abrufen und dieselbe Anfrage zusammen mit dem Seitentoken erneut senden. Wenn das zurückgegebene Seitentoken leer ist, sind keine weiteren Aufgaben für Datenabruf.

Felder beim Auflisten von Aufgaben

In Fleet Engine werden die folgenden Felder beim Auflisten von Aufgaben entfernt:

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

Verwenden Sie die folgenden Feldformate, die auf Vorschlägen zur Verbesserung der Google API 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

Aufgeführte Aufgaben filtern

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

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

Aufgabeneigenschaften 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 Filterabfrageoperatoren finden Sie unter AIP-160.

Beispiele für Aufgaben auflisten

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

Eine erfolgreiche Antwort kann immer noch leer sein. Eine leere Antwort gibt an, dass mit dem angegebenen deliveryVehicleId keine Aufgaben verknüpft 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 aufgeführten Aufgaben anwenden möchten, fügen Sie einen „Filter“ hinzu URL-Parameter mit einer Filterabfrage mit URL-Escaping als Wert.

Der Anfrageheader muss das Feld Authorization mit dem Wert Bearer <token> enthalten. Dabei muss <token> die richtige Rolle für das Dienstkonto haben. Siehe Dienstkontorollen.

Bei einer erfolgreichen Suche wird ein Antworttext mit der folgenden Struktur zurückgegeben:

    // 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