本頁面由 Cloud Translation API 翻譯而成。

尋找工作

本文將說明如何從伺服器或瀏覽器中找出工作資訊。Fleet Engine 支援兩種找尋工作的方式：

查詢工作：您可以使用下列 ID 查詢工作：
- 工作 ID：可由車隊操作員等使用者使用，這些使用者可查看工作資料的完整檢視畫面。
- 追蹤 ID：用於客戶端軟體，向使用者提供有限資訊，例如包裹何時會送達。
請務必瞭解工作 ID 和工作追蹤 ID 的差異。兩者並不相同。請參閱「預定工作指南」中的「基本工作欄位」。
列出工作：可存取所有工作，但僅限於信任的使用者。

查詢工作

本節說明如何依工作 ID 或追蹤 ID 查詢工作。相關規定如下：

透過追蹤 ID 進行查詢時，必須遵循「追蹤物件的顯示規則」中所述的顯示規則。
請盡可能使用最狹隘的權杖，以降低安全性風險。舉例來說，如果您使用「傳送消費者憑證」，則任何呼叫都只會傳回與該使用者相關的資訊，例如貨運的寄件者或收件者。Fleet Engine 會在回應中遮蓋所有其他資訊。如要進一步瞭解符記，請參閱「JSON Web 符記」。

依工作 ID 查詢工作

您可以使用 gRPC 或 REST，根據伺服器環境中的工作 ID 查詢工作。以下範例說明如何使用 Java gRPC 程式庫或 REST 要求來 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> 是工作專屬 ID。
<taskId> 是需要查詢的工作 ID。
要求標頭必須包含「Authorization」欄位，其值為「Bearer <token>」，其中 <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 或 HTTP REST 呼叫至 GetTaskTrackingInfo，依據運送追蹤 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。
要求標頭必須包含「Authorization」欄位，其值為「Bearer <token>」，其中<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}"

欄位類型	格式	範例
時間戳記	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`

用於篩選清單的工作屬性
`type` `attributes` `tracking_id` `delivery_vehicle_id` `state` `planned_location`	`task_duration` `task_duration_outcome` `task_outcome` `task_outcome_location` `task_outcome_time`

列出工作

列出工作會要求工作存取權的廣泛存取權。只有可信任的使用者才能列出工作。請在提出清單工作要求時，使用 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 程式庫和 HTTP REST 呼叫 ListTasks，列出 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」網址參數，並將網址轉義篩選器查詢做為其值。

要求標頭必須包含「Authorization」欄位，其值為「Bearer <token>」，其中<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}"

後續步驟

管理出貨作業