Lập mô hình các hoạt động trong nhóm thiết bị của bạn cho lượt phân phối đầu tiên và chặng cuối cùng bằng Fleet Engine Deliveries API. Bạn có thể sử dụng API này bằng cách dùng SDK trình điều khiển cho Android và iOS hoặc trực tiếp bằng cách sử dụng lệnh gọi HTTP REST hoặc gRPC.
Thiết lập ban đầu
Bạn có thể định cấu hình Fleet Engine Deliveries API trong Google Cloud Console.
Để biết thông tin về các bước cần thực hiện trong bảng điều khiển cũng như cách tạo Mã thông báo web JSON để uỷ quyền, hãy xem phần Xác thực và uỷ quyền.
Để biết thông tin chi tiết về cách sử dụng bảng điều khiển, vui lòng xem Tài liệu về Google Cloud Console.
Xác minh thông tin thiết lập của bạn
Sau khi tạo tài khoản dịch vụ, hãy xác minh rằng bạn đã thiết lập xong và bạn có thể tạo xe giao hàng. Việc xác minh chế độ thiết lập ngay lập tức đảm bảo rằng bạn đã giải quyết các vấn đề về uỷ quyền thường gặp có thể phát sinh khi thiết lập dự án. Có 2 cách để xác minh chế độ thiết lập của bạn:
Kiểm thử hai phần quan trọng trong quá trình thiết lập: ký mã thông báo uỷ quyền và tạo phương tiện phân phối bản dùng thử bằng tiện ích dòng lệnh
gcloud. Để biết thông tin chi tiết, hãy xem hướng dẫn Xác minh chế độ thiết lập của bạn.Kiểm tra chế độ thiết lập của bạn bằng Tập lệnh mẫu xác thực của Fleet Engine.
Thư viện ứng dụng
Để có trải nghiệm tốt hơn cho nhà phát triển so với gRPC hoặc REST thô, hãy sử dụng thư viện ứng dụng bằng một số ngôn ngữ lập trình phổ biến. Để biết hướng dẫn về cách tải thư viện ứng dụng cho ứng dụng máy chủ, hãy xem phần Thư viện ứng dụng.
Các ví dụ về Java trong tài liệu này giả định rằng bạn đã quen thuộc với gRPC.
Cấu trúc dữ liệu
API Fleet Engine Deliveries sử dụng 2 cấu trúc dữ liệu để lập mô hình việc lấy hàng và giao hàng:
- Phương tiện giao hàng dùng để vận chuyển gói hàng.
- Các nhiệm vụ đến lấy hàng và giao hàng.
Bạn cũng sử dụng các tác vụ để lập mô hình thời gian nghỉ của người lái xe và các lần dừng theo lịch trong suốt cả ngày.
Xe giao hàng
Xe giao hàng vận chuyển các gói hàng từ một kho đến một vị trí giao hàng và từ một vị trí đón đến kho. Trong một số trường hợp, họ cũng có thể vận chuyển lô hàng trực tiếp từ vị trí đến lấy hàng đến vị trí giao hàng.
Sử dụng SDK Driver để tạo một đối tượng DeliveryVehicle trong Fleet Engine và gửi thông tin cập nhật về vị trí để giao hàng và theo dõi đội xe.
DeliveryVehicle.
Tasks
Đối với những hành động mà xe thực hiện trong ngày, bạn sẽ chỉ định nhiệm vụ theo loại hành động:
- Đối với dịch vụ đến lấy hàng và giao hàng, hãy chỉ định Nhiệm vụ vận chuyển.
- Đối với những thời điểm người lái xe không thể rảnh, như giờ nghỉ bắt buộc, hãy chỉ định Nhiệm vụ không có mặt.
- Đối với các nhiệm vụ không phải lái xe tại hòm thư hoặc tại vị trí của khách hàng, hãy giao Nhiệm vụ dừng xe đã lên lịch.
Mỗi công việc bạn giao phải có một mã công việc duy nhất, nhưng các công việc có thể dùng chung một mã theo dõi. Khi tính toán khoảng thời gian đến dự kiến cho từng nhiệm vụ, Fleet Engine sẽ sử dụng tất cả các nhiệm vụ và thứ tự lên lịch để ước tính các nhiệm vụ đó. Để biết thêm thông tin về mã tác vụ, hãy xem Nguyên tắc đối với mã tác vụ.
Để tạo việc cần làm trong Fleet Engine, hãy dùng Trình quản lý tác vụ của SDK Driver.
Nhiệm vụ vận chuyển
Tạo các tác vụ vận chuyển cho cả việc đến lấy hàng và giao hàng, đồng thời cung cấp những thông tin sau:
- Vị trí đến lấy hàng hoặc giao hàng.
- Số theo dõi hoặc mã nhận dạng.
- Thời gian dừng để tính đến thời gian bổ sung để hoàn thành nhiệm vụ, tìm chỗ đỗ xe hoặc đi bộ đến vị trí bàn giao.
- Mã công việc duy nhất. Xem Nguyên tắc về mã việc cần làm.
Để biết thêm thông tin, hãy xem các chủ đề sau:
Android
iOS
Tác vụ về tình trạng không có sẵn
Tác vụ về tình trạng không có hàng bao gồm những khoảng thời gian xe không đến lấy hàng hoặc giao hàng, chẳng hạn như giờ nghỉ để đổ nhiên liệu cho xe hoặc khoảng thời gian nghỉ ngơi của người lái.
Tạo tác vụ không có sẵn với thông tin sau:
- Thời lượng của điểm chèn quảng cáo.
- Bạn cũng có thể chọn vị trí của điểm chèn quảng cáo. Bạn không cần phải cung cấp vị trí cụ thể, nhưng việc cung cấp sẽ cung cấp khoảng thời gian đến dự kiến chính xác hơn trong suốt cả ngày.
Để biết thêm thông tin, hãy xem các chủ đề sau:
Android
iOS
Việc cần làm cho điểm dừng đã lên lịch
Tạo nhiệm vụ dừng theo lịch để lập mô hình các điểm dừng mà xe giao hàng cần thực hiện. Ví dụ: tạo tác vụ dừng theo lịch cho một lượt dừng thu thập theo lịch hằng ngày tại một vị trí cụ thể, độc lập với các hoạt động phân phối hoặc đến lấy hàng khác tại cùng một vị trí. Bạn cũng có thể tạo tác vụ dừng theo lịch cho các bộ sưu tập từ hộp thả xuống hoặc để lập mô hình chuyển xe trung chuyển hoặc dừng tại trung tâm dịch vụ và điểm dịch vụ.
Để biết thêm thông tin, hãy xem các chủ đề sau:
Android
iOS
Nguyên tắc đối với mã việc cần làm
Khi bạn tạo mã công việc, hãy làm theo các nguyên tắc về nội dung và định dạng sau đây:
- Tạo mã công việc duy nhất
- Đừng tiết lộ bất kỳ thông tin nhận dạng cá nhân (PII) hoặc dữ liệu văn bản rõ ràng nào.
- Sử dụng chuỗi Unicode hợp lệ.
- Chỉ được dùng tối đa 64 ký tự.
- Đừng thêm bất kỳ ký tự ASCII nào sau đây: "/", ":", "\", "?", hoặc "#".
- Chuẩn hoá theo Biểu mẫu chuẩn hoá Unicode C.
Sau đây là một số ví dụ về mã việc cần làm phù hợp:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
Bảng sau đây trình bày ví dụ về mã việc cần làm không được hỗ trợ:
| Mã việc cần làm không được hỗ trợ | Lý do |
|---|---|
| 8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | Vi phạm các yêu cầu về PII (Thông tin nhận dạng cá nhân) và ký tự: dấu phẩy, dấu chấm, dấu hai chấm và dấu gạch chéo. |
| JohnDoe-577b484da26f-Cupertino-SantaCruz | Vi phạm các yêu cầu về Thông tin nhận dạng cá nhân (PII). |
| 4R0oXLToF"112 Mùa hè Tiến sĩ East Hartford, CT06118"577b484da26f8a | Vi phạm các yêu cầu về PII (Thông tin nhận dạng cá nhân) và ký tự: khoảng trắng, dấu phẩy và dấu ngoặc kép. Dài hơn 64 ký tự. |
Tài nguyên khác
Để xem các trường cụ thể có trong từng cấu trúc dữ liệu, hãy xem Tài liệu tham khảo API cho DeliveryVehicle (gRPC, REST) và Task (gRPC, REST).
Vòng đời của một chiếc xe
Đối tượng DeliveryVehicle đại diện cho xe giao hàng đầu tiên hoặc dặm cuối.
Bạn tạo đối tượng DeliveryVehicle bằng:
- Mã dự án của dự án trên Google Cloud chứa tài khoản dịch vụ dùng để gọi các API Fleet Engine.
- Mã xe do khách hàng sở hữu.
Sử dụng mã xe riêng biệt cho từng chiếc xe. Đừng sử dụng lại mã xe trừ phi không có nhiệm vụ nào đang hoạt động cho xe ban đầu.
Fleet Engine tự động xoá các đối tượng DeliveryVehicle chưa được cập nhật bằng UpdateDeliveryVehicle sau 7 ngày. Để xem xe có tồn tại hay không:
- Gọi đến số
UpdateDeliveryVehicle. - Nếu bạn gặp lỗi NOT_FOUND, hãy gọi
CreateDeliveryVehicleđể tạo lại xe. Nếu cuộc gọi trả về một chiếc xe, thì xe vẫn có sẵn để cập nhật.
Thuộc tính xe
Thực thể DeliveryVehicle chứa trường lặp lại của DeliveryVehicleAttribute. API ListDeliveryVehicles bao gồm một trường filter có thể giới hạn các thực thể DeliveryVehicle được trả về ở những thực thể có thuộc tính được chỉ định. DeliveryVehicleAttribute không ảnh hưởng đến hành vi định tuyến của Fleet Engine.
Đừng thêm thông tin nhận dạng cá nhân (PII) hoặc thông tin nhạy cảm vào các thuộc tính vì trường này có thể hiển thị với người dùng.
Vòng đời của một nhiệm vụ
Bạn có thể tạo, cập nhật và truy vấn các tác vụ trong Fleet Engine bằng giao diện gRPC hoặc REST của API Phân phối.
Đối tượng Task có trường trạng thái để theo dõi tiến trình trong vòng đời của đối tượng. Các giá trị sẽ chuyển từ trạng thái MỞ sang ĐÓNG CỬA. Các tác vụ mới sẽ được tạo ở trạng thái MỞ cho biết rằng:
- Nhiệm vụ này chưa được giao cho xe giao hàng.
- Xe giao hàng chưa qua điểm dừng xe được chỉ định của nhiệm vụ.
Nguyên tắc về việc cần làm
Bạn chỉ có thể giao nhiệm vụ cho xe khi xe ở trạng thái MỞ.
Bạn huỷ một nhiệm vụ bằng cách xoá nhiệm vụ đó khỏi danh sách điểm dừng xe, thao tác này sẽ tự động đặt trạng thái của nhiệm vụ thành ĐÃ ĐÓNG CỬA.
Khi xe của nhiệm vụ hoàn tất tại điểm dừng của nhiệm vụ:
Cập nhật trường kết quả của tác vụ thành SUCCEEDED (ĐÃ THÀNH CÔNG) hoặc FAILED (KHÔNG THÀNH CÔNG).
Chỉ định dấu thời gian của sự kiện.
Sau đó, thư viện Theo dõi nhóm JavaScript sẽ cho biết kết quả của tác vụ và trạng thái tác vụ sẽ tự động được đặt thành ĐÃ ĐÓNG CỬA. Để biết thêm thông tin, hãy xem bài viết Theo dõi nhóm thiết bị bằng thư viện Theo dõi nhóm JavaScript.
Tương tự như phương tiện di chuyển, Fleet Engine sẽ xoá các tác vụ chưa được cập nhật sau 7 ngày. Nếu bạn cố gắng tạo một tác vụ có mã nhận dạng đã tồn tại, thì một lỗi sẽ được trả về.
Lưu ý: Fleet Engine không hỗ trợ việc xoá một nhiệm vụ một cách rõ ràng. Dịch vụ sẽ tự động xoá các tác vụ sau 7 ngày mà không cập nhật. Nếu muốn lưu giữ dữ liệu tác vụ lâu hơn 7 ngày, bạn phải tự triển khai chức năng đó.
Thuộc tính của việc cần làm
Thực thể Task chứa trường lặp lại của TaskAttribute. Trường này có thể có giá trị từ một trong 3 loại: chuỗi, số và bool. API ListTasks bao gồm một trường filter có thể giới hạn các thực thể Task được trả về ở những thực thể có các thuộc tính được chỉ định. Các thuộc tính tác vụ không ảnh hưởng đến hành vi định tuyến của Fleet Engine.
Đừng đưa thông tin nhận dạng cá nhân (PII) hoặc các thông tin nhạy cảm khác vào trong các thuộc tính vì người dùng có thể nhìn thấy các thuộc tính này.
Quản lý vòng đời công việc và xe
Lời nhắc: Hệ thống nội bộ đóng vai trò là nguồn dữ liệu đáng tin cậy mà API Fleet Engine Deliveries thay mặt bạn tăng cường.
Để quản lý vòng đời của xe và nhiệm vụ trong hệ thống, hãy sử dụng Fleet Engine Deliveries API để tạo, cập nhật và theo dõi xe của bạn cũng như các nhiệm vụ liên quan.
Đồng thời, ứng dụng trình điều khiển sẽ giao tiếp trực tiếp với Fleet Engine để cập nhật thông tin về tuyến đường và vị trí của thiết bị. Mô hình này cho phép Fleet Engine quản lý hiệu quả thông tin vị trí theo thời gian thực. Công cụ này sẽ gửi trực tiếp vị trí đến thư viện theo dõi. Sau đó, bạn có thể sử dụng thư viện này để cập nhật trạng thái đơn đặt hàng của họ cho người tiêu dùng.
Ví dụ: giả sử bạn có trường hợp sau:
- Một tài xế gần trạm giao hàng. Ứng dụng trình điều khiển sẽ gửi thông tin vị trí của ứng dụng đến Fleet Engine.
- Fleet Engine gửi thông tin vị trí của thiết bị đến thư viện theo dõi. Thư viện này sẽ được ứng dụng cho người dùng thông báo để cảnh báo cho người tiêu dùng về khoảng cách của gói hàng.
- Sau khi tài xế hoàn tất quá trình vận chuyển, họ nhấp vào nút "Đã giao lô hàng" trên ứng dụng dành cho tài xế.
- Hành động "Lô hàng đã giao" sẽ gửi thông tin đến hệ thống phụ trợ của bạn. Hệ thống này sẽ thực hiện các bước xác thực và xác minh kinh doanh cần thiết.
- Hệ thống của bạn xác nhận tác vụ là SUCCEEDED và cập nhật Fleet Engine bằng API Phân phối.
Biểu đồ dưới đây minh hoạ các quy trình này ở mức độ chung. Biểu đồ này cũng cho thấy mối quan hệ tiêu chuẩn giữa hệ thống của bạn, ứng dụng và Fleet Engine.
Quản lý mã thông báo của khách hàng
Thông tin cập nhật vị trí bắt nguồn từ ứng dụng của người lái xe và được gửi trực tiếp đến Fleet Engine cần phải có mã thông báo uỷ quyền. Sau đây là phương pháp đề xuất để xử lý các bản cập nhật từ ứng dụng khách lên Fleet Engine:
Tạo mã thông báo bằng vai trò tài khoản dịch vụ Fleet Engine Delivery Untrust Driver User (Người dùng trình điều khiển không tin cậy).
Cung cấp cho ứng dụng trình điều khiển một mã thông báo có phạm vi giới hạn. Phạm vi này chỉ cho phép cập nhật vị trí thiết bị trong Fleet Engine.
Phương pháp này đảm bảo rằng các lệnh gọi bắt nguồn từ một thiết bị di động (được coi là môi trường có độ tin cậy thấp) tuân thủ nguyên tắc về đặc quyền tối thiểu.
Các vai trò khác trong tài khoản dịch vụ
Thay vào đó, nếu bạn muốn cho phép các ứng dụng trình điều khiển cập nhật trực tiếp Fleet Engine, ngoài những vai trò chỉ dành cho vai trò Người lái xe không tin cậy, chẳng hạn như đối với một số cập nhật tác vụ, bạn có thể sử dụng vai trò Người lái xe đáng tin cậy. Để biết thông tin về mô hình sử dụng vai trò Trình điều khiển đáng tin cậy, hãy xem mô hình Trình điều khiển đáng tin cậy.
Để biết thêm thông tin về cách sử dụng vai trò của người lái xe không đáng tin cậy và không đáng tin cậy, hãy xem bài viết Thiết lập dự án trên đám mây.
Lập mô hình một ngày làm việc
Bảng sau đây mô tả một ngày làm việc của các tài xế tuyến đầu hoặc tuyến cuối có thể trông như thế nào tại một công ty giao hàng và kho vận. Các chi tiết có thể khác nhau giữa công ty của bạn, nhưng bạn có thể xem cách lập mô hình cho một ngày làm việc.
| Thời gian | Hoạt động | Lập mô hình |
|---|---|---|
| Trong vòng 24 giờ kể từ đầu ngày | Điều phối viên chỉ định việc vận chuyển cho xe hoặc tuyến giao hàng. | Bạn có thể tạo trước các nhiệm vụ liên quan đến việc giao hàng, đến lấy hàng, nghỉ giải lao và các nhiệm vụ khác trong Fleet Engine. Ví dụ: bạn có thể tạo
nhiệm vụ đến lấy hàng để vận chuyển,
nhiệm vụ giao hàng hoá,
tình trạng không còn hàng được lên lịch hoặc
điểm dừng theo lịch.
Phân công nhiệm vụ cho một chiếc xe sau khi hoàn tất tập hợp các gói giao hàng và thứ tự giao các gói hàng đó. |
| Đầu ngày | Tài xế bắt đầu ngày làm việc tại kho bằng cách đăng nhập vào ứng dụng Driver. | Khởi chạy Delivery Driver API. Tạo xe giao hàng trong Fleet Engine nếu cần. |
| Tài xế xếp các gói hàng lên xe giao hàng, quét các lô hàng. | Nếu bạn không tạo nhiệm vụ giao hàng vận chuyển trước thời hạn, hãy tạo nhiệm vụ giao hàng vận chuyển tại thời điểm quét. | |
| Người lái xe xác nhận thứ tự các tác vụ cần thực hiện. | Nếu không được tạo trước, hãy tạo tác vụ đến lấy hàng để vận chuyển, tình trạng rảnh/bận theo lịch và điểm dừng theo lịch. | |
| Người lái xe rời kho và cam kết số công việc tiếp theo cần hoàn thành. | Giao tất cả nhiệm vụ hoặc một nhóm nhỏ nhiệm vụ cho xe bằng cách cam kết hoàn thành thứ tự. | |
| Tài xế giao hàng. | Sau khi đến điểm giao hàng, hãy thực hiện các thao tác liên quan đến phương tiện đến điểm dừng. Sau khi giao hàng, hãy đóng nhiệm vụ giao hàng và trạng thái vận chuyển của cửa hàng và các siêu thông tin khác (không bắt buộc). Sau khi hoàn thành mọi thao tác tại điểm dừng và trước khi bắt đầu lái xe đến điểm dừng tiếp theo, hãy thực hiện các thao tác liên quan đến việc phương tiện di chuyển hoàn tất một điểm dừng và xe lên đường đến điểm dừng tiếp theo. | |
| Tài xế gặp xe trung chuyển để chuyển các lô hàng khác lên xe giao hàng. | Điểm gặp của hoạt động chuyển giữa đơn vị vận chuyển và xe giao hàng
phải được mô hình hoá dưới dạng điểm dừng theo lịch.
Sau khi chuyển và quét các gói hàng, hãy tạo nhiệm vụ giao hàng nếu bạn chưa tạo nhiệm vụ. Sau đó, hãy cập nhật thứ tự hoàn thành nhiệm vụ bằng cách giao nhiệm vụ cho một chiếc xe và cập nhật thứ tự nhiệm vụ. |
|
| Tài xế nhận được thông báo về yêu cầu đến lấy hàng. | Sau khi chấp nhận yêu cầu đến lấy hàng, hãy tạo một nhiệm vụ đến lấy hàng. Sau đó, hãy cập nhật thứ tự thực thi nhiệm vụ bằng cách giao nhiệm vụ cho một xe và cập nhật thứ tự thực hiện nhiệm vụ. | |
| Trưa | Tài xế nghỉ trưa. | Nếu một vị trí được liên kết với nhiệm vụ không khả dụng, hãy coi vị trí đó giống như mọi nhiệm vụ khác. Thực hiện các hành động liên quan đến việc một chiếc xe
đến điểm dừng,
phương tiện di chuyển hoàn tất một điểm dừng
và xe đang lên đường đến điểm dừng tiếp theo.
Nếu không, bạn không cần làm gì thêm cho đến khi điểm chèn quảng cáo kết thúc. Xoá việc cần làm bằng cách xác nhận các việc cần làm tiếp theo và còn lại, rồi cập nhật thứ tự của các nhiệm vụ. |
| Tài xế nhận một kiện hàng. | Mô hình này được lập mô hình giống như một điểm giao hàng. Thực hiện các thao tác liên quan đến xe đến điểm dừng và đóng nhiệm vụ, cũng như trạng thái lưu trữ đang lưu trữ và các siêu thông tin khác (không bắt buộc). Sau khi hoàn thành mọi thao tác tại điểm dừng và trước khi bắt đầu lái xe đến điểm dừng tiếp theo, hãy thực hiện các thao tác liên quan đến việc xe hoàn tất điểm dừng và xe lên đường đến điểm dừng tiếp theo. Lưu ý: Để đảm bảo việc thanh toán chính xác, tất cả các đơn đến lấy hàng phải có nhiệm vụ giao hàng tương ứng. Nếu đơn hàng đến lấy hàng được giao đến một vị trí khác trên cùng tuyến đường của tài xế trong ngày hôm đó, bạn nên lập mô hình tác vụ giao hàng đó như mọi nhiệm vụ giao hàng khác trên tuyến đường đó. Nếu người lái xe đưa sản phẩm đến lấy hàng trở lại kho hàng, bạn nên tạo một nhiệm vụ giao hàng tại điểm đến kho hàng. | |
| Tài xế dừng lại theo lịch để lấy hàng từ một thùng hàng. | Mô hình này được lập mô hình giống như mọi điểm dừng nhận hàng khác. Thực hiện các thao tác liên quan đến xe đến điểm dừng và đóng một tác vụ. Sau khi hoàn thành mọi thao tác tại điểm dừng và bắt đầu lái xe đến điểm dừng tiếp theo, hãy thực hiện các thao tác liên quan đến việc xe hoàn tất điểm dừng và xe lên đường đến điểm dừng tiếp theo. | |
| Tài xế nhận được thông báo về việc gói hàng đang được chuyển hướng đến một địa điểm khác. | Đặt trạng thái của nhiệm vụ giao hàng vận chuyển ban đầu thành COMPLETED (ĐÃ HOÀN TẤT) rồi tạo nhiệm vụ giao hàng vận chuyển mới cho vị trí giao hàng mới. Để biết thêm thông tin, hãy xem bài viết Định tuyến lại lô hàng. | |
| Tài xế đã cố gắng giao một gói hàng nhưng không được. | Quá trình này được lập mô hình tương tự như một điểm dừng phân phối thành công, đánh dấu tác vụ phân phối là đã hoàn tất. Thực hiện các thao tác liên quan đến một chiếc xe đến điểm dừng. Khi không thể giao hàng, hãy đóng nhiệm vụ và trạng thái vận chuyển của cửa hàng và các siêu thông tin khác (không bắt buộc). Sau khi hoàn thành mọi thao tác tại điểm dừng và trước khi bắt đầu lái xe đến điểm dừng tiếp theo, hãy thực hiện các thao tác liên quan đến việc xe hoàn tất điểm dừng và xe lên đường đến điểm dừng tiếp theo. | |
| Tài xế đã được thông báo để tạm giữ (không giao) một kiện hàng. | Sau khi nhận được và xác nhận thông báo, hãy đặt trạng thái của nhiệm vụ thành COMPLETED. | |
| Tài xế đã nhận được thông báo giao một lô hàng nhất định, điều này đã thay đổi đơn đặt hàng đã cam kết. | Cập nhật thứ tự tác vụ. | |
| Tài xế chọn giao một lô hàng không đúng thứ tự. | Cập nhật thứ tự tác vụ rồi tiến hành như bình thường. | |
| Tài xế giao nhiều kiện hàng đến một địa điểm duy nhất. | Mô hình này được lập mô hình tương tự như một trạm giao hàng duy nhất. Sau khi đến điểm dừng, hãy thực hiện các thao tác liên quan đến một xe đang đến điểm dừng. Sau khi phân phối mỗi lô hàng, hãy đóng từng nhiệm vụ và trạng thái vận chuyển của cửa hàng và các siêu thông tin khác (không bắt buộc). Sau khi hoàn thành mọi thao tác tại điểm dừng và trước khi bắt đầu lái xe đến điểm dừng tiếp theo, hãy thực hiện các thao tác liên quan đến việc xe hoàn tất điểm dừng và xe lên đường đến điểm dừng tiếp theo. | |
| Cuối ngày | Tài xế quay trở lại kho. | Nếu người lái xe quay lại kho hàng để vận chuyển các gói hàng đã được lấy trong lộ trình của họ, thì bạn cũng phải tạo và đóng từng gói hàng dưới dạng tác vụ giao hàng để đảm bảo việc thanh toán chính xác. Bạn có thể thực hiện việc này bằng cách lập mô hình kho hàng như bất kỳ điểm giao hàng nào khác. Nếu kho hàng không được dùng làm điểm dừng giao hàng, bạn vẫn có thể tuỳ ý lập mô hình kho hàng như một điểm dừng theo lịch. Việc lập mô hình điểm dừng giúp tài xế biết được tuyến đường quay lại kho hàng và biết được thời gian dự kiến đến kho hàng. |
Cách hoạt động của tính năng cập nhật vị trí
Để Fleet Engine đạt được hiệu suất tốt nhất, hãy cung cấp cho công cụ này một luồng thông tin cập nhật vị trí của xe. Bạn có thể sử dụng một trong các cách sau để cung cấp các thông tin cập nhật này:
- Sử dụng SDK Trình điều khiển – Android, iOS -- lựa chọn đơn giản nhất.
- Sử dụng mã tuỳ chỉnh – hữu ích nếu các vị trí được chuyển tiếp thông qua phần phụ trợ, hoặc nếu bạn sử dụng các thiết bị không phải Android hoặc iOS.
Bất kể bạn cung cấp thông tin cập nhật về vị trí của xe bằng cách nào, phần phụ trợ của bạn vẫn chịu trách nhiệm cập nhật Fleet Engine khi một xe giao hàng đang đến một điểm dừng (bao gồm cả kho hàng) và khi xe đến một điểm dừng. Fleet Engine không tự động phát hiện các sự kiện này.
Trạm dừng xe và địa điểm giao hàng
Trạm dừng xe là nơi xe giao hàng hoàn thành một nhiệm vụ vận chuyển hoặc một số nhiệm vụ khác. Đó có thể là một điểm truy cập, chẳng hạn như bãi bốc hàng hoặc vị trí bị bám vào đường.
Địa điểm giao hàng là địa điểm giao hàng hoặc đến lấy hàng. Bạn có thể phải đi bộ một chút từ trạm xe để đi và đến địa điểm giao hàng.
Ví dụ: khi người lái xe đang giao hàng đến một cửa hàng trong một trung tâm mua sắm, xe giao hàng sẽ dừng trong bãi đỗ xe của trung tâm mua sắm gần lối vào gần cửa hàng nhất. Đây là trạm dừng xe. Sau đó, người lái xe đi bộ từ trạm xe đến vị trí trong trung tâm mua sắm có cửa hàng. Đây là vị trí giao hàng.
Để người dùng có trải nghiệm theo dõi tốt nhất, hãy cân nhắc cách chỉ định nhiệm vụ vận chuyển cho trạm xe và lưu ý rằng số lượng trạm xe còn lại để thực hiện nhiệm vụ vận chuyển sẽ được báo cáo cho người dùng để giúp họ xem tiến trình vận chuyển.
Ví dụ: nếu người lái xe đang giao hàng nhiều lần đến một toà nhà văn phòng, hãy cân nhắc việc chỉ định tất cả nhiệm vụ giao hàng cho một điểm dừng xe. Nếu mỗi nhiệm vụ giao hàng được chỉ định cho một điểm dừng xe riêng, thì trải nghiệm theo dõi lô hàng của bạn sẽ không mấy hữu ích cho người dùng vì tính năng theo dõi chỉ dùng được khi xe ở một số điểm dừng nhất định trước điểm đến. Việc có nhiều điểm dừng xe hoàn tất trong một thời gian ngắn sẽ khiến người dùng không có nhiều thời gian để theo dõi tiến trình giao hàng.
Sử dụng SDK di động
Trước khi thực hiện lệnh gọi đến SDK Trình điều khiển, hãy nhớ khởi chạy SDK đó.
Khởi chạy Delivery Driver API
Trước khi khởi chạy API Trình điều khiển phân phối trong SDK Trình điều khiển, hãy nhớ khởi động SDK điều hướng. Sau đó, hãy khởi chạy Delivery Driver API như minh hoạ trong ví dụ sau:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
Trường hợp sử dụng
Phần này mô tả cách sử dụng API Phân phối để lập mô hình các trường hợp sử dụng phổ biến.
Giá trị nhận dạng thực thể duy nhất
Định dạng và giá trị của giá trị nhận dạng thực thể duy nhất dùng trong các lệnh gọi REST chưa được rõ ràng đối với Fleet Engine. Tránh sử dụng mã nhận dạng tự động tăng và đảm bảo rằng giá trị nhận dạng không chứa bất kỳ thông tin nhận dạng cá nhân (PII), chẳng hạn như số điện thoại của người lái xe.
Tạo phương tiện di chuyển
Bạn có thể tạo xe từ SDK trình điều khiển hoặc từ môi trường máy chủ bằng gRPC hoặc REST.
gRPC
Để tạo xe mới, bạn hãy gọi CreateDeliveryVehicle đến Fleet Engine.
Sử dụng đối tượng CreateDeliveryVehicleRequest để xác định các thuộc tính của xe giao hàng mới. Lưu ý rằng mọi giá trị được chỉ định cho trường Name sẽ bị bỏ qua theo hướng dẫn API đối với mã nhận dạng do người dùng chỉ định.
Bạn nên sử dụng trường DeliveryVehicleId để đặt mã nhận dạng xe.
Khi tạo DeliveryVehicle, bạn có thể tuỳ ý chỉ định các trường sau:
- Thuộc tính
- LastLocation
- Loại
Không đặt bất kỳ trường nào khác. Nếu bạn làm như vậy, Fleet Engine sẽ trả về lỗi vì các trường đó đang ở chế độ chỉ đọc hoặc chỉ có thể được cập nhật bằng lệnh gọi đến UpdateDeliveryVehicle.
Để tạo xe mà không cần thiết lập các trường không bắt buộc, bạn có thể không đặt trường DeliveryVehicle trong CreateDeliveryVehicleRequest.
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo xe:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Kiến trúc chuyển trạng thái đại diện (REST)
Để tạo xe từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến CreateDeliveryVehicle:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> là giá trị nhận dạng duy nhất của xe giao hàng trong hệ thống thiết bị của bạn.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung POST đại diện cho thực thể DeliveryVehicle sẽ được tạo. Bạn có thể chỉ định các trường không bắt buộc sau đây:
- attributes
- lastLocation
- loại
Ví dụ về lệnh curl:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"attributes": [{"key": "model", "value": "sedan"}],
"lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM
Fleet Engine bỏ qua trường name của thực thể DeliveryVehicle theo hướng dẫn của API đối với mã nhận dạng do người dùng chỉ định.
Không đặt bất kỳ trường nào khác. Nếu bạn làm như vậy, Fleet Engine sẽ trả về lỗi vì các trường đó đang ở chế độ chỉ đọc hoặc chỉ có thể được cập nhật bằng cách sử dụng lệnh gọi đến UpdateDeliveryVehicle.
Để tạo xe mà không thiết lập trường nào, hãy để trống phần nội dung của yêu cầu POST. Sau đó, chiếc xe mới tạo sẽ trích xuất mã xe từ tham số deliveryVehicleId trong URL POST.
Ví dụ về lệnh curl:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}"
Tạo nhiệm vụ đến lấy hàng để vận chuyển
Bạn có thể tạo tác vụ đến lấy hàng vận chuyển từ Driver SDK hoặc từ môi trường máy chủ bằng gRPC hoặc REST.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo một nhiệm vụ đến lấy hàng để vận chuyển:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Kiến trúc chuyển trạng thái đại diện (REST)
Để tạo tác vụ đến lấy hàng vận chuyển từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> là giá trị nhận dạng duy nhất của tác vụ. Đây không được là số vận đơn cho lô hàng. Nếu không có mã công việc trong hệ thống, bạn có thể tạo một giá trị nhận dạng duy nhất trên toàn cầu (UUID).
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể Task:
Các trường bắt buộc:
Kỹ thuật Giá trị loại Type.PICKUP state State.OPEN trackingId Số điện thoại hoặc mã nhận dạng bạn đang dùng để theo dõi quá trình vận chuyển. plannedLocation Là vị trí nơi hoàn thành công việc, trong trường hợp này là vị trí đến lấy hàng. taskDuration Thời gian dự kiến (tính bằng giây) để lấy hàng tại vị trí đến lấy hàng. Các trường không bắt buộc:
Kỹ thuật Giá trị targetTimeWindow Khoảng thời gian hoàn thành tác vụ. Điều này không ảnh hưởng đến hoạt động định tuyến. attributes Danh sách các thuộc tính tuỳ chỉnh của Tác vụ. Mỗi thuộc tính phải có một khoá duy nhất.
Tất cả các trường khác trong thực thể đều bị bỏ qua khi tạo. Fleet Engine sẽ gửi ra một trường hợp ngoại lệ nếu yêu cầu bao gồm một deliveryVehicleId được chỉ định. Bạn giao việc cần làm bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Giao nhiệm vụ cho một chiếc xe và UpdateDeliveryVehicleRequest.
Ví dụ về lệnh curl:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Tạo nhiệm vụ giao hàng
Tạo tác vụ phân phối hàng vận chuyển từ Driver SDK hoặc từ môi trường máy chủ bằng gRPC hoặc REST.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo một tác vụ giao hàng:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Kiến trúc chuyển trạng thái đại diện (REST)
Để tạo tác vụ phân phối hàng vận chuyển từ môi trường máy chủ bằng gRPC hoặc REST, hãy thực hiện lệnh gọi HTTP REST đến CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> là giá trị nhận dạng duy nhất của tác vụ. Đây không được là số vận đơn cho lô hàng. Nếu không có mã công việc trong hệ thống, bạn có thể tạo một giá trị nhận dạng duy nhất trên toàn cầu (UUID).
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể Task:
Các trường bắt buộc:
Kỹ thuật Giá trị loại Type.DELIVERY state State.OPEN trackingId Số điện thoại hoặc mã nhận dạng bạn đang dùng để theo dõi quá trình vận chuyển. plannedLocation Địa điểm nơi công việc cần được hoàn thành, trong trường hợp này là địa điểm giao hàng của lô hàng này. taskDuration Thời gian dự kiến tính bằng giây để giao hàng tại địa điểm giao hàng. Các trường không bắt buộc:
Kỹ thuật Giá trị targetTimeWindow Khoảng thời gian hoàn thành tác vụ. Điều này không ảnh hưởng đến hoạt động định tuyến. attributes Danh sách các thuộc tính tuỳ chỉnh của Tác vụ. Mỗi thuộc tính phải có một khoá duy nhất.
Tất cả các trường khác trong thực thể đều bị bỏ qua khi tạo. Fleet Engine sẽ gửi ra một trường hợp ngoại lệ nếu yêu cầu bao gồm một deliveryvehicleId được chỉ định. Bạn giao việc cần làm bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Giao nhiệm vụ cho một chiếc xe và UpdateDeliveryVehicleRequest.
Ví dụ về lệnh curl:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Tạo hàng loạt tác vụ
Bạn có thể tạo một loạt tác vụ từ môi trường máy chủ bằng gRPC hoặc REST.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo hai tác vụ: một tác vụ để giao hàng và một tác vụ để đến lấy hàng tại cùng một vị trí:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Delivery Task settings
Task deliveryTask = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("delivery-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header or parent fields
.setTaskId("task-8312508") // Task ID assigned by the Provider
.setTask(deliveryTask) // Initial state
.build();
// Pickup Task settings
Task pickupTask = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("pickup-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header or parent fields
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(pickupTask) // Initial state
.build();
// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;
// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
BatchCreateTasksRequest.newBuilder()
.setParent(parent)
.addRequests(createDeliveryTaskRequest)
.addRequests(createPickupTaskRequest)
.build();
// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.
try {
BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Kiến trúc chuyển trạng thái đại diện (REST)
Để tạo tác vụ phân phối và lấy hàng từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến BatchCreateTasks:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể BatchCreateTasksRequest:
Các trường bắt buộc:
Kỹ thuật Giá trị yêu cầu Mảng< CreateTasksRequest>Các trường không bắt buộc:
Kỹ thuật Giá trị tiêu đề " DeliveryRequestHeader"
Mỗi phần tử CreateTasksRequest trong requests phải chuyển cùng một quy tắc xác thực như yêu cầu CreateTask, ngoại trừ trường parent và header là không bắt buộc. Nếu được đặt, các trường này phải giống với các trường tương ứng ở BatchCreateTasksRequest cấp cao nhất. Xem bài viết tạo tác vụ đến lấy hàng và tạo tác vụ giao hàng để biết các quy tắc xác thực cụ thể cho từng tác vụ.
Để biết thêm thông tin, hãy xem tài liệu Tham khảo API cho BatchCreateTasks (gRPC, REST).
Ví dụ về lệnh curl:
# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"requests" : [
{
"taskId": "${DELIVERY_TASK_ID}",
"task" : {
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${DELIVERY_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
},
{
"taskId": "${PICKUP_TASK_ID}",
"task" : {
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${PICKUP_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
}
]
}
EOM
Không thể sử dụng theo lịch
Bạn có thể tạo một tác vụ cho biết tình trạng không hoạt động (ví dụ: đối với khoảng nghỉ của người lái xe hoặc tiếp nhiên liệu) từ SDK trình điều khiển hoặc từ môi trường máy chủ bằng gRPC hoặc REST. Tác vụ không có sẵn đã lên lịch không được bao gồm mã theo dõi. Bạn có thể cung cấp vị trí nếu muốn.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo một tác vụ không có sẵn:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Kiến trúc chuyển trạng thái đại diện (REST)
Để tạo tác vụ không hoạt động từ môi trường máy chủ, hãy thực hiện lệnh gọi REST HTTP đến CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> là giá trị nhận dạng duy nhất của tác vụ. Nếu không có mã tác vụ trong hệ thống, bạn có thể tạo một giá trị nhận dạng duy nhất trên toàn cầu (UUID).
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể Task:
Các trường bắt buộc:
Kỹ thuật Giá trị loại Type.UNAVAILABLE state State.OPEN taskDuration Thời lượng của điểm chèn quảng cáo tính bằng giây. Các trường không bắt buộc:
Kỹ thuật Giá trị plannedLocation Vị trí của điểm chèn quảng cáo nếu phải diễn ra tại một địa điểm cụ thể.
Tất cả các trường khác trong thực thể đều bị bỏ qua khi tạo. Fleet Engine sẽ gửi ra một trường hợp ngoại lệ nếu yêu cầu bao gồm một deliveryvehicleId được chỉ định. Bạn giao việc cần làm bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Giao nhiệm vụ cho một chiếc xe và UpdateDeliveryVehicleRequest.
Ví dụ về lệnh curl:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "UNAVAILABLE",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "300s"
}
EOM
Điểm dừng theo lịch trình
Bạn có thể tạo tác vụ dừng theo lịch từ SDK trình điều khiển hoặc từ một môi trường máy chủ bằng gRPC hoặc REST. Tác vụ dừng theo lịch có thể không có mã theo dõi.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo một tác vụ dừng theo lịch:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Kiến trúc chuyển trạng thái đại diện (REST)
Để tạo tác vụ dừng theo lịch từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> là giá trị nhận dạng duy nhất của tác vụ. Nếu không có mã tác vụ trong hệ thống, bạn có thể tạo một giá trị nhận dạng duy nhất trên toàn cầu (UUID).
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể Task:
Các trường bắt buộc:
Kỹ thuật Giá trị loại Type.SCHEDULED_STOP state State.OPEN plannedLocation Vị trí dừng. taskDuration Thời lượng dự kiến của điểm dừng tính bằng giây. Các trường không bắt buộc:
- Không có
Tất cả các trường khác trong thực thể đều bị bỏ qua khi tạo. Fleet Engine sẽ gửi ra một trường hợp ngoại lệ nếu yêu cầu bao gồm một deliveryvehicleId được chỉ định. Bạn giao việc cần làm bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Giao nhiệm vụ cho một chiếc xe và UpdateDeliveryVehicleRequest.
Ví dụ về lệnh curl:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "SCHEDULED_STOP",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "600s"
}
EOM
Đặt khoảng thời gian mục tiêu
Khoảng thời gian mục tiêu là TimeWindow mà trong đó tác vụ sẽ được hoàn tất. Ví dụ: nếu thông báo về khoảng thời gian phân phối cho người nhận, bạn có thể sử dụng khoảng thời gian mục tiêu của nhiệm vụ để ghi lại khoảng thời gian này và tạo cảnh báo hoặc phân tích hiệu suất sau chuyến đi bằng trường này.
Khoảng thời gian mục tiêu bao gồm thời gian bắt đầu và thời gian kết thúc, đồng thời có thể được đặt cho bất kỳ loại tác vụ nào. Khoảng thời gian mục tiêu không ảnh hưởng đến hành vi định tuyến.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để đặt khoảng thời gian tác vụ:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} 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)
Để đặt khoảng thời gian cho tác vụ bằng HTTP, hãy gọi UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<id> là giá trị nhận dạng duy nhất của tác vụ.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể Task:
Các trường bắt buộc:
Kỹ thuật Giá trị targetTimeWindow Khoảng thời gian hoàn thành tác vụ. Chế độ cài đặt này không ảnh hưởng đến hoạt động định tuyến Các trường không bắt buộc:
- Không có
Tất cả các trường khác trong thực thể đều bị bỏ qua trong quá trình cập nhật.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Đặt cấu hình chế độ hiển thị của tính năng theo dõi việc cần làm
Bạn có thể kiểm soát khả năng hiển thị dữ liệu trong thư viện Theo dõi vận chuyển và dữ liệu đó được trả về từ lệnh gọi đến GetTaskTrackingInfo theo từng tác vụ bằng cách đặt TaskTrackingViewConfig cho tác vụ đó. Hãy xem phần Các nhiệm vụ về xe đang hoạt động để biết thêm thông tin. Bạn có thể thực hiện việc này khi tạo hoặc cập nhật tác vụ. Sau đây là ví dụ về cách cập nhật tác vụ bằng cấu hình này:
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để thiết lập cấu hình chế độ xem theo dõi công việc:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskTrackingViewConfig(
TaskTrackingViewConfig.newBuilder()
.setRoutePolylinePointsVisibility(
VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
.setEstimatedArrivalTimeVisibility(
VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
.setRemainingStopCountVisibility(
VisibilityOption.newBuilder().setNever(true)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} 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)
Để đặt cửa sổ cấu hình chế độ xem theo dõi công việc bằng HTTP, hãy gọi UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<id> là giá trị nhận dạng duy nhất của tác vụ.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể Task:
Các trường bắt buộc:
Kỹ thuật Giá trị taskTrackingViewConfig Cấu hình để theo dõi công việc chỉ định những phần tử dữ liệu nào sẽ hiển thị cho người dùng cuối trong trường hợp nào. Các trường không bắt buộc:
- Không có
Tất cả các trường khác trong thực thể đều bị bỏ qua trong quá trình cập nhật.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"estimatedArrivalTimeVisibility": {
"remainingDrivingDistanceMetersThreshold": 5000
},
"remainingStopCountVisibility": {
"never": true
}
}
}
EOM
Phân công nhiệm vụ cho xe
Bạn giao nhiệm vụ cho xe giao hàng bằng cách cập nhật thứ tự nhiệm vụ cho chiếc xe đó. Thứ tự tác vụ cho xe được xác định theo danh sách điểm dừng của xe cho xe giao hàng và bạn có thể chỉ định một hoặc nhiều nhiệm vụ cho mỗi điểm dừng xe. Để biết thông tin chi tiết, hãy xem phần Cập nhật thứ tự tác vụ.
Để thay đổi một lô hàng từ xe này sang xe khác, hãy đóng nhiệm vụ ban đầu rồi tạo lại trước khi giao xe mới. Nếu cập nhật tác vụ sắp xếp thứ tự cho một tác vụ đã được giao cho một xe khác, bạn sẽ gặp lỗi.
Cập nhật thứ tự tác vụ
Bạn có thể cập nhật các nhiệm vụ theo thứ tự đã chỉ định cho một chiếc xe thông qua SDK Trình điều khiển hoặc môi trường máy chủ. Không sử dụng cả hai phương thức để tránh điều kiện cuộc đua và duy trì một nguồn đáng tin cậy duy nhất.
Khi bạn cập nhật thứ tự nhiệm vụ cho một chiếc xe, thao tác này cũng sẽ thực hiện những việc sau:
- Phân công các nhiệm vụ mới cho xe.
- Đóng mọi thao tác đã được chỉ định trước đó cho xe, nhưng không có trong thứ tự mới cập nhật.
Để thay đổi một lô hàng từ xe này sang xe khác, hãy đóng nhiệm vụ ban đầu rồi tạo lại trước khi giao cho phương tiện mới. Nếu cập nhật tác vụ sắp xếp thứ tự cho một tác vụ đã được giao cho một xe khác, bạn sẽ gặp lỗi.
Bạn có thể cập nhật thứ tự việc cần làm bất cứ lúc nào.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để cập nhật thứ tự tác vụ cho xe:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.NEW)))
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} 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)
Để cập nhật thứ tự tác vụ cho xe từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> là giá trị nhận dạng duy nhất của xe giao hàng trong đội xe mà bạn dự định cập nhật thứ tự nhiệm vụ. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể DeliveryVehicle:
Các trường bắt buộc:
Kỹ thuật Giá trị remainingVehicleJourneySegments Danh sách phân đoạn hành trình cho các tác vụ theo thứ tự thực thi. Công việc đầu tiên trong danh sách sẽ được thực thi trước. còn lại hành trình xe theo phân đoạn[i].dừng Điểm dừng của tác vụ i trong danh sách. còn lạiXeJourneyPhân đoạn[i].stop.plannedLocation Vị trí đã lên kế hoạch cho điểm dừng. còn lạiXeJourneyPhân đoạn[i].stop.tasks Danh sách những việc cần làm tại trạm xe này. remainingVehicleJourneySegments[i].stop.state State.NEW Các trường không bắt buộc:
- Không có
Tất cả các trường khác trong thực thể đều bị bỏ qua trong quá trình cập nhật.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Xe đang trên đường đến trạm dừng tiếp theo
Fleet Engine phải được thông báo khi xe khởi hành từ điểm dừng hoặc bắt đầu chỉ đường. Bạn có thể thông báo cho Fleet Engine từ Driver SDK hoặc từ một môi trường máy chủ bằng gRPC hoặc REST. Không sử dụng cả hai phương pháp để tránh các điều kiện tranh đấu và để duy trì một nguồn đáng tin cậy duy nhất.
gRPC
Ví dụ sau cho thấy cách sử dụng thư viện Java gRPC để thông báo cho Fleet Engine rằng một chiếc xe đang trên đường đến trạm dừng tiếp theo.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} 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)
Để thông báo cho Fleet Engine rằng một chiếc xe đang trên đường đến điểm dừng tiếp theo từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST tới UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> là giá trị nhận dạng duy nhất của xe giao hàng trong nhóm thiết bị mà bạn dự định cập nhật thứ tự nhiệm vụ. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể DeliveryVehicle:
Trường bắt buộc:
Kỹ thuật Giá trị remainingVehicleJourneySegments Danh sách các điểm dừng xe còn lại, trong đó các tiểu bang được đánh dấu là State.NEW. Điểm dừng đầu tiên trong danh sách phải có trạng thái được đánh dấu là State.ENROUTE. Các trường không bắt buộc:
- Không có
Tất cả các trường khác trong thực thể sẽ bị bỏ qua đối với thông báo.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ENROUTE",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Cập nhật vị trí của xe
Nếu không dùng SDK trình điều khiển để cập nhật vị trí của xe, bạn có thể gọi trực tiếp đến Fleet Engine để cung cấp thông tin về vị trí của xe. Đối với mọi xe đang hoạt động, Fleet Engine sẽ cập nhật vị trí tối thiểu 1 lần/phút và tối đa 5 giây/lần.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để cập nhật vị trí của một chiếc xe trong Fleet Engine:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
.setLastLocation(DeliveryVehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(myDeliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} 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)
Để cập nhật vị trí của xe trong Fleet Engine bằng HTTP REST, hãy gọi đến UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`
<id> là giá trị nhận dạng duy nhất cho xe giao hàng trong đội quân của bạn hoặc xe mà bạn dự định cập nhật vị trí. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể DeliveryVehicle:
Trường bắt buộc:
Kỹ thuật Giá trị lastLocation.supplementalLocation Vị trí của xe. lastLocation.supplementalLocationTime Dấu thời gian xác định gần đây nhất của chiếc xe tại vị trí này. lastLocation.supplementalLocationSensor Phải được điền bằng CUSTOMER_supPLIED_LOCATION. Các trường không bắt buộc:
Kỹ thuật Giá trị lastLocation.supplementalLocationAccuracy Độ chính xác của vị trí đã cung cấp, tính bằng mét.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"lastLocation": {
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
}
EOM
Xe đã dừng tại điểm dừng
Fleet Engine phải được thông báo khi xe đến điểm dừng. Bạn có thể thông báo cho Fleet Engine từ Driver SDK hoặc từ một môi trường máy chủ bằng gRPC hoặc REST. Không sử dụng cả hai phương pháp để tránh các điều kiện tranh đấu và để duy trì một nguồn đáng tin cậy duy nhất.
gRPC
Ví dụ sau đây cho thấy cách sử dụng thư viện Java gRPC để thông báo cho Fleet Engine rằng một chiếc xe đã đến điểm dừng:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Marking the arrival at stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} 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)
Để thông báo cho Fleet Engine về việc xe đến tại điểm dừng từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> là giá trị nhận dạng duy nhất của xe giao hàng trong nhóm thiết bị mà bạn dự định cập nhật thứ tự nhiệm vụ. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể DeliveryVehicle:
Các trường bắt buộc:
Kỹ thuật Giá trị remainingVehicleJourneySegments Điểm dừng bạn đã đến với trạng thái được đặt là State.ARRIVED, theo sau là danh sách các điểm dừng xe còn lại với trạng thái được đánh dấu là State.NEW. Các trường không bắt buộc:
- Không có
Tất cả các trường khác trong thực thể đều bị bỏ qua trong quá trình cập nhật.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ARRIVED",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Xe hoàn tất một điểm dừng
Fleet Engine phải được thông báo khi xe dừng lại xong. Điều này sẽ khiến tất cả các tác vụ liên kết với điểm dừng được đặt thành trạng thái ĐÃ ĐÓNG CỬA. Bạn có thể thông báo cho Fleet Engine từ Driver SDK, hoặc từ môi trường máy chủ bằng gRPC hoặc REST. Không sử dụng cả hai phương pháp để tránh điều kiện tranh đấu và để duy trì một nguồn đáng tin cậy duy nhất.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để thông báo cho Fleet Engine rằng một chiếc xe đã dừng lại.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} 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)
Để thông báo cho Fleet Engine về việc hoàn tất việc dừng một môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
<id> là giá trị nhận dạng duy nhất của xe giao hàng trong nhóm thiết bị mà bạn dự định cập nhật thứ tự nhiệm vụ. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể DeliveryVehicle:
Các trường bắt buộc:
Kỹ thuật Giá trị remaining_vehicle_journey_segments Điểm dừng bạn đã hoàn tất sẽ không còn nằm trong danh sách điểm dừng còn lại của xe. Các trường không bắt buộc:
- Không có
Tất cả các trường khác trong thực thể đều bị bỏ qua trong quá trình cập nhật.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Cập nhật việc cần làm
Hầu hết các trường tác vụ đều không thể thay đổi. Tuy nhiên, bạn có thể sửa đổi trạng thái, kết quả tác vụ, thời gian kết quả tác vụ, vị trí kết quả tác vụ và các thuộc tính bằng cách cập nhật trực tiếp thực thể tác vụ. Ví dụ: trong trường hợp một nhiệm vụ chưa được giao cho xe, bạn có thể đóng tác vụ đó bằng cách cập nhật trực tiếp trạng thái.
gRPC
Đây là ví dụ về cách cập nhật một nhiệm vụ thông qua gRPC.
Kiến trúc chuyển trạng thái đại diện (REST)
Đây là ví dụ về cách cập nhật một công việc thông qua REST.
Đóng việc cần làm
Để đóng một nhiệm vụ đã được giao cho một xe, hãy thông báo cho Fleet Engine rằng xe đã hoàn thành điểm dừng tại điểm dừng của nhiệm vụ đó hoặc xoá nhiệm vụ đó khỏi danh sách điểm dừng của xe. Để làm việc đó, bạn có thể đặt danh sách các điểm dừng xe còn lại giống như khi cập nhật thứ tự nhiệm vụ cho một chiếc xe.
Nếu một nhiệm vụ chưa được giao cho xe và cần phải đóng, hãy cập nhật nhiệm vụ đó thành trạng thái ĐÃ ĐÓNG CỬA. Tuy nhiên, bạn không thể mở lại việc cần làm ĐÃ ĐÓNG CỬA.
Việc đóng một nhiệm vụ không biểu thị việc thành công hay thất bại. Nó cho biết rằng tác vụ không còn được xem xét là đang thực hiện. Để theo dõi hệ thống thiết bị, quan trọng là bạn phải chỉ ra kết quả thực tế của một nhiệm vụ để có thể cho thấy kết quả phân phối.
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setState(Task.State.CLOSED) // You can only directly CLOSE a
.build(); // task that is NOT assigned to a vehicle.
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("state"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} 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)
Để đánh dấu một tác vụ là đã đóng từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`
<id> là giá trị nhận dạng duy nhất của tác vụ.
Tiêu đề yêu cầu của bạn phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Bạn phải đưa thực thể Task vào nội dung yêu cầu:
Các trường bắt buộc:
Kỹ thuật Giá trị state State.CLOSED Các trường không bắt buộc:
Kỹ thuật Giá trị taskOutcome Outcome.SUCCEEDED hoặc Outcome.FAILED. taskOutcomeTime Thời điểm hoàn thành việc cần làm. taskOutcomeLocation Vị trí nơi việc cần làm đã hoàn thành. Fleet Engine mặc định là vị trí đặt xe ở vị trí gần nhất, trừ phi nhà cung cấp ghi đè theo cách thủ công.
Tất cả các trường khác trong thực thể đều bị bỏ qua trong quá trình cập nhật.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"state": "CLOSED",
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)"
}
EOM
Đặt kết quả của nhiệm vụ và vị trí kết quả
Việc đóng một tác vụ không cho biết tác vụ có thành công hay không mà chỉ ra rằng tác vụ không còn được coi là đang thực hiện. Đối với hoạt động theo dõi hệ thống thiết bị, quan trọng là bạn phải cho biết kết quả thực tế của một nhiệm vụ để có thể cho thấy kết quả phân phối và có phương thức thanh toán phù hợp cho dịch vụ. Sau khi đặt, bạn không thể thay đổi kết quả của tác vụ. Tuy nhiên, bạn có thể sửa đổi thời gian kết quả tác vụ và vị trí kết quả tác vụ sau khi đặt.
Các tác vụ ở trạng thái ĐÃ ĐÓNG CỬA có thể đặt kết quả thành SUCCEEDED (ĐÃ THÀNH CÔNG) hoặc FAILED (KHÔNG THÀNH CÔNG). Fleet Engine chỉ tính phí các nhiệm vụ phân phối có trạng thái là SUCCEEDED.
Khi đánh dấu kết quả của một nhiệm vụ, Fleet Engine sẽ tự động điền vị trí kết quả nhiệm vụ bằng vị trí đã biết gần đây nhất của xe. Bạn có thể ghi đè hành vi này.
gRPC
Bạn có thể đặt vị trí kết quả tác vụ khi đặt kết quả. Việc đặt vị trí này sẽ ngăn Fleet Engine đặt vị trí này thành mặc định của vị trí xe gần đây nhất. Bạn cũng có thể ghi đè vị trí kết quả nhiệm vụ mà Fleet Engine đã thiết lập vào lúc khác. Fleet Engine không bao giờ ghi đè vị trí kết quả nhiệm vụ mà bạn cung cấp. Bạn không thể thiết lập vị trí kết quả tác vụ cho một tác vụ chưa đặt kết quả tác vụ. Bạn có thể đặt cả kết quả tác vụ và vị trí kết quả tác vụ trong cùng một yêu cầu.
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để đặt kết quả tác vụ thành SUCCEEDED và đặt vị trí hoàn thành tác vụ:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTime(now())
.setTaskOutcomeLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} 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)
Để đánh dấu một tác vụ là đã hoàn thành qua môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`
<id> là giá trị nhận dạng duy nhất của tác vụ.
Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Phần nội dung yêu cầu phải chứa thực thể Task:
Các trường bắt buộc:
Kỹ thuật Giá trị taskOutcome Outcome.SUCCEEDED hoặc Outcome.FAILED. Các trường không bắt buộc:
Kỹ thuật Giá trị taskOutcomeLocation Vị trí nơi việc cần làm đã hoàn thành. Nếu bạn không đặt chính sách này, thì Fleet Engine sẽ mặc định đặt giá trị này là vị trí của xe gần đây nhất. taskOutcomeTime Dấu thời gian khi việc cần làm được hoàn thành.
Tất cả các trường khác trong thực thể đều bị bỏ qua trong quá trình cập nhật.
Ví dụ về lệnh curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
Định tuyến lại lô hàng
Sau khi tạo nhiệm vụ vận chuyển, bạn không thể thay đổi vị trí theo kế hoạch của nhiệm vụ đó. Để định tuyến lại một lô hàng, hãy đóng nhiệm vụ vận chuyển mà không đặt ra kết quả, sau đó tạo một nhiệm vụ mới với vị trí đã lên kế hoạch đã cập nhật. Sau khi tạo nhiệm vụ mới, hãy giao nhiệm vụ đó cho cùng một chiếc xe. Để biết thêm thông tin, hãy xem phần đóng nhiệm vụ vận chuyển và giao nhiệm vụ.
Sử dụng xe trung chuyển và xe giao hàng
Nếu bạn dùng các phương tiện giao hàng để vận chuyển hàng vận chuyển đến xe giao hàng trong suốt cả ngày, hãy lập mô hình quá trình chuyển hàng dưới dạng một nhiệm vụ dừng theo lịch cho xe giao hàng. Để đảm bảo theo dõi vị trí chính xác, chỉ giao nhiệm vụ giao hàng cho một lô hàng đã chuyển sau khi hàng được chất lên xe giao hàng. Để biết thêm thông tin, hãy xem bài viết điểm dừng theo lịch.
Trạng thái vận chuyển của cửa hàng và các siêu thông tin khác
Khi một nhiệm vụ vận chuyển hoàn tất, trạng thái và kết quả của nhiệm vụ sẽ được ghi lại trong nhiệm vụ đó. Tuy nhiên, bạn nên cập nhật các thông tin meta khác cụ thể cho lô hàng. Để lưu trữ những thông tin meta khác mà bạn có thể tham chiếu bên ngoài dịch vụ Fleet Engine, hãy sử dụng theo dõi_id liên kết với tác vụ làm khoá trong bảng bên ngoài.
Để biết thêm thông tin, hãy xem bài viết Vòng đời của một nhiệm vụ.
Tra cứu phương tiện
Bạn có thể tra cứu xe từ SDK trình điều khiển hoặc từ môi trường máy chủ bằng gRPC hoặc REST.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tra cứu xe:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} 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)
Để tra cứu xe từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến GetVehicle:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`
<id> là giá trị nhận dạng duy nhất của tác vụ.
<vehicleId> là mã nhận dạng của xe 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ị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
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ể xe.
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}/deliveryVehicles/${VEHICLE_ID}"
Tra cứu việc cần làm
Bạn có thể tra cứu công việc từ môi trường máy chủ bằng gRPC hoặc REST. SDK trình điều khiển không hỗ trợ tra cứu một tác vụ.
gRPC
Ví dụ sau cho biết cách dùng thư viện Java gRPC để tra cứu một tác vụ:
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)
Để tra cứu một tác vụ từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến GetTask:
`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ị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
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 thông tin về nhiệm vụ vận chuyển theo mã theo dõi
Bạn có thể tra cứu thông tin về các nhiệm vụ của nhóm thiết bị theo những cách sau, mỗi cách có một mục đích riêng:
- theo mã công việc: được những người dùng như nhà vận hành hệ thống thiết bị có quyền truy cập vào toàn bộ dữ liệu công việc sử dụng.
- bằng mã theo dõi: được phần mềm ứng dụng của bạn sử dụng để cung cấp thông tin hạn chế cho người dùng cuối, chẳng hạn như khi dự kiến nhận gói hàng tại nhà của họ.
Phần này thảo luận cách tra cứu thông tin công việc bằng mã theo dõi. Nếu bạn muốn tra cứu một công việc theo mã công việc, hãy chuyển đến phần Tra cứu một công việc.
Để tra cứu thông tin theo mã theo dõi, bạn có thể sử dụng một trong các cách sau:
Yêu cầu về tra cứu
Thông tin vận chuyển do mã theo dõi cung cấp phải tuân thủ các quy tắc về chế độ hiển thị nêu trong phần Kiểm soát chế độ hiển thị của các vị trí được theo dõi.
Sử dụng Fleet Engine để tra cứu thông tin vận chuyển bằng mã theo dõi. SDK trình điều khiển không hỗ trợ tra cứu thông tin bằng mã theo dõi. Để thực hiện việc này bằng Fleet Engine, bạn cần sử dụng môi trường máy chủ hoặc trình duyệt.
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, mọi lệnh gọi API Fleet Engine Deliveries sẽ chỉ trả về thông tin liên quan đến người dùng cuối đó, chẳng hạn như người vận chuyển hoặc người nhận hàng vận chuyển. Tất cả thông tin khác trong các câu trả lời đều bị loại bỏ. Để biết thêm thông tin về mã thông báo, hãy xem phần Tạo mã thông báo web JSON (JWT) để uỷ quyền.
Tra cứu bằng Java bằng gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tra cứu thông tin về nhiệm vụ vận chuyển theo mã theo dõi của nhiệm vụ đó.
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;
}
Tra cứu bằng HTTP
Để tra cứu nhiệm vụ vận chuyển qua trình duyệt, hãy thực hiện lệnh gọi HTTP REST đến GetTaskTrackingInfo:
`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ị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Nếu tra cứu thành công, nội dung phản hồi sẽ chứa 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
Bạn có thể liệt kê các công việc từ môi trường máy chủ hoặc trình duyệt. SDK Trình điều khiển không hỗ trợ việc liệt kê các tác vụ.
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 Trình đọc nhóm phân phối hoặc Mã thông báo xác thực người dùng siêu phân phối khi tạo yêu cầu tác vụ danh sách.
Các tác vụ trong danh sách có các trường sau đây đã bị loại bỏ:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
Bạn có thể lọc các công việc trong danh sách theo hầu hết thuộc tính của công việc. Để biết cú pháp truy vấn bộ lọc, hãy xem AIP-160. Danh sách sau đây cho thấy các thuộc tính tác vụ hợp lệ mà bạn có thể dùng để lọc:
- attributes
- delivery_vehicle_id
- state
- planned_location
- task_duration
- task_outcome
- task_outcome_location
- task_outcome_location_source
- task_outcome_time
- tracking_id
- loại
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 |
| Liệt kê | 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 |
Hãy xem AIP-160 để biết danh sách đầy đủ các toán tử truy vấn bộ lọc.
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ê.
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 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, thì hệ thống sẽ sử dụng giá trị 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ì kích thước 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. Sử dụng mã thông báo trang với một yêu cầu giống hệt với yêu cầu trước đó để truy xuất trang việc cần làm tiếp theo. Khi mã thông báo trang được trả về trống, sẽ không có thêm tác vụ nào để truy xuất.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để liệt kê các tác vụ cho một deliveryvehicleId và một thuộc tính của nhiệm vụ. Phản hồi thành công vẫn có thể trống. Phản hồi trống cho biết rằng không có Tác vụ nào được liên kết với deliveryvehicleId đã 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;
}
Kiến trúc chuyển trạng thái đại diện (REST)
Để liệt kê các tác vụ trên một trình duyệt, hãy thực hiện lệnh gọi HTTP REST đến ListTasks:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`
Để áp dụng bộ lọc cho các công việc trong danh sách, hãy thêm tham số URL "bộ lọc" với truy vấn bộ lọc đượ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ị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Nếu tra cứu thành công thì nội dung phản hồi sẽ chứa dữ liệu theo cấu trúc sau:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
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ìm thấy tác vụ nào đáp ứng tiêu chí bộ lọc đã chỉ định.
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}"
Liệt kê xe giao hàng
Bạn có thể liệt kê xe giao hàng từ môi trường máy chủ hoặc trình duyệt. SDK trình điều khiển không hỗ trợ danh sách xe giao hàng.
Phương tiện giao hàng trang thông tin yêu cầu quyền truy cập rộng rãi vào xe giao hàng và chỉ dành cho những người dùng đáng tin cậy. Sử dụng Trình đọc nhóm phân phối hoặc Mã thông báo xác thực người dùng siêu phân phối khi đưa ra yêu cầu về xe giao hàng theo danh sách.
Các trường sau đây bị loại bỏ do ảnh hưởng của các trường trong danh sách xe giao hàng đến kích thước phản hồi:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
Bạn có thể lọc danh sách các phương tiện giao hàng theo tài sản attributes của họ. Ví dụ: để truy vấn một thuộc tính bằng khoá my_key và giá trị my_value, hãy sử dụng attributes.my_key = my_value. Để truy vấn nhiều thuộc tính, hãy kết hợp các truy vấn bằng cách sử dụng các toán tử logic AND và OR như trong attributes.key1 = value1 AND
attributes.key2 = value2. Hãy xem AIP-160 để biết nội dung mô tả đầy đủ về cú pháp truy vấn bộ lọc.
Bạn có thể lọc các xe giao hàng trong danh sách theo vị trí bằng cách sử dụng tham số yêu cầu viewport. Tham số yêu cầu viewport xác định khung nhìn bằng hai toạ độ giới hạn: cặp toạ độ vĩ độ và kinh độ high (đông bắc) và low (tây nam). Yêu cầu sẽ bị từ chối nếu vĩ độ cao thấp hơn vĩ độ địa lý thấp.
Theo mặc định, danh sách xe giao hàng được phân trang bằng kích thước trang hợp lý. Nếu bạn chỉ định kích thước trang, yêu cầu sẽ chỉ trả về số lượng xe được chỉ định trong giới hạn hoặc ít hơn. Nếu kích thước trang được yêu cầu vượt quá giá trị tối đa nội bộ, thì kích thước tối đa nội bộ sẽ được sử dụng. Kích thước trang mặc định và tối đa đều là 100 xe.
Danh sách xe giao hàng có thể bao gồm một mã thông báo để đọc trang kết quả tiếp theo. Mã thông báo trang chỉ xuất hiện trong phản hồi khi có thêm trang phương tiện giao hàng để truy xuất. Để truy xuất trang tác vụ tiếp theo, hãy sử dụng mã thông báo trang với yêu cầu giống hệt với yêu cầu trước đó.
gRPC
Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để liệt kê các xe giao hàng ở một khu vực cụ thể kèm theo một thuộc tính nhất định. Phản hồi thành công vẫn có thể trống. Khi điều đó xảy ra, có nghĩa là không có xe nào có thuộc tính được chỉ định đã nằm trong khung nhìn được chỉ định.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
ListDeliveryVehiclesRequest.newBuilder() // No need for the header
.setParent(parent)
.setViewport(
Viewport.newBuilder()
.setHigh(LatLng.newBuilder()
.setLatitude(37.45)
.setLongitude(-122.06)
.build())
.setLow(LatLng.newBuilder()
.setLatitude(37.41)
.setLongitude(-122.11)
.build())
.setFilter("attributes.my_key = my_value")
.build();
try {
ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} 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)
Để liệt kê các tác vụ trên một trình duyệt, hãy thực hiện lệnh gọi HTTP REST đến ListDeliveryVehicles:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Để áp dụng bộ lọc cho các tác vụ được liệt kê, hãy thêm tham số URL "bộ lọc" với 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ị Bearer <token>, trong đó <token> là mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.
Nếu tra cứu thành công thì nội dung phản hồi sẽ chứa dữ liệu theo cấu trúc sau:
// JSON representation
{
"deliveryVehicles": [
{
object (DeliveryVehicle)
}
],
"nextPageToken": string,
"totalSize": integer
}
Một phản hồi thành công vẫn có thể trống. Khi điều đó xảy ra, điều đó có nghĩa là không tìm thấy xe giao hàng nào đáp ứng khung nhìn và truy vấn bộ lọc đã chỉ định.
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}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"
Theo dõi đội phương tiện vận chuyển
Bạn có hai lựa chọn sử dụng Fleet Engine Deliveries API để bật tính năng theo dõi nhóm thiết bị:
Ưu tiên: Dùng thư viện Theo dõi nhóm JavaScript. Thư viện này cho phép bạn minh hoạ vị trí của xe và vị trí quan tâm được theo dõi trong Fleet Engine. Lớp này chứa thành phần bản đồ JavaScript thay thế cho đối tượng google.maps.Map chuẩn và các thành phần dữ liệu để kết nối với Fleet Engine. Thành phần này cho phép bạn cung cấp trải nghiệm theo dõi nhóm ảnh động có thể tuỳ chỉnh từ web hoặc ứng dụng di động của mình.
Triển khai tính năng theo dõi nhóm riêng của bạn dựa trên Fleet Engine Deliveries API.
Điều quan trọng là cần tra cứu các công việc trong nhóm thiết bị bằng mã theo dõi.
Ghi nhật ký
Bạn có thể thiết lập Fleet Engine để gửi nhật ký RPC đến Cloud Logging. Để biết thêm thông tin, hãy xem phần Ghi nhật ký.
Vai trò và mã thông báo uỷ quyền
Như mô tả trong phần Quản lý vòng đời của xe và nhiệm vụ cũng như ghi chú uỷ quyền cho từng trường hợp sử dụng, việc thực hiện các lệnh gọi đến Fleet Engine sẽ yêu cầu xác thực bằng Mã thông báo web JSON đã được ký bằng thông tin xác thực tài khoản dịch vụ. Các tài khoản dịch vụ dùng để phát hành những mã thông báo đó có thể có một hoặc nhiều vai trò, mỗi vai trò sẽ cấp một nhóm quyền khác nhau.
Để biết thêm thông tin, hãy xem phần Xác thực và uỷ quyền.
Khắc phục các sự cố thường gặp
Hãy xem các mục sau đây để được trợ giúp nếu bạn gặp phải vấn đề.
Khả năng phục hồi
Fleet Engine không được xem là nguồn đáng tin cậy. Bạn có trách nhiệm khôi phục trạng thái của hệ thống nếu cần mà không cần dựa vào Fleet Engine.
Trạng thái bị mất trong Fleet Engine
Khi làm việc với Fleet Engine, hãy triển khai ứng dụng để hệ thống tự khắc phục trong trường hợp có lỗi. Ví dụ: khi Fleet Engine cố gắng cập nhật một xe, công cụ này có thể phản hồi và thông báo lỗi cho biết xe không tồn tại. Sau đó, khách hàng phải tạo lại chiếc xe ở trạng thái mới. Mặc dù vấn đề này hiếm khi xảy ra, nhưng hãy đảm bảo rằng hệ thống của bạn có đủ khả năng phục hồi để xử lý.
Trong trường hợp hiếm gặp xảy ra sự cố nghiêm trọng của Fleet Engine, bạn có thể sẽ phải tạo lại hầu hết hoặc tất cả phương tiện và nhiệm vụ. Nếu tỷ lệ tạo trở nên quá cao, một số yêu cầu có thể không thực hiện được do các vấn đề về hạn mức vì việc kiểm tra hạn mức được áp dụng nhằm tránh các cuộc tấn công từ chối dịch vụ (DOS). Trong trường hợp này, hãy giảm tốc độ tạo lại bằng cách sử dụng chiến lược thời gian đợi để thử lại.
Trạng thái bị mất trong ứng dụng dành cho người lái xe
Nếu ứng dụng trình điều khiển gặp sự cố, ứng dụng phải tạo lại trạng thái hiện tại trong SDK trình điều khiển. Ứng dụng sẽ cố gắng tạo lại các tác vụ để đảm bảo rằng các tác vụ đó tồn tại và khôi phục trạng thái hiện tại. Ứng dụng cũng phải tạo lại và đặt rõ danh sách điểm dừng cho SDK Trình điều khiển.
Câu hỏi thường gặp
Điều gì sẽ xảy ra nếu người lái xe dừng lại để thực hiện một nhiệm vụ không đúng thứ tự?
Trong trường hợp này, trước tiên, hãy cập nhật thứ tự của các tác vụ rồi tiếp tục như bình thường, đánh dấu điểm đến, hoàn thành tác vụ và các thông tin chi tiết khác. Nếu bạn không thì hệ thống có thể sẽ trở nên nhất quán, ETA có thể không chính xác và các lỗi không mong muốn có thể được báo cáo.