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>
- <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 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>
<tracking_id> 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, giá trị 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 | |
---|---|
|
|
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}"