Làm quen với Fleet Engine để theo dõi tình hình vận chuyển

Lập mô hình các hoạt động trong nhóm thiết bị của bạn cho chuyến giao hàng đầu tiên và dặm cuối cùng bằng API Phân phối Fleet Engine. Bạn có thể sử dụng API này bằng cách sử 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 các lệnh gọi HTTP REST hay gRPC.

Thiết lập ban đầu

Bạn có thể định cấu hình Fleet Engine Deliveries API trong Google Cloud Console.

Xác minh 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à tạo một phương tiện giao hàng. Xác minh chế độ thiết lập của bạn ngay lập tức đảm bảo rằng bạn đã giải quyết các vấn đề thường gặp về việc uỷ quyền có thể phát sinh khi khi thiết lập dự án. Có 2 cách để xác minh chế độ thiết lập của bạn:

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 khách bằng một số ngôn ngữ lập trình phổ biến. Cho hướng dẫn về cách tải thư viện ứng dụng cho ứng dụng máy chủ của bạn, hãy xem 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 hai cấu trúc dữ liệu để lập mô hình cho hoạt động đến lấy hàng và giao hàng số lượng lô 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 dùng các nhiệm vụ để lập mô hình giờ nghỉ giữa chừng và điểm dừng theo lịch suốt cả ngày.

Xe giao hàng

Xe giao hàng vận chuyển các lô hàng từ kho đến một địa điểm giao hàng, và từ một vị trí đón đến kho. Trong một số trường hợp, chúng cũng có thể vận chuyển trực tiếp lô hàng từ vị trí đến lấy hàng đến địa điểm giao hàng.

Sử dụng SDK Trình điều khiển để tạo đối tượng DeliveryVehicle trong Fleet Engine cũng như gửi thông tin cập nhật về vị trí để theo dõi quá trình vận chuyển và đội xe.

Tasks

Đối với những hành động mà một chiếc xe thực hiện trong ngày, bạn chỉ định việc cần làm 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ể lái xe, như khi cần nghỉ giải lao, chỉ định tác vụ Không thể sử dụng.
  • Đối với các nhiệm vụ không liên quan đến việc lái xe tại hòm thư hoặc tại địa điểm của khách hàng, hãy chỉ định Việc cần làm có thể dừng theo lịch.

Mỗi việc cần làm mà bạn giao phải có một mã việc cần làm duy nhất, nhưng các việc cần làm có thể có cùng một mã mã theo dõi. Khi Fleet Engine tính toán thời gian đến dự kiến cửa sổ cho mỗi tác vụ, nó sẽ sử dụng tất cả các tác vụ và thứ tự mà họ được lên lịch để thực hiện ước tính. Để biết thêm thông tin về mã công việc, hãy xem Nguyên tắc đối với mã việc cần làm.

Để 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 nhiệm vụ vận chuyển cho cả việc đến lấy hàng và giao hàng, và bao gồm các 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 thêm thời gian hoàn thành công việc, hãy xem để đỗ xe hoặc đi bộ đến vị trí chuyể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

Nhiệm vụ về tình trạng không khả dụng cho biết khoảng thời gian xe không hoạt động dịch vụ đến lấy hàng hoặc giao hàng, chẳng hạn như thời gian nghỉ ngơi để đổ xăng cho xe hoặc tài xế nghỉ ngơ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 phải cung cấp vị trí cụ thể, nhưng làm như vậy sẽ cung cấp khoảng thời gian đến dự kiến chính xác hơn 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 trạm dừng mà xe giao hàng cần thực hiện. Ví dụ: tạo việc cần làm dừng theo lịch cho một lịch biểu hằng ngày ngừng thu thập tại một địa điểm cụ thể, độc lập với các gói phân phối khác hoặc đến lấy hàng tại cùng một vị trí. Bạn cũng có thể tạo các thao tác dừng theo lịch cho các bộ sưu tập từ thùng đựng hàng hoặc chuyển mô hình sang 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 về 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
  • Không tiết lộ bất kỳ thông tin nhận dạng cá nhân (PII) hoặc xoá dữ liệu văn bản.
  • Sử dụng chuỗi Unicode hợp lệ.
  • Chỉ được dùng tối đa 64 ký tự.
  • Đừng dùng 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 Hasford, 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 mỗi dữ liệu cấu trúc, vui lòng 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 Fleet Engine API.
  • 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. Không sử dụng lại mã xe trừ phi không có nhiệm vụ nào đang hoạt động đối với xe ban đầu.

Fleet Engine tự động xoá DeliveryVehicle đối tượng chưa đã được cập nhật bằng UpdateDeliveryVehicle sau 7 ngày. Các thành phần được đề xuất để duy trì khả năng sử dụng phương tiện trong Fleet Engine là cập nhật vị trí của phương tiện đó theo định kỳ. Nội dung cập nhật đối với hầu hết các trường khác trong DeliveryVehicle thực thể cũng sẽ kéo dài tuổi thọ của nó, miễn là giá trị trường mới khác từ quảng cáo hiện tại.

Để xem xe có tồn tại hay không:

  1. Gọi đến số UpdateDeliveryVehicle.
  2. Nếu bạn gặp lỗi NOT_FOUND, hãy gọi CreateDeliveryVehicle để tái tạo chiếc 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.

Loại phương tiện

Thực thể VehicleType chứa trường không bắt buộc của VehicleType, trong đó có chứa Enum Category mà bạn có thể chỉ định là AUTO, TWO_WHEELER, BICYCLE hoặc PEDESTRIAN. Nếu bạn không đặt trường này, thì trường này sẽ được đặt mặc định thành AUTO.

Tất cả tuyến đường cho các phương tiện di chuyển sử dụng RouteTravelMode tương ứng cho loại xe.

Thuộc tính xe

Thực thể DeliveryVehicle chứa trường lặp lại là DeliveryVehicleAttribute. API ListDeliveryVehicles bao gồm một filter trường có thể giới hạn thực thể DeliveryVehicle được trả về thành những thực thể có các thuộc tính đã chỉ định. DeliveryVehicleAttribute không ảnh hưởng đến Fleet Engine hành vi định tuyến.

Đừng thêm thông tin nhận dạng cá nhân (PII) hoặc thông tin nhạy cảm trong các thuộc tính vì người dùng có thể thấy trường này.

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 nhiệm 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 của đối tượng đó vòng đời của nó. Các giá trị sẽ chuyển từ trạng thái MỞ sang ĐÓNG CỬA. Đã tạo việc cần làm mới ở 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 hủy một nhiệm vụ bằng cách xóa nhiệm vụ đó khỏi danh sách điểm dừng xe, thao tác này sẽ đặt trạng thái của công việc thành tự động ĐÓ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ụ:

  1. 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).

  2. Chỉ định dấu thời gian của sự kiện.

    Sau đó, thư viện JavaScript theo dõi vận chuyển sẽ cho biết kết quả của tác vụ và trạng thái của công việc sẽ tự động được đặt thành ĐÃ ĐÓNG CỬA. Để biết thêm thông tin, hãy xem Theo dõi lô hàng của bạn bằng thư viện Theo dõi lô hàng JavaScript.

Giống như đối với xe, Fleet Engine sẽ xoá những nhiệm vụ chưa được cập nhật sau đó 7 ngày và nếu bạn cố tạo một công việc bằng mã nhận dạng đã tồn tại, sẽ trả về một lỗi.

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ụ tự động xoá việc cần làm sau 7 ngày mà không cập nhật. Nếu bạn muốn lưu giữ dữ liệu công việc lâu hơn 7 ngày, bạn phải tự triển khai khả 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 là TaskAttribute, có thể có giá trị từ một trong 3 loại: chuỗi, số và boolean. API ListTasks bao gồm trường filter có thể giới hạn được trả về Thực thể Task thành những thực thể có thuộc tính được chỉ định. Thuộc tính việc cần làm không ảnh hưởng đến hành vi định tuyến Fleet Engine.

Đừng thêm thông tin nhận dạng cá nhân (PII) hoặc các thông tin nhạy cảm khác thông tin 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ộ của bạn đóng vai trò là nguồn dữ liệu đáng tin cậy mà API Fleet Engine Deliveries thay mặt bạn nâng cấp.

Để 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 người lái xe sẽ giao tiếp trực tiếp với Fleet Engine để cập nhật thông tin 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ả vị trí theo thời gian thực. Thao tác này sẽ gửi trực tiếp vị trí đến thư viện theo dõi mà sau đó bạn có thể sử dụng để cập nhật trạng thái của người tiêu dùng đơn đặt hàng của họ.

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 gửi vị trí của ứng dụng tới Fleet Engine.
  • Fleet Engine gửi thông tin vị trí của thiết bị cho thư viện theo dõi mà ứng dụng tiêu dùng của bạn sử dụng để cảnh báo người tiêu dùng gần gói hàng của họ.
  • Sau khi tài xế hoàn tất quá trình vận chuyển, họ nhấp vào thông báo "Đã giao hàng" trên ứng dụng trình điều khiển.
  • "Lô hàng đã được giao" hành động gửi thông tin đến hệ thống phụ trợ của bạn, thực hiện các bước xác thực và xác minh doanh nghiệp 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 cách sử dụng API Phân phối.

Biểu đồ dưới đây minh hoạ các quy trình này ở mức độ chung. Điều này cũng cho thấy mối quan hệ chuẩn giữa hệ thống của bạn, máy khách và Fleet Engine.

Sử dụng API Phân phối

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 dành cho người lái xe và được gửi trực tiếp để Fleet Engine yêu cầu 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:

  1. Tạo mã thông báo bằng cách sử dụng Người dùng trình điều khiển không tin cậy của Fleet Engine Delivery vai trò trong tài khoản dịch vụ.

  2. 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 cuộc gọi bắt nguồn từ thiết bị di động sẽ được cân nhắc 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 thực hiện Fleet Engine cập nhật những nội dung ngoài những quyền được giới hạn ở vai trò Tài xế không tin cậy, chẳng hạn như đối với một số thông tin cập nhật về tác vụ, bạn có thể sử dụng vai trò Người lái xe đáng tin cậy. Cho thông tin về mô hình sử dụng vai trò Người lái xe đáng tin cậ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ò người lái xe không đáng tin cậy và không đáng tin cậy, hãy xem 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 cho người lái xe chạy tuyến đầu hoặc dặm cuối cùng có thể trông giống như một công ty giao hàng và kho vận. Công ty của bạn có thể khác nhau về chi tiết, nhưng bạn có thể xem cách bạn có thể lập mô hình một ngày làm việc.

Thời gianHoạt độngLậ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 nhiệm vụ liên quan đến việc vận chuyển hàng giao, đến lấy hàng, nghỉ giải lao và khác trong Fleet Engine trước khi ra mắt. Ví dụ: bạn có thể tạo một tác vụ nhận hàng để vận chuyển, nhiệm vụ giao hàng tình trạng không có 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 tập hợp các gói hàng giao hàng và thứ tự phân phối chúng đã được hoàn tất.
Đầ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 nhiệm vụ giao hàng vận chuyển không được tạo trước thời hạn, tạo nhiệm vụ giao hàng 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 chúng không được tạo trước, hãy tạo nhiệm vụ lấy hàng để vận chuyển, tình trạng không có hàng được lên lịch và điểm dừng theo lịch.
Người lái xe rời kho và cam kết thực hiện số nhiệm vụ tiếp theo đã hoàn tất. Giao tất cả việc cần làm hoặc một nhóm nhỏ việc cần làm vào xe bằng cách thực hiện yêu cầu hoàn thành.
Tài xế giao hàng. Sau khi đến điểm dừng giao hàng, hãy thực hiện các hành động liên quan đến một xe đang đến điểm dừng. Sau khi giao hàng, đóng công việc phân phối và (không bắt buộc) trạng thái vận chuyển tại cửa hàng và các siêu thông tin khác. Sau khi hoàn thành tất cả các tác vụ ở điểm dừng và trước đó bắt đầu lái xe đến điểm dừng tiếp theo, thực hiện các hành động liên quan đến xe cộ hoàn thành một điểm dừng và phương tiện di chuyển đến trạ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 để 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 một đ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 chúng chưa được tạo. Sau đó, hãy cập nhật thông tin hoàn thành việc cần làm sắp xếp bằng cách giao nhiệm vụ cho một chiếc xe và cập nhật thứ tự tác 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, tạo nhiệm vụ đến lấy hàng. Sau đó, hãy cập nhật hoạt động thực thi tác vụ sắp xếp bằng cách giao nhiệm vụ cho một chiếc xe và cập nhật thứ tự tác vụ.
Buổi trưa Tài xế nghỉ trưa. Nếu một vị trí có liên quan đến nhiệm vụ về tình trạng không khả dụng, hãy coi vị trí đó giống như bất kỳ tác vụ nào khác. Thực hiện các thao tác liên quan đến xe đến một điểm dừng, xe đã dừng và xe đang lên đường đến trạm dừng tiếp theo.

Nếu không, bạn không cần làm gì thêm cho đến khi kết thúc điểm chèn quảng cáo. 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ự tác 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 một xe đang đến điểm dừng cũng như đóng một tác vụ và tuỳ ý lưu trữ trạng thái vận chuyển và các siêu thông tin khác. Sau khi hoàn thành tất cả các nhiệm vụ tại điểm dừng và trước khi bắt đầu lái xe đến điểm dừng tiếp theo, thực hiện các thao tác liên quan đến xe hoàn tất một điểm dừng và phương tiện di chuyển đến trạ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 lần đến lấy hàng phải có thông tin thanh toán tương ứng nhiệm vụ phân phối. Nếu đơn đặt hàng đến lấy hàng được giao đến một địa điểm khác trên tuyến đường của cùng một tuyến đường vào ngày hôm đó, bạn nên lập mô hình tác vụ phân phối đó như bất kỳ nhiệm vụ phân phối nào khác trên tuyến đường đó. Nếu tài xế mang xe đến lấy hàng quay lại kho, chúng tôi đề xuất tạo một nhiệm vụ giao hàng tại kho đích.
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 một xe đang đến điểm dừng và đóng tác vụ. Sau khi hoàn tất tất cả các nhiệm vụ tại điểm dừng và bắt đầu lái xe đến điểm dừng tiếp theo, thực hiện các hành động liên quan đến việc xe bị dừng hoàn tất và phương tiện di chuyển đến trạ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 một mục mới nhiệm vụ giao hàng cho vị trí giao hàng mới. Để biết thêm thông tin, xem Đị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. Việc này được lập mô hình tương tự như một điểm dừng giao hàng thành công, đánh dấu nhiệm vụ phân phối quảng cáo là đã hoàn tất. Thực hiện các thao tác liên quan đến một xe đến điểm dừng. Sau không thể giao hàng, đóng tác vụ và tuỳ ý trạng thái vận chuyển tại cửa hàng và các siêu thông tin khác. Sau khi hoàn thành tất cả các nhiệm vụ tại điểm dừng và trước khi bắt đầu lái xe đến điểm dừng tiếp theo, thực hiện các thao tác liên quan đến xe hoàn tất một điểm dừng và phương tiện di chuyển đến trạ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, đặt trạng thái công việc 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ụ, sau đó tiếp tục 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 hành động liên quan đến xe đến điểm dừng. Sau khi giao từng lô hàng, hãy đóng từng nhiệm vụ và (không bắt buộc) trạng thái vận chuyển tại cửa hàng và các siêu thông tin khác. Sau khi hoàn thành tất cả các nhiệm vụ tại điểm dừng và trước khi bắt đầu lái xe đến điểm dừng tiếp theo, thực hiện các thao tác liên quan đến xe hoàn tất một điểm dừng và phương tiện di chuyển đến trạ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 trở lại kho hàng kèm theo các gói hàng đã được lấy trong kho , bạn cũng phải tạo và đóng từng gói dưới dạng tác vụ phân phối để đảm bảo 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 phân phối khác. Nếu kho hàng không được dùng làm trạm giao hàng, bạn vẫn có thể tuỳ ý mô hình kho hàng như một điểm dừng theo lịch. Lập mô hình điểm dừng sẽ cho phép người lái xe của bạn thấy được tuyến đường quay lại kho và cho biết thời gian ước tính của họ thời gian đến.

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 nó một luồng xe cập nhật vị trí. 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:

  1. Sử dụng SDK trình điều khiển – Android, iOS -- lựa chọn đơn giản nhất.
  2. Sử dụng mã tùy chỉnh -- hữu ích nếu vị trí được chuyển tiếp qua phần phụ trợ của bạn hoặc nếu bạn sử dụng thiết bị không phải là Android hoặc iOS.

Bất kể bạn cung cấp thông tin cập nhật vị trí 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 xe giao hàng trên đường đến một điểm dừng (bao gồm cả kho) và khi nào tới điểm dừng. Fleet Engine không phát hiện được những sự kiện này tự động.

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 công việc 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ư một đế tải hoặc một vị trí bị mắc kẹt trên đường.

Địa điểm giao hàng là địa điểm giao hàng hoặc được chọn. Bạn có thể phải đi bộ một chút để đi từ địa điểm giao hàng đến địa điểm giao hàng từ trạm xe.

Ví dụ: khi người lái xe đang giao hàng tới một cửa hàng trong một trung tâm mua sắm, xe giao hàng 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. Tài xế sau đó đi bộ từ trạm xe đến vị trí trong trung tâm mua sắm nơi cửa hàng nằm ở đâu. Đây là vị trí giao hàng.

Để người dùng có trải nghiệm theo dõi vận chuyển tốt nhất, hãy cân nhắc cách nhiệm vụ vận chuyển được chỉ định cho các trạm dừng xe và xin lưu ý rằng số lượng số điểm dừng còn lại của xe để vận chuyển công việc sẽ được báo cáo cho người dùng để giúp họ xem tiến trình vận chuyển của họ.

Ví dụ: nếu một người lái xe đang giao hàng đến một toà nhà văn phòng duy nhất, 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 điểm dừng xe riêng, lô hàng của bạn sẽ ít hữu ích hơn cho người dùng của bạn vì tính năng theo dõi chỉ có sẵn khi xe ở một số điểm dừng nhất định trước khi đích đến của nó. Việc có nhiều điểm dừng xe hoàn tất trong một thời gian ngắn sẽ không mang lại người dùng dành nhiều thời gian để theo dõi tiến trình phân phối.

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 đảm bảo để khởi chạy 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 lệnh gọi REST là không 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 mã 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 phương tiện giao hàng mới. Xin lưu ý rằng mọi giá trị được chỉ định cho trường Name đều 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ề thông báo lỗi bởi vì các trường đó ở 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ể để Chưa đặt trường DeliveryVehicle trong CreateDeliveryVehicleRequest.

Ví dụ sau đây minh hoạ cách sử dụng Thư viện Java gRPC để tạo một chiếc 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>

&lt;id&gt; 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

  • 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ề thông báo lỗi vì các trường đó ở 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 thiết lập trường nào, hãy rời khỏi phần nội dung của yêu cầu POST trống. Chiếc xe mới được tạo sau đó 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 nhiệm vụ đến lấy hàng vận chuyển 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 đây minh hoạ cách sử dụng Thư viện Java gRPC để tạo tác vụ 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>`

&lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ. Đó không được là số vận đơn cho lô hàng. Nếu chưa có mã công việc trong hệ thống, bạn có thể tạo mã 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá trị
    loại Type.PICKUP
    tiểu bang 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 công việc cần được hoàn thành, trong trường hợp này vị trí nhận hàng để vận chuyển.
    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:

    TrườngGiá trị
    targetTimeWindow Khoảng thời gian hoàn thành tác vụ. Điều này không ảnh hưởng đến hành vi đị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. Ném của Fleet Engine trường hợp ngoại lệ nếu yêu cầu bao gồm deliveryVehicleId được chỉ định. Bạn chỉ định công việc bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem Chỉ định 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 nhiệm vụ giao hàng trong 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 đây minh hoạ cách sử dụng Thư viện Java gRPC để tạo 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ụ giao 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>`

&lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ. Đó không được là số vận đơn cho lô hàng. Nếu chưa có mã công việc trong hệ thống, bạn có thể tạo mã 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá trị
    loại Type.DELIVERY
    tiểu bang 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 công việc cần được hoàn thành, trong trường hợp này địa điểm giao hàng cho lô hàng này.
    taskDuration Thời gian dự kiến (tính bằng giây) để giao kiện hàng tại vị trí giao hàng.

  • Các trường không bắt buộc:

    TrườngGiá trị
    targetTimeWindow Khoảng thời gian hoàn thành tác vụ. Điều này không ảnh hưởng đến hành vi đị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. Ném của Fleet Engine trường hợp ngoại lệ nếu yêu cầu bao gồm deliveryvehicleId được chỉ định. Bạn chỉ định công việc bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem Chỉ định 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 đây minh hoạ cách sử dụng Thư viện Java gRPC để tạo hai công việc, một cho việc giao hàng và một cho đến lấy hàng cùng một lúc 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à đến lấy hàng từ môi trường máy chủ, hãy tạo một Lệnh gọi REST của HTTP tới 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 với 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:

    TrườngGiá trị
    yêu cầu Mảng<CreateTasksRequest>

  • Các trường không bắt buộc:

    TrườngGiá trị
    tiêu đề `DeliveryRequestHeader`

Mỗi phần tử CreateTasksRequest trong requests đều phải vượt qua cùng một quy trình xác thực quy tắc dưới dạng yêu cầu CreateTask, với ngoại lệ là parent và header là trường không bắt buộc. Nếu được đặt, các giá trị này phải giống với các trường tương ứng ở cấp cao nhất BatchCreateTasksRequest. Xem tạo nhiệm vụ lấy hàng để vận chuyển và tạo nhiệm vụ giao hàng vận chuyển để biết quy tắc xác thực cụ thể cho từng ứng dụng.

Để 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 nhiệm vụ cho biết không có dịch vụ (ví dụ: cho người lái xe) hỏng hoặc tiếp nhiên liệ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. Nhiệm 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 đây minh hoạ cách sử dụng Thư viện Java gRPC để tạo tác vụ không hoạt độ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.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 HTTP REST đến CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

&lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ. Nếu không có mã công việc trong hệ thống của mình, bạn có thể tạo mã công việc duy nhất trên toàn cầu mã nhận dạng (UUID).

Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá trị
    loại Type.UNAVAILABLE
    tiểu bang 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:

    TrườngGiá 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. Ném của Fleet Engine trường hợp ngoại lệ nếu yêu cầu bao gồm deliveryvehicleId được chỉ định. Bạn chỉ định công việc bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem Chỉ định 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 đã lên lịch bằng một trong hai cách sau SDK trình điều khiển, hoặc từ môi trường máy chủ bằng gRPC hoặc REST. Nhiệm vụ dừng theo lịch có thể không bao gồm hoạt động theo dõi Mã nhận dạng.

gRPC

Ví dụ sau đây minh hoạ cách sử dụng Thư viện Java gRPC để tạo 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>`

&lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ. Nếu bạn không có mã công việc trong hệ thống của mình, bạn có thể tạo mã 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá trị
    loại Type.SCHEDULED_STOP
    tiểu bang 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. Ném của Fleet Engine trường hợp ngoại lệ nếu yêu cầu bao gồm deliveryvehicleId được chỉ định. Bạn chỉ định công việc bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem Chỉ định 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 trong thời gian hoàn thành tác vụ. Ví dụ: nếu bạn truyền đạt một khoảng thời gian giao hàng đến người nhận, bạn có thể sử dụng thời gian mục tiêu của nhiệm vụ cửa sổ để ghi lại khoảng thời gian này và tạo cảnh báo hoặc phân tích sau chuyến đi hiệu suất bằng cách sử dụ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 bạn có thể đặt khoảng thời gian trên mọi loại tác vụ. Khoảng thời gian mục tiêu không ảnh hưởng đến việc định tuyến hành vi.

gRPC

Ví dụ sau đây minh hoạ cách sử dụng Thư viện Java gRPC để đặt khoảng thời gian cho 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`

&lt;id&gt; 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá 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 chế độ đị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

Chế độ hiển thị của 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 nhiệm vụ bằng cách đặt TaskTrackingViewConfig về nhiệm vụ đó. Xem Thao tác trên 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 công việc. 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 đây minh hoạ cách sử dụng Thư viện Java gRPC để đặt 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`

&lt;id&gt; 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá trị
    taskTrackingViewConfig Cấu hình để theo dõi công việc chỉ định những phần tử dữ liệu 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ự nhiệm vụ cho một chiếc xe được xác định theo danh sách số điểm dừng xe cho xe giao hàng và bạn có thể chỉ định một hoặc nhiều nhiệm vụ đến từng điểm dừng xe. Để biết thông tin chi tiết, hãy xem Cập nhật thứ tự tác vụ.

Để thay đổi một kiện hàng từ xe này sang xe khác, hãy đóng việc cần làm ban đầu sau đó tạo lại trước khi giao chiếc xe mới. Nếu bạn cập nhật việc cần làm sắp xếp một tác vụ đã được giao sang xe khác thì 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 xe được thực hiện từ một trong hai cách sau: thời gian 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 pháp để tránh điều kiện tương đồng 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 việc cần làm đã được giao trước đó cho xe nhưng hiện không thực hiện theo thứ tự mới.

Cách thay đổi một kiện hàng từ xe này sang xe khác: đóng tác vụ ban đầu sau đó tạo lại trước khi giao chiếc xe mới. Nếu bạn cập nhật việc cần làm sắp xếp một tác vụ đã được giao sang xe khác thì 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 đây minh hoạ cách sử dụng Thư viện Java gRPC để cập nhật thứ tự nhiệm 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ự nhiệm 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`

&lt;id&gt; là giá trị nhận dạng duy nhất của một xe giao hàng trong nhóm xe của bạn mà bạn dự định cập nhật thứ tự tác vụ. Đây chính là giá trị nhận dạng 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá 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.
    remainingVehicleJourneySegments[i].stop Điểm dừng của tác vụ i trong danh sách.
    remainingVehicleJourneySegments[i].stop.plannedLocation Vị trí đã lên kế hoạch cho điểm dừng.
    remainingVehicleJourneySegments[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 điều hướng. Bạn có thể thông báo cho Fleet Engine bằng SDK trình điều khiển, hoặc từ môi trường máy chủ bằng gRPC hoặc REST. Không sử dụng cả hai cách để tránh chủng tộc các điều kiện và để duy trì một nguồn đáng tin cậy duy nhất.

gRPC

Ví dụ sau đây minh hoạ 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 điể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ộ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`

&lt;id&gt; là giá trị nhận dạng duy nhất của xe giao hàng trong nhóm xe của bạn mà bạn dự định cập nhật thứ tự tác vụ. Đây chính là giá trị nhận dạng 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá 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 sử 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 để biết vị trí của xe. Đối với mọi xe đang hoạt động, Fleet Engine mong muốn cập nhật vị trí ít nhất một lần mỗi phút và tối đa là một lần mỗi 5 giây.

gRPC

Ví dụ sau đây minh hoạ cách sử dụng Thư viện Java gRPC cách cập nhật vị trí của 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`

&lt;id&gt; là giá trị nhận dạng duy nhất cho xe giao hàng trong hệ thống thiết bị hoặc mà bạn dự định cập nhật vị trí. Đây chính là giá trị nhận dạng 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá 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:

    TrườngGiá 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 Fleet Engine từ SDK trình điều khiển, hoặc từ môi trường máy chủ bằng gRPC hoặc REST. Không sử dụng cả hai cách để tránh chủng tộc các điều kiện và để duy trì một nguồn đáng tin cậy duy nhất.

gRPC

Ví dụ sau đây minh hoạ 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 một chiếc xe đến tại điểm dừng từ môi trường máy chủ, thực hiện lệnh gọi REST HTTP đến UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

&lt;id&gt; là giá trị nhận dạng duy nhất của xe giao hàng trong nhóm xe của bạn mà bạn dự định cập nhật thứ tự tác vụ. Đây chính là giá trị nhận dạng 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá trị
    remainingVehicleJourneySegments Điểm dừng bạn đã đến với trạng thái được đặt là State.ARRIVED, tiếp theo là 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.

  • 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 khiến tất cả công việc liên kết với điểm dừng sẽ được đặt thành trạng thái ĐÃ ĐÓNG CỬA. Bạn có thể thông báo cho Fleet Engine từ SDK trình điều khiển, 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 đây minh hoạ 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 trong môi trường máy chủ, thực hiện lệnh gọi REST HTTP đến UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`

&lt;id&gt; là giá trị nhận dạng duy nhất của xe giao hàng trong nhóm xe của bạn mà bạn dự định cập nhật thứ tự tác vụ. Đây chính là giá trị nhận dạng 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá 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 số lượng xe còn lại.

  • 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ả nhiệm vụ, thời gian kết quả nhiệm vụ, vị trí kết quả nhiệm vụ và các thuộc tính theo cập nhật trực tiếp thực thể tác vụ. Ví dụ: trong trường hợp một tác vụ chưa đã được giao cho một chiếc xe, bạn có thể đóng nhiệm vụ đó bằng cách cập nhật trạng thái trực tiếp.

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 chiếc xe, hãy thông báo cho Fleet Engine xe đã hoàn tất điểm dừng nơi thực hiện nhiệm vụ hoặc xoá địa điểm đó khỏi danh sách điểm dừng xe. Để làm được việc đó, bạn có thể đặt danh sách chiếc xe còn lại dừng lại ngay 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 việc cần làm đó sang 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 công việc không còn được coi là đang thực hiện. Để theo dõi quá trình vận chuyển, điều quan trọng là phải chỉ ra kết quả thực tế của một nhiệm vụ để phân phối kết quả có thể xuất hiện.

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`

&lt;id&gt; 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 trường Uỷ quyền có giá trị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá trị
    tiểu bang State.CLOSED

  • Các trường không bắt buộc:

    TrườngGiá 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à đến vị trí của chiếc xe cuối cùng 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 thành công hay thất bại mà cho biết rằng tác vụ sẽ không được xem là đang thực hiện nữa. Để theo dõi quá trình vận chuyển, điều quan trọng là phải chỉ ra kết quả thực tế của một nhiệm vụ để kết quả phân phối có thể được hiển thị và 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ả nhiệm vụ và vị trí kết quả nhiệm vụ sau khi đặt.

Có thể đặt kết quả cho những tác vụ ở trạng thái ĐÃ ĐÓNG CỬA thành: SUCCEEDED (ĐÃ THÀNH CÔNG) hoặc 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 (ĐÃ THÀNH CÔNG).

Khi đánh dấu kết quả của một nhiệm vụ, Fleet Engine sẽ tự động điền vào vị trí kết quả nhiệm vụ cùng với vị trí chiếc xe đã biết gần đây nhất. Bạn có thể ghi đè hành vi này.

gRPC

Bạn có tùy chọn để đặt vị trí kết quả tác vụ khi đặt kết quả. Việc đặt vị trí này sẽ không cho phép Fleet Engine thiết lập vị trí này về mặc định vị trí của xe. Bạn cũng có thể ghi đè vị trí kết quả nhiệm vụ Fleet Engine đặt sau này. 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ể đặt vị trí kết quả tác vụ cho một nhiệm vụ chưa đặt kết quả tác vụ. Bạn có thể đặt cả hai kết quả việc cần làm và vị trí kết quả tác vụ trong cùng một yêu cầu.

Ví dụ sau đây minh hoạ cách sử dụng Thư viện Java gRPC để đặt kết quả tác vụ thành SUCCEEDED và đặt vị trí tác vụ đã hoàn tất:

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)

Cách đánh dấu một công việc là đã hoàn thành từ môi trường máy chủ: thực hiện lệnh gọi REST HTTP đến UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`

&lt;id&gt; 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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:

    TrườngGiá trị
    taskOutcome Outcome.SUCCEEDED hoặc Outcome.FAILED.

  • Các trường không bắt buộc:

    TrườngGiá 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 đặt mặc định vị trí 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 cài đặt kết quả rồi tạo một nhiệm vụ mới với vị trí dự kiến đã 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 việc cần làm.

Sử dụng xe trung chuyển và xe giao hàng

Nếu bạn sử dụng xe trung chuyển để vận chuyển lô hàng đến xe giao hàng suốt cả ngày, lập mô hình việc chuyển hàng dưới dạng tác vụ ngừng giao theo lịch trình cho xe giao hàng. Để đảm bảo theo dõi vị trí chính xác, hãy chỉ định nhiệm vụ giao hàng cho một lô hàng đã chuyển sau khi nó được xếp 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 hoàn tất nhiệm vụ vận chuyển, trạng thái và kết quả của nhiệm vụ sẽ được ghi lại trong tác vụ. Tuy nhiên, bạn nên cập nhật các siêu thông tin khác cho lô hàng. Để lưu trữ các siêu thông tin 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 được liên kết với công việc là 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 đây minh hoạ cách sử dụng Thư viện Java gRPC để tra cứu một chiếc 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)

Cách tra cứu xe từ môi trường máy chủ: thực hiện lệnh gọi REST HTTP đến GetVehicle:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`

&lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ.

&lt;vehicleId&gt; 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ị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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 công việc.

gRPC

Ví dụ sau đây minh hoạ cách sử dụng Thư viện Java gRPC để tra cứu một việc cần làm:

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 công việc từ môi trường máy chủ, thực hiện lệnh gọi REST HTTP đến GetTask:

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

&lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ.

&lt;taskId&gt; là mã nhận dạng của việc cần làm cần tra cứu.

Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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ề nhiệm vụ vận chuyển theo các cách sau, mỗi yếu tố có một mục đích riêng biệt:

  • theo mã công việc: được sử dụng bởi những người dùng như nhà vận hành đội xe có quyền truy cập vào chế độ xem toàn bộ dữ liệu công việc.
  • bằng mã theo dõi: được phần mềm khách của bạn sử dụng để cung cấp thông tin cho người dùng cuối, chẳng hạn như thời điểm dự kiến nhận được 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 việc cần làm theo mã công việc, hãy chuyển đến phần Tra cứu việc cần làm.

Để 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ề khả năng hiển thị nêu trong 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. Tài xế SDK không hỗ trợ hoạt động tra cứu thông tin theo mã theo dõi. Cách thực hiện việc này bằng Fleet Công cụ, bạ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 phân phối của Fleet Engine Deliveries chỉ thông tin có liên quan đến người dùng cuối đó, chẳng hạn như người giao hàng hoặc người nhận gói hàng. 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 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 đây minh hoạ 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.

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 công việc vận chuyển qua trình duyệt, hãy thực hiện lệnh gọi HTTP REST để GetTaskTrackingInfo:

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

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

Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Thẻ <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 một taskTrackingInfo thực thể.

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ợ tác vụ liệt kê.

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 Xác thực người dùng siêu phân phối Mã thông báo 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. Đối với cú pháp truy vấn lọc, hãy xem AIP-160. Danh sách sau đây cho thấy tác vụ hợp lệ những thuộc tính mà bạn có thể dùng để lọc:

  • attributes
  • delivery_vehicle_id
  • tiểu bang
  • 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
Enum Chuỗi state = CLOSED AND type = PICKUP
Vị trí point.latitude và point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

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

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 chỉ định kích thước trang, số lượng tác vụ được trả về sẽ không lớn hơn so với kích thước trang được chỉ định. Nếu không có kích thước trang thì đặt mặc định hợp lý sẽ được sử dụng. Nếu kích thước trang được yêu cầu vượt quá giá trị tối đa nội bộ, thì giá trị tối đa nội bộ sẽ được sử dụng.

Danh sách việc cần làm có thể chứa mã thông báo để đọc trang kết quả tiếp theo. Sử dụng mã thông báo trang với một yêu cầu hoàn toàn giống với yêu cầu trước đó để truy xuất trang công việc tiếp theo. Khi mã thông báo trang được trả về trống, không có thêm tác vụ nào để truy xuất.

gRPC

Ví dụ sau đây minh hoạ cách sử dụng Thư viện Java gRPC để liệt kê các nhiệm vụ cho deliveryvehicleId và thuộc tính nhiệm vụ. Một phản hồi vẫn có thể trống. Phản hồi trống cho biết rằng không có Tasks nào có liên kết với deliveryvehicleId mà bạn 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 những việc cần làm trong danh sách, hãy thêm "bộ lọc" Tham số URL có truy vấn bộ lọc thoát URL làm giá trị.

Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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 rằng không có đã tìm thấy tác vụ đá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. Tài xế SDK không hỗ trợ việc đăng thông tin về xe giao hàng.

Phương tiện giao hàng trang thông tin yêu cầu quyền tiếp cận rộng rãi vào xe giao hàng và chỉ dành cho người dùng đáng tin cậy. Dùng Reader Fleet Reader hoặc Delivery Fleet Mã thông báo xác thực người dùng khi đưa ra yêu cầu về xe giao hàng trong danh sách.

Xe giao hàng trong danh sách có các trường sau đây bị loại bỏ do tác động của chúng về 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ọ. Cho Ví dụ: để truy vấn một thuộc tính có 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 thông qua các toán tử logic AND và OR như trong attributes.key1 = value1 AND attributes.key2 = value2. Xem AIP-160 để biết toàn bộ nội dung mô tả cú pháp truy vấn lọc.

Bạn có thể lọc các phương tiện giao hàng có trong danh sách theo địa điểm bằng cách sử dụng yêu cầu viewport . Tham số yêu cầu viewport xác định khung nhìn bằng cách sử dụng hai giới hạn toạ độ: vĩ độ và kinh độ high (đông bắc) và low (tây nam) cặp toạ độ. Yêu cầu bị từ chối nếu có vĩ độ cao vùng địa lý thấp hơn vĩ độ 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, thì yêu cầu chỉ trả về số lượng xe được chỉ định bởi giới hạn hoặc ít hơn. Nếu kích thước trang được yêu cầu vượt quá kích thước nội bộ giá trị tối đa, thì giá trị tối đa nội bộ sẽ được sử dụng. Trang mặc định và tối đa đều có kích thước là 100 xe.

Danh sách phương tiện giao hàng có thể chứa một mã thông báo để đọc trang tiếp theo của kết quả. Mã thông báo trang chỉ xuất hiện trong phản hồi khi có thêm trang phân phối phương tiện để truy xuất. Để truy xuất trang tiếp theo của việc cần làm, 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 đó của bạn.

gRPC

Ví dụ sau đây minh hoạ cách sử dụng Thư viện Java gRPC để đăng xe giao hàng trong một khu vực cụ thể có thuộc tính nhất định. Đáp 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 những xe có thuộc tính được chỉ định đã có 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 những việc cần làm trong danh sách, hãy thêm "bộ lọc" URL có thuộc tính Truy vấn bộ lọc dùng ký tự thoát URL làm giá trị.

Tiêu đề yêu cầu phải chứa một trường Uỷ quyền có giá trị Mã thông báo mang mã <token>, trong đó <token> là mã thông báo do nhà máy sản xuất 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 phương tiện giao hàng đáp ứng truy vấn bộ lọc và khung nhìn đượ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 quá trình vận chuyển

Bạn có hai lựa chọn sử dụng API Fleet Engine Deliveries để theo dõi quá trình vận chuyển:

  • Ưu tiên: Hãy sử dụng Thư viện Theo dõi vận chuyển JavaScript. Thư viện cho phép bạn minh hoạ trực quan vị trí của xe và địa điểm được quan tâm trong Fleet Engine. Tệp này chứa thành phần bản đồ JavaScript là lệnh 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 mang đến trải nghiệm theo dõi quá trình vận chuyển có thể tuỳ chỉnh được trên web hoặc ứng dụng di động.

  • Triển khai tính năng theo dõi lô hàng của riêng bạn trên Fleet Engine Deliveries API.

Điều quan trọng là tra cứu nhiệm vụ vận chuyển bằng mã theo dõi.

Nếu bạn sử dụng Vai trò người tiêu dùng phân phối, thì mọi lệnh gọi API Fleet Engine Deliveries chỉ trả lại thông tin có liên quan cho người gửi hàng hoặc người nhận. Tất cả giá trị khác thông tin trong các câu trả lời bị loại bỏ. Bạn có trách nhiệm để xác thực người dùng cuối. Ngoài ra, thông tin vị trí sẽ được lọc dựa trên tác vụ đã thực hiện. Trong khi thực hiện nhiệm vụ không có sẵn, thông tin vị trí sẽ không được chia sẻ với người dùng cuố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, xem Ghi nhật ký.

Vai trò và mã thông báo uỷ quyền

Như mô tả trong bài viết Quản lý vòng đời của xe và công việc và ghi chú uỷ quyền cho từng trường hợp sử dụng, giúp các lệnh gọi đến Fleet Engine yêu cầu xác thực bằng Mã thông báo web JSON có đã được ký bằng thông tin xác thực tài khoản dịch vụ. Tài khoản dịch vụ được sử dụng để phát hành những mã thông báo đó có thể có một hoặc nhiều vai trò, với mỗi vai trò sẽ được cấp một nhóm quyền khác.

Để biết thêm thông tin, hãy xem 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 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 có thể hồi phục nếu có lỗi. Ví dụ: khi Fleet Engine cố gắng cập nhật một chiếc xe có thể phản hồi với thông báo lỗi cho biết chiếc 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ù sự cố này hiếm khi xảy ra, hãy đảm bảo rằng hệ thống của bạn có đủ khả năng phục hồi để xử lý nó.

Trong một tình huống hiếm gặp là sự cố thảm khốc xảy ra với Fleet Engine, bạn có thể cần phải tạo lại hầu hết hoặc tất cả xe 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 làm chậm tốc độ tạo lại bằng chiến lược thời gian đợi cho lần 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 công việc để đảm bảo chúng tồn tại và khôi phục trạng thái hiện tại của chúng. Ứng dụng cũng sẽ tạo lại và đặt rõ danh sách các đ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ến hành như bình thường, đánh dấu việc đến điểm dừng, hoàn thành công việc và các chi tiết khác. Nếu bạn không làm như vậy, hệ thống có thể trở nên không nhất quán và 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.