In diesem Dokument wird beschrieben, wie Sie Aufgabeninformationen von einem Server oder Browser abrufen können. Fleet Engine unterstützt zwei Möglichkeiten zum Auffinden von Aufgaben:
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 zur Verfügung zu stellen, z. B. wann ein Paket bei ihm zugestellt wird.
Achten Sie darauf, den Unterschied zwischen der Aufgaben-ID und der Aufgaben-Tracking-ID zu verstehen. Sie sind jedoch nicht identisch. Weitere Informationen finden Sie im Leitfaden zu geplanten Aufgaben unter Grundlegende Aufgabenfelder.
Aufgaben auflisten: umfassender Zugriff auf Aufgaben, der nur für vertrauenswürdige Nutzer vorgesehen ist.
Aufgaben suchen
In diesem Abschnitt wird beschrieben, wie Sie Aufgaben anhand der Aufgaben-ID oder der Tracking-ID suchen. Es gelten folgende Anforderungen:
Lookups nach Tracking-ID müssen den Sichtbarkeitsregeln entsprechen, die unter Sichtbarkeitsregeln für nachverfolgte Objekte angegeben sind.
Verwenden Sie das möglichst eng gefasste Token, um Sicherheitsrisiken zu begrenzen. Wenn Sie beispielsweise ein Delivery Consumer Token verwenden, werden bei jedem Aufruf nur Informationen zurückgegeben, die für diesen Endnutzer relevant sind, z. B. das Versandunternehmen oder den Empfänger einer Sendung. Alle anderen Informationen in den Antworten werden von Fleet Engine entfernt. Weitere Informationen zu Tokens finden Sie unter JSON-Webtokens.
Aufgabe nach Aufgaben-ID suchen
Sie können eine Aufgabe anhand ihrer Aufgabe-ID in einer Serverumgebung mit gRPC oder REST abrufen. Die folgenden Beispiele zeigen, wie die Java-gRPC-Bibliothek oder eine REST-Anfrage für GetTask verwendet wird.
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, wobei <token> von Ihrem Server gemäß den unter Dienstkontorollen und JSON-Webtokens beschriebenen Richtlinien ausgegeben 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 anhand der Tracking-ID nachschlagen
Die folgenden Beispiele zeigen, wie Aufgaben mithilfe von gRPC oder einem HTTP REST-Aufruf an GetTaskTrackingInfo
anhand ihrer Sendungsverfolgungs-ID gesucht werden.
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 war, enthält der Antworttext die Entität taskTrackingInfo.
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ürdige Nutzer vorgesehen. 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.
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 vorhanden ist, wird ein angemessener Standardwert 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. Senden Sie dieselbe Anfrage zusammen mit dem Seitentoken noch einmal, um die nächste Seite abzurufen. Wenn das zurückgegebene Seiten-Token leer ist, sind keine weiteren Aufgaben zum Abrufen verfügbar.
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 basierend auf Google API-Verbesserungsvorschlägen die folgenden Feldformate:
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 Filterabfragesyntax finden Sie unter AIP-160. Wenn keine Filterabfrage angegeben ist, werden alle Aufgaben aufgeführt.
Die folgende Tabelle enthält gültige Aufgabeneigenschaften, die Sie zum Filtern verwenden können:
Aufgabeneigenschaften zum Filtern von Listen | |
---|---|
|
|
Eine vollständige Liste der Filterabfrageoperatoren finden Sie unter AIP-160.
Beispiele für Aufgaben auflisten
Das folgende Beispiel zeigt, wie Aufgaben für eine deliveryVehicleId
und ein Aufgabenattribut sowohl mit der Java gRPC-Bibliothek als auch mit dem HTTP REST-Aufruf von ListTasks
aufgelistet werden.
Eine erfolgreiche Antwort kann trotzdem 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 die aufgeführten Aufgaben filtern möchten, fügen Sie den URL-Parameter „filter“ mit einer URL-entcodierten Filterabfrage als Wert hinzu.
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.
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}"