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

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

  • Tra cứu việc cần làm: Bạn có thể tra cứu việc cần làm theo các mã sau:

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

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

  • Danh sách việc cần làm: quyền truy cập rộng rãi vào các việc cần làm, chỉ dành cho 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. Có các yêu cầu sau:

  • Các lần tra cứu theo mã theo dõi phải tuân thủ các quy tắc hiển thị nêu trong Quy tắc hiển thị cho đố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 tiêu dùng phân phối, bất kỳ lệnh gọi nào trả về chỉ thông tin có liên quan đến người dùng cuối đó, chẳng hạn như người giao hàng hoặc người nhận gói hàng. Fleet Engine loại bỏ tất cả 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 mã thông báo Web JSON.

Tra cứu công việc theo mã công việc

Bạn có thể tra cứu một công việc theo mã công việc của công việc đó trong môi trường máy chủ bằng gRPC hoặc Kiến trúc chuyển trạng thái đại diện (REST) Các ví dụ sau đây minh hoạ cách sử dụng thư viện Java gRPC hoặc một yêu cầu REST đến 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;
 }

Kiến trúc chuyển trạng thái đại diện (REST)

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>

  • &lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ.
  • &lt;taskId&gt; 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 một trường Uỷ quyền có giá trị Mã <token>, trong đó <token> do máy chủ của bạn cấp theo nguyên tắc nêu trong phần Vai trò trong 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ể tác vụ.

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 tác vụ theo mã theo dõi

Các ví dụ sau đây minh hoạ cách tra cứu công việc theo mã theo dõi lô hàng bằng cách sử dụng lệnh gọi gRPC hoặc 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;
}

Kiến trúc chuyển trạng thái đại diện (REST)

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>

  • &lt;tracking_id&gt; là mã theo dõi được liên kết với tác vụ.

  • Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Mã <token>, trong đó <token> chịu dịch vụ chính xác vai trò trong tài khoản. Xem bài viết Vai trò trong 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 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

Công việc trong trang thông tin yêu cầu quyền truy cập rộng rãi vào công việc. Tác vụ trang thông tin chỉ dành cho người dùng đáng tin cậy. Sử dụng mã thông báo xác thực của Trình đọc nhóm phân phối hoặc Quản trị viên phân phối khi đưa ra yêu cầu tác vụ đối với danh sách. Xem bài viết Các vai trò trong tài khoản dịch vụ để tìm hiểu thêm của bạn.

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 yêu cầu tác vụ danh sách. Nếu chỉ định kích thước trang, số lượng tác vụ được trả về sẽ không lớn hơn so với kích thước trang được chỉ định. Nếu không có kích thước trang thì đặt mặc định hợp lý sẽ được sử dụng. 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 việc cần làm có thể chứa mã thông báo để đọc trang kết quả tiếp theo. Người nhận truy xuất trang tiếp theo đó, hãy gửi lại yêu cầu tương tự 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ó thêm tác vụ nào nữa truy xuất.

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

Fleet Engine sẽ loại bỏ các trường sau đây khi liệt kê các nhiệm vụ:

  • 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 thiệ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 các việc cần làm được liệt kê

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

Bảng sau đây trình bày các thuộc tính công việc hợp lệ mà bạn có thể 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.

Liệt kê ví dụ về tác vụ

Ví dụ sau đây trình bày cách liệt kê các tác vụ cho deliveryVehicleId và tác vụ, cả với thư viện Java gRPC và với lệnh gọi REST HTTP tới 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 tác vụ 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;
 }

Kiến trúc chuyển trạng thái đại diện (REST)

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks

Để áp dụng bộ lọc cho những việc cần làm trong danh sách, hãy thêm "bộ lọc" Tham số URL có truy vấn bộ lọc thoát URL làm giá trị.

Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Mã <token>, trong đó <token> chịu dịch vụ chính xác vai trò trong tài khoản. Xem bài viết Vai trò trong tài khoản dịch vụ.

Nếu quá trình tra cứu thành công, nội dung phản hồi sẽ có cấu trúc như 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}"

Các bước tiếp theo