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

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

• Tìm kiếm nhiệm vụ: Bạn có thể tìm kiếm nhiệm vụ theo các mã nhận dạng sau:

  • Mã nhận dạng nhiệm vụ: được người dùng sử dụng, chẳng hạn như nhân viên vận hành đội xe có quyền truy cập vào chế độ xem đầy đủ về dữ liệu nhiệm vụ.
  • Mã theo dõi: được phần mềm khách hàng của bạn 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 gói hàng dự kiến được giao đến nhà của họ.

  Hãy nhớ phân biệt giữa mã nhận dạng tác vụ và mã nhận dạng theo dõi tác vụ. Hai trường hợp này không phải là một. Xem 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.

• Liệt kê các 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ác tác vụ theo mã nhận dạng tác vụ hoặc mã nhận dạng theo dõi. Phương thức này có các yêu cầu sau:

• Các hoạt động tra cứu theo mã nhận dạng để theo dõi phải tuân thủ các quy tắc hiển thị được nêu trong Quy tắc hiển thị cho các đố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 dịch vụ giao hàng, 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 hàng hoặc người nhận hàng của một lô hàng. Fleet Engine sẽ biên tập tất cả thông tin khác trong các phản hồi. Để biết thêm thông tin về mã thông báo, hãy xem phần 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 việc cần làm theo mã nhận dạng việc cần làm của việc đó trong môi trường máy chủ bằ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.

 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;
 }

    # 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ác việc cần làm theo mã theo dõi

Các ví dụ sau đây minh hoạ cách tra cứu các nhiệm vụ theo mã theo dõi lô hàng bằng cách sử dụng gRPC hoặc lệnh gọi HTTP REST đến GetTaskTrackingInfo.

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;
}

# 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ê các nhiệm vụ

Việc liệt kê các nhiệm vụ yêu cầu quyền truy cập rộng rãi vào các nhiệm vụ. Tính năng liệt kê các việc cần làm chỉ dành cho người dùng đáng tin cậy. Sử dụng mã thông báo xác thực Delivery Fleet Reader hoặc Delivery Admin khi đưa ra các yêu cầu về danh sách việc cần làm. 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 liệt kê việc cần làm. Nếu bạn chỉ định kích thước trang, 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, hệ thống 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 nhiệm vụ 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ề là mã thông báo trống, sẽ không có thêm nhiệm vụ nào để truy xuất.

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

Fleet Engine sẽ chỉnh sửa các trường sau đây khi liệt kê các việc cần làm:

• 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:

Lọc các việc cần làm trong danh sách

Bạn có thể lọc các việc cần làm trong danh sách theo hầu hết các thuộc tính của 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, thì tất cả các tác vụ sẽ được liệt kê.

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

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ề danh sách việc cần làm

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

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

 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;
 }

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

 # 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

• Quản lý lô hàng