Find tasks

This document describes the ways that you can find task information from a server or browser. Fleet Engine supports two ways to find tasks:

Look up tasks: You can look up tasks by the following IDs:
- Task ID: used by users like fleet operators who have access to the full view of the task data.
- Tracking ID: used by your client software to provide limited information to an end user, such as when a package is expected at their house.
Be sure to understand the difference between the task ID and the task tracking ID. They are not the same. See Basic task fields in the Scheduled task guide.
List tasks: a broad access to tasks, intended for trusted users only.

Look up tasks

This section describes how to lookup tasks by task ID or tracking ID. It has the following requirements:

Lookups by tracking ID must adhere to the visibility rules stated in Visibility rules for tracked objects .
Use the narrowest token possible to limit security risks. For example, if you use a Delivery Consumer Token, any calls return only information relevant to that end user, such as the shipper or the receiver of a shipment. Fleet Engine redacts all other information in the responses. For more information about tokens, see JSON Web tokens .

Lookup task by task ID

You can look up a task by its task ID from a server environment using gRPC or REST. The following examples show how to use the Java gRPC library or a REST request to 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> is a unique identifier for the task.
<taskId> is the ID of the task to look up.
The request header must contain a field Authorization with the value Bearer <token> , where <token> is issued by your server according to the guidelines described in Service account roles and JSON Web tokens .
The request body must be empty.
If the lookup is successful, the response body contains a task entity.

Example curl command:

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

Lookup tasks by tracking ID

The following examples show how to lookup tasks by their shipment tracking ID using either gRPC or an HTTP REST call to 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> is the tracking ID associated with the task.
The request header must contain a field Authorization with the value Bearer <token> , where <token> bears the correct service account role. See Service account roles .
If the lookup is successful, the response body contains a taskTrackingInfo entity.

Example curl command:

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

List tasks

Listing tasks requests broad access to tasks. Listing tasks is intended only for trusted users. Use Delivery Fleet Reader or Delivery Admin authentication tokens when making list tasks requests. See Service account roles for more information.

Paginate lists

Task lists are paginated. A page size can be specified in list tasks requests. If a page size is specified, the number of returned tasks is no greater than the specified page size. If no page size is present, a reasonable default is used. If the requested page size exceeds an internal maximum value, then the internal maximum is used.

A task list can include a token for reading the next page of results. To retrieve that next page, re-issue the same request along with the page token. When the returned page token is empty, no more tasks are available for retrieval.

Fields when listing tasks

Fleet Engine redacts the following fields when listing tasks:

VehicleStop.planned_location
VehicleStop.state
VehicleStop.TaskInfo.taskId

Use the following field formats based on Google API Improvement Proposals:

Field Type	Format	Example
Timestamp	RFC-3339	`task_outcome_time = 2022-03-01T11:30:00-08:00`
Duration	Number of seconds followed by an `s`	`task_duration = 120s`
Enum	String	`state = CLOSED AND type = PICKUP`
Location	`point.latitude` and `point.longitude`	`planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0`

Filter listed tasks

You can filter listed tasks by most task properties. For filter query syntax, see AIP-160 . If no filter query is specified, all tasks are listed.

The following table shows valid task properties that you can use for filtering:

Task properties for filtering lists

type
attributes
tracking_id
delivery_vehicle_id
state
planned_location

task_duration
task_duration_outcome
task_outcome
task_outcome_location
task_outcome_time

See AIP-160 for a full list of filter query operators.

List task examples

The following example shows how to list tasks for a deliveryVehicleId and a task attribute, both with the Java gRPC library and with HTTP REST call to ListTasks .

A successful response can still be empty. An empty response indicates no tasks associated the supplied 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

To apply a filter to the listed tasks, include a "filter" URL parameter with a URL-escaped filter query as its value.

The request header must contain a field Authorization with the value Bearer <token> , where <token> bears the correct service account role. See Service account roles .

A successful lookup provides a response body with the following structure:

   
 // JSON representation 
  
 { 
  
 "tasks" 
 : 
  
 [ 
  
 { 
  
 objec 
 t 
  
 (Task) 
  
 } 
  
 ], 
  
 "nextPageToken" 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 "totalSize" 
 : 
  
 i 
 nte 
 ger 
  
 }

Example curl command:

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

What's next

Manage shipments

Find tasks Stay organized with collections Save and categorize content based on your preferences.

Look up tasks

Lookup task by task ID

gRPC

REST

Lookup tasks by tracking ID

gRPC

REST

List tasks

Paginate lists

Fields when listing tasks

Filter listed tasks

List task examples

gRPC

REST

What's next

Find tasks