查找任务

本文档介绍了从服务器或浏览器查找任务信息的方法。Fleet Engine 支持通过以下两种方式查找任务：

• 查找任务：您可以按照以下 ID 查找任务：

  • 任务 ID：供车队运营商等有权查看任务数据完整视图的用户使用。
  • 跟踪 ID：客户端软件用来向最终用户提供有限信息（例如包裹预计送达时间）

  请务必了解任务 ID 与任务跟踪 ID 之间的区别。二者并不相同。请参阅“安排的任务”指南中的基本任务字段。

• 列出任务：对任务具有广泛的访问权限，仅适用于可信用户。

注意：如果您使用可让驱动程序控制任务的可信客户端模型，请注意，Driver SDK 不支持查找或列出任务。

查询任务

本部分介绍如何按任务 ID 或跟踪 ID 查找任务。它具有以下要求：

• 按跟踪 ID 进行查找时，必须遵循跟踪对象的可见性规则中所述的可见性规则。

• 使用尽可能窄的令牌限制安全风险。例如，如果您使用的是传送使用方令牌，则任何调用都只会返回与该最终用户相关的信息，例如发货人或收货人。Fleet Engine 会隐去响应中的所有其他信息。如需详细了解令牌，请参阅 JSON Web 令牌。

按任务 ID 查找任务

您可以使用 gRPC 或 REST 在服务器环境中按任务 ID 查找任务。以下示例展示了如何使用 Java gRPC 库或对 GetTask 发出 REST 请求。

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> 是任务的唯一标识符。
• <taskId> 是要查找的任务的 ID。
• 请求标头必须包含一个值为 Bearer <token> 的 Authorization 字段，其中 <token> 由您的服务器根据服务账号角色和 JSON Web 令牌中所述的指南签发。
• 请求正文必须为空。
• 如果查找成功，响应正文将包含一个任务实体。

示例 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}"

按跟踪 ID 查找任务

以下示例展示了如何使用 gRPC 或对 GetTaskTrackingInfo 的 HTTP REST 调用按运单跟踪 ID 查找任务。

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> 是与任务关联的跟踪 ID。

• 请求标头必须包含值为 Bearer <token> 的字段 Authorization，其中 <token> 具有正确的服务账号角色。请参阅服务账号角色。

• 如果查找成功，响应正文将包含一个 taskTrackingInfo 实体。

示例 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}"

列出任务

列出任务会请求对任务的广泛访问权限。列出任务功能仅适用于受信任的用户。发出列表任务请求时，请使用 Delivery Fleet Reader 或 Delivery Admin 身份验证令牌。如需了解详情，请参阅服务账号角色。

将列表分页

任务列表会分页显示。您可以在列出任务的请求中指定页面大小。如果指定了页面大小，则返回的任务数量不得超过指定的页面大小。如果没有页面大小，则使用合理的默认值。如果请求的页面大小超出内部最大值，则使用内部最大值。

任务列表可以包含用于读取下一页结果的令牌。如需检索该下一页，请重新发出相同的请求以及页面令牌。当返回的页面令牌为空时，没有其他任务可供检索。

列出任务时的字段

Fleet Engine 在列出任务时会隐去以下字段：

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

根据 Google API 改进建议使用以下字段格式：

字段类型	格式	示例
时间戳	RFC-3339	task_outcome_time = 2022-03-01T11:30:00-08:00
时长	后跟 s 的秒数	task_duration = 120s
枚举	字符串	state = CLOSED AND type = PICKUP
位置	point.latitude和point.longitude	planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

过滤列出的任务

您可以按大多数任务属性过滤所列任务。如需了解过滤条件查询语法，请参阅 AIP-160。如果未指定任何过滤条件查询，系统会列出所有任务。

注意 ：对任务属性进行过滤可能会导致检索延迟时间显著增加，因此应谨慎使用。

下表显示了可用于过滤的有效任务属性：

用于过滤列表的任务属性
type attributes tracking_id delivery_vehicle_id state planned_location	task_duration task_duration_outcome task_outcome task_outcome_location task_outcome_time

如需查看过滤条件查询运算符的完整列表，请参阅 AIP-160。

列表任务示例

以下示例展示了如何使用 Java gRPC 库和对 ListTasks 的 HTTP REST 调用，为 deliveryVehicleId 和任务属性列出任务。

成功的响应可能仍为空。空响应表示没有与提供的 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

如需对所列任务应用过滤条件，请添加“filter”网址参数，并将网址转义的过滤条件查询作为其值。

请求标头必须包含一个值为 Bearer <token> 的 Authorization 字段，其中 <token> 具有正确的服务账号角色。请参阅服务账号角色。

成功的查找会提供采用以下结构的响应正文：

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

示例 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}"

后续步骤

• 管理发货