Tìm việc cần làm

Tài liệu này mô tả các cách bạn có thể tìm thấy thông tin về tác vụ từ máy chủ hoặc trình duyệt. Công cụ của Fleet hỗ trợ hai cách tìm tác vụ:

  • Tìm kiếm việc cần làm: Bạn có thể tìm kiếm việc cần làm theo mã nhận dạng sau:

    • Mã công việc: do những người dùng như người vận hành đội xe sử dụng, những người có quyền truy cập vào chế độ xem đầy đủ của dữ liệu công việc.
    • Mã vận đơn: được phần mềm ứng dụng của bạn sử dụng để cung cấp thông tin giới hạn cho người dùng cuối, chẳng hạn như thời điểm dự kiến gói hàng sẽ đến nhà của họ.

    Hãy nhớ hiểu rõ sự khác biệt giữa mã tác vụ và mã theo dõi tác vụ. Hai trường hợp này không phải là một. Xem phần Các trường cơ bản của việc cần làm trong hướng dẫn về Việc cần làm theo lịch.

  • Danh sách việc cần làm: quyền truy cập rộng rãi vào việc cần làm, chỉ dành cho những người dùng đáng tin cậy.

Tra cứu việc cần làm

Phần này mô tả cách tra cứu công việc theo mã công việc hoặc mã theo dõi. Phương thức này có các yêu cầu sau:

  • Truy vấn theo mã theo dõi phải tuân thủ các quy tắc hiển thị nêu trong phần Quy tắc hiển thị đối tượng được theo dõi.

  • Sử dụng mã thông báo hẹp nhất có thể để hạn chế rủi ro bảo mật. Ví dụ: nếu bạn sử dụng Mã thông báo người dùng phân phối, thì mọi lệnh gọi sẽ chỉ trả về thông tin liên quan đến người dùng cuối đó, chẳng hạn như người gửi hoặc người nhận hàng. Công cụ của Fleet sẽ loại bỏ mọi thông tin khác trong phản hồi. Để biết thêm thông tin về mã thông báo, hãy xem bài viết Mã thông báo web JSON.

Tra cứu việc cần làm theo mã việc cần làm

Bạn có thể tra cứu một tác vụ theo mã tác vụ của tác vụ đó từ môi trường máy chủ bằng cách sử dụng gRPC hoặc REST. Các ví dụ sau đây cho biết cách sử dụng thư viện gRPC Java hoặc yêu cầu 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> là giá trị nhận dạng duy nhất của tác vụ.
  • <taskId> là mã nhận dạng của việc cần làm cần tra cứu.
  • Tiêu đề yêu cầu phải chứa trường Authorization (Uỷ quyền) có giá trị Bearer <token>, trong đó <token> do máy chủ của bạn phát hành theo các nguyên tắc được mô tả trong phần Vai trò của tài khoản dịch vụ và Mã thông báo web JSON.
  • Nội dung yêu cầu phải trống.
  • Nếu tra cứu thành công, nội dung phản hồi sẽ chứa một thực thể công việc.

Ví dụ về lệnh 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}"

Tra cứu công việc theo mã theo dõi

Các ví dụ sau đây cho thấy cách tra cứu công việc theo mã vận đơn bằng cách sử dụng gRPC hoặc lệnh gọi HTTP REST đến 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> là mã theo dõi liên kết với tác vụ.

  • Tiêu đề yêu cầu phải chứa trường Authorization (Uỷ quyền) có giá trị Bearer <token>, trong đó <token> mang vai trò tài khoản dịch vụ chính xác. Xem Vai trò của tài khoản dịch vụ.

  • Nếu tra cứu thành công, nội dung phản hồi sẽ chứa một thực thể taskTrackingInfo.

Ví dụ về lệnh 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}"

Liệt kê việc cần làm

Việc liệt kê việc cần làm sẽ yêu cầu quyền truy cập rộng vào việc cần làm. Tính năng liệt kê công việc chỉ dành cho người dùng đáng tin cậy. Sử dụng mã xác thực của Trình đọc đội xe phân phối hoặc Quản trị viên phân phối khi tạo yêu cầu công việc trong danh sách. Hãy xem phần Vai trò của tài khoản dịch vụ để biết thêm thông tin.

Phân trang danh sách

Danh sách việc cần làm được phân trang. Bạn có thể chỉ định kích thước trang trong các yêu cầu danh sách việc cần làm. Nếu bạn chỉ định kích thước trang, thì số lượng tác vụ được trả về sẽ không lớn hơn kích thước trang đã chỉ định. Nếu không có kích thước trang nào, hệ thống sẽ sử dụng kích thước mặc định hợp lý. Nếu kích thước trang được yêu cầu vượt quá giá trị tối đa nội bộ, thì giá trị tối đa nội bộ sẽ được sử dụng.

Danh sách công việc có thể bao gồm một mã thông báo để đọc trang kết quả tiếp theo. Để truy xuất trang tiếp theo đó, hãy phát hành lại cùng một yêu cầu cùng với mã thông báo trang. Khi mã thông báo trang được trả về trống, sẽ không có tác vụ nào để truy xuất nữa.

Các trường khi liệt kê việc cần làm

Công cụ quản lý đội xe sẽ loại bỏ các trường sau đây khi liệt kê công việc:

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

Sử dụng các định dạng trường sau đây dựa trên Đề xuất cải tiến API của Google:

Loại trường Định dạng Ví dụ:
Dấu thời gian RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Thời lượng Số giây, theo sau là s task_duration = 120s
Enum Chuỗi state = CLOSED AND type = PICKUP
Vị trí point.latitude và point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Lọc việc cần làm đã liệt kê

Bạn có thể lọc các việc cần làm được liệt kê theo hầu hết các thuộc tính việc cần làm. Để biết cú pháp truy vấn bộ lọc, hãy xem AIP-160. Nếu bạn không chỉ định truy vấn bộ lọc, tất cả công việc sẽ được liệt kê.

Bảng sau đây cho thấy các thuộc tính công việc hợp lệ mà bạn có thể sử dụng để lọc:

Thuộc tính tác vụ để lọc danh sách
  • type
  • attributes
  • tracking_id
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_duration_outcome
  • task_outcome
  • task_outcome_location
  • task_outcome_time

Hãy xem AIP-160 để biết danh sách đầy đủ các toán tử truy vấn bộ lọc.

Ví dụ về việc cần làm dạng danh sách

Ví dụ sau đây cho thấy cách liệt kê các tác vụ cho deliveryVehicleId và thuộc tính tác vụ, cả bằng thư viện gRPC Java và bằng lệnh gọi HTTP REST đến ListTasks.

Một phản hồi thành công vẫn có thể trống. Phản hồi trống cho biết không có tác vụ nào liên kết với deliveryVehicleId đã cung cấp.

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

Để áp dụng bộ lọc cho các tác vụ được liệt kê, hãy thêm tham số URL "filter" (bộ lọc) với giá trị là truy vấn bộ lọc đã thoát URL.

Tiêu đề yêu cầu phải chứa trường Authorization (Uỷ quyền) có giá trị Bearer <token>, trong đó <token> mang vai trò tài khoản dịch vụ chính xác. Xem Vai trò của tài khoản dịch vụ.

Một lượt tra cứu thành công sẽ cung cấp nội dung phản hồi có cấu trúc sau:

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

Ví dụ về lệnh 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}"

Bước tiếp theo