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 của nhóm thiết bị cho chặng giao hàng đầu tiên và dặm cuối cùng bằng Fleet Engine Deliveries API. Bạn có thể sử dụng API này bằng cách dùng SDK trình điều khiển cho Android và iOS, hoặc trực tiếp bằng cách dùng các lệnh gọi HTTP REST hoặc gRPC.

Thiết lập ban đầu

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

  • Để biết thông tin về các bước cần thực hiện trong bảng điều khiển và cách tạo Mã thông báo web JSON để uỷ quyền, hãy xem phần Xác thực và uỷ quyền.

  • Để biết thông tin chi tiết về cách sử dụng bảng điều khiển này, vui lòng xem tài liệu về Google Cloud Console.

Xác minh thông tin thiết lập của bạn

Sau khi tạo tài khoản dịch vụ, hãy xác minh rằng quá trình thiết lập đã hoàn tất và bạn có thể tạo xe giao hàng. Việc 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 thiết lập dự án. Có hai 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 các thư viện ứng dụng bằng một số ngôn ngữ lập trình phổ biến. Để biết hướng dẫn về cách lấy thư viện ứng dụng cho ứng dụng máy chủ của bạn, hãy xem phần Thư viện ứng dụng.

Các ví dụ về Java trong tài liệu này giả định rằng bạn đã quen thuộc với gRPC.

Cấu trúc dữ liệu

Fleet Engine Deliveries API sử dụng hai cấu trúc dữ liệu để lập mô hình cho quá trình đến lấy hàng và giao hàng:

  • Xe giao hàng dùng để vận chuyển kiện hàng.
  • Các nhiệm vụ lấy hàng và giao hàng.

Bạn cũng sử dụng các nhiệm vụ để lập mô hình thời gian nghỉ của người lái xe và điểm dừng theo lịch trong suốt cả ngày.

Xe giao hàng

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

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

Tasks

Đối với các hành động mà một chiếc xe thực hiện trong ngày, bạn giao nhiệm vụ theo loại hành động:

  • Đối với tính năng đến lấy hàng và giao hàng, hãy giao Nhiệm vụ vận chuyển.
  • Đối với những thời điểm người lái xe không rảnh (chẳng hạn như nghỉ giải lao), hãy chỉ định Nhiệm vụ khi người lái xe không rảnh.
  • Đối với các tác vụ không phải lái xe tại hộp thả xuống hoặc địa điểm của khách hàng, hãy chỉ định Các tác vụ dừng theo lịch.

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

Để tạo nhiệm vụ trong Fleet Engine, hãy dùng Trình quản lý tác vụ SDK trình điều khiển.

Nhiệm vụ vận chuyển

Tạo nhiệm vụ vận chuyển cho cả tính năng lấy hàng và giao hàng, đồng thời cung cấp những thông tin sau:

  • Địa điểm đến lấy hàng hoặc giao hàng.
  • Số theo dõi hoặc mã theo dõi.
  • Thời gian dừng để tính đến thời gian bổ sung nhằm hoàn thành tác vụ, tìm chỗ đỗ 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ụ không có sẵn

Nhiệm vụ không có sẵn sử dụng bao gồm các khoảng thời gian khi không có xe để đến lấy hàng hoặc giao hàng, chẳng hạn như giờ nghỉ tiếp nhiên liệu xe hoặc nghỉ ngơi cho người lái xe.

Tạo một tác vụ không có trạng thái thực hiện bằng những thông tin sau:

  • Thời lượng của điểm chèn quảng cáo.
  • Vị trí chèn quảng cáo (không bắt buộc). Bạn không cần phải cung cấp một vị trí cụ thể, nhưng làm như vậy sẽ giúp cửa sổ ETA chính xác hơn trong suốt cả ngày.

Để biết thêm thông tin, hãy xem các chủ đề sau:

Android

iOS

Các tác vụ cần dừng theo lịch

Tạo các nhiệm vụ dừng theo lịch để lập mô hình các điểm dừng mà xe giao hàng cần thực hiện. Ví dụ: tạo một tác vụ dừng theo lịch cho điểm dừng thu thập được lên lịch hằng ngày tại một vị trí cụ thể, không phụ thuộc vào các đợt giao hàng hoặc đến lấy hàng khác ở cùng vị trí đó. Bạn cũng có thể tạo các nhiệm vụ dừng theo lịch cho các bộ sưu tập từ hộp thả xuống hoặc đến hoạt động chuyển xe trung chuyển mô hình hoặc dừng tại các 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 sau về nội dung và định dạng:

  • Tạo mã công việc duy nhất
  • Đừng cung cấp bất kỳ thông tin nhận dạng cá nhân (PII) hoặc dữ liệu văn bản rõ ràng nào.
  • Sử dụng chuỗi Unicode hợp lệ.
  • Hãy sử dụng từ 64 ký tự trở xuống.
  • Đừng dùng bất cứ 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ã công việc phù hợp:

  • 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
  • e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
  • NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk

Bảng sau đây trình bày ví dụ về những 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ề 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.
4R0oXLToF"112 Mùa hè Tiến sĩ East Arthurford, CT06118"577b484da26f8a Vi phạm các yêu cầu về ký tự và thông tin nhận dạng cá nhân (PII): khoảng trắng, dấu phẩy và dấu ngoặc kép. Dài hơn 64 ký tự.

Tài nguyên khác

Để xem các trường cụ thể có trong từng cấu trúc dữ liệu, hãy xem tài liệu tham khảo API cho DeliveryVehicle (gRPC, REST) và Task (gRPC, REST).

Vòng đời của xe

Đối tượng DeliveryVehicle đại diện cho xe giao hàng dặm đầu tiên hoặc dặm cuối cùng. Bạn tạo một đối tượng DeliveryVehicle bằng:

  • Mã dự án của dự án trên Google Cloud chứa tài khoản dịch vụ dùng để gọi các API Fleet Engine.
  • Mã xe của khách hàng.

Sử dụng mã xe riêng biệt cho từng chiếc xe. Đừng sử dụng lại mã xe trừ phi không có nhiệm vụ nào đang hoạt động cho xe gốc.

Fleet Engine sẽ tự động xoá các đối tượng DeliveryVehicle chưa được cập nhật bằng UpdateDeliveryVehicle sau 7 ngày. Cách xem xe có tồn tại hay không:

  1. Gọi điện đến số UpdateDeliveryVehicle.
  2. Nếu bạn gặp lỗi NOT_FOUND, hãy gọi CreateDeliveryVehicle để tạo lại xe. Nếu cuộc gọi trả lại một chiếc xe, thì chiếc xe đó vẫn có sẵn để cập nhật.

Loại phương tiện

Thực thể VehicleType chứa trường VehicleType không bắt buộ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 thiết lập trường này, thì trường này sẽ mặc định là AUTO.

Tất cả hoạt động định tuyến cho xe đều 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 của DeliveryVehicleAttribute. API ListDeliveryVehicles bao gồm một trường filter có thể giới hạn các thực thể DeliveryVehicle được trả về ở những thực thể có thuộc tính đã chỉ định. DeliveryVehicleAttribute không ảnh hưởng đến hành vi định tuyến của Fleet Engine.

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

Vòng đời của một tác 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 Deliveries API gRPC hoặc REST.

Đối tượng Task có trường trạng thái để theo dõi tiến trình của đối tượng trong suốt vòng đời của đối tượng đó. Giá trị di chuyển từ MỞ sang ĐÃ ĐÓNG. Các tác vụ mới được tạo ở trạng thái MỞ cho biết rằng:

  • Nhiệm vụ chưa được giao cho xe giao hàng.
  • Xe giao hàng chưa vượt 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 một chiếc xe khi nó ở trạng thái MỞ.

Bạn huỷ một nhiệm vụ bằng cách xoá nhiệm vụ đó khỏi danh sách điểm dừng xe. Thao tác này sẽ tự động đặt trạng thái tác vụ thành ĐÃ ĐÓNG.

Khi xe của nhiệm vụ hoàn thành điểm dừng xe của nhiệm vụ đó:

  1. Cập nhật trường kết quả của nhiệm vụ thành SUCCEEDED hoặc FAILED.

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

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

Tương tự như xe, Fleet Engine sẽ xoá các nhiệm vụ chưa được cập nhật sau 7 ngày. Nếu bạn cố gắng tạo một nhiệm vụ bằng mã đã tồn tại, thì hệ thống sẽ trả về 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ụ này tự động xoá các công việc sau 7 ngày mà không cần cập nhật. Nếu 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 tính năng đó.

Thuộc tính việc cần làm

Thực thể Task chứa trường lặp lại TaskAttribute. Trường này có thể có giá trị từ một trong 3 loại: chuỗi, số và bool. API ListTasks bao gồm một trường filter có thể giới hạn các thực thể Task được trả về ở những thực thể có thuộc tính đã chỉ định. Thuộc tính tác vụ không ảnh hưởng đến hành vi định tuyến của Fleet Engine.

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

Quản lý vòng đời của xe và nhiệm vụ

Lưu ý: Hệ thống nội bộ của bạn đóng vai trò là nguồn dữ liệu đáng tin cậy mà Fleet Engine Deliveries API thay mặt bạn sẽ tăng cường.

Để quản lý vòng đời của xe và nhiệm vụ trong hệ thống, hãy sử dụng Fleet Engine Deliveries API để tạo, cập nhật và theo dõi xe của bạn cũng như các nhiệm vụ liên quan.

Đồng thời, ứng dụng dành cho người lái xe sẽ giao tiếp trực tiếp với Fleet Engine để cập nhật thông tin về vị trí của thiết bị và tuyến đường. Mô hình này cho phép Fleet Engine quản lý hiệu quả thông tin vị trí theo thời gian thực. Đối tượng này trực tiếp gửi vị trí đến thư viện theo dõi. Sau đó, bạn có thể sử dụng thư viện này để cập nhật trạng thái đơn đặt hàng của người tiêu dùng.

Ví dụ: giả sử bạn gặp phải trường hợp sau:

  • Một người lái xe đến gần một trạm giao hàng. Ứng dụng trình điều khiển sẽ gửi thông tin vị trí đến Fleet Engine.
  • Fleet Engine gửi thông tin vị trí thiết bị đến thư viện theo dõi. Ứng dụng của bạn sẽ sử dụng thư viện này để thông báo cho người dùng về độ gần của gói hàng.
  • Sau khi người lái xe hoàn tất quá trình vận chuyển, họ sẽ nhấp vào nút "Đã giao hàng" trên ứng dụng của trình điều khiển.
  • Thao tác "Đã giao hàng" sẽ gửi thông tin đến hệ thống phụ trợ của bạn. Hệ thống này sẽ thực hiện các bước xác thực và xác minh hoạt động kinh doanh cần thiết.
  • Hệ thống xác nhận nhiệm vụ là SUCCEEDED và cập nhật Fleet Engine bằng cách sử dụng API giao hàng.

Sơ đồ dưới đây minh hoạ các quy trình này ở mức độ chung. Tệp này cũng cho thấy mối quan hệ tiêu chuẩn giữa hệ thống, ứng dụng khách và Fleet Engine.

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

Quản lý mã thông báo ứng dụng

Thông tin cập nhật vị trí bắt nguồn từ ứng dụng của người lái xe và được gửi trực tiếp đến Fleet Engine cần có mã thông báo uỷ quyền. Dưới đây là phương pháp đề xuất để xử lý các bản cập nhật từ ứng dụng cho Fleet Engine:

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

  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 thông tin vị trí thiết bị trong Fleet Engine.

Phương pháp này đảm bảo rằng các lệnh gọi bắt nguồn từ thiết bị di động (được coi là môi trường ít tin cậy) tuân thủ nguyên tắc về đặc quyền tối thiểu.

Các vai trò khác đối với tài khoản dịch vụ

Thay vào đó, nếu muốn cho phép các ứng dụng của người lái xe cập nhật trực tiếp Fleet Engine ngoài những cập nhật chỉ dành cho vai trò Người lái xe không tin cậy, chẳng hạn như để cập nhật một số tác vụ, bạn có thể sử dụng vai trò Người lái xe đáng tin cậy. Để biết thông tin về mô hình sử dụng vai trò Người lái xe đáng tin cậy, hãy xem phần Mô hình Người lái xe đáng tin cậy.

Để biết thêm thông tin về cách sử dụng các vai trò của người lái xe không đáng tin cậy và đáng tin cậy, hãy xem nội dung Thiết lập dự án trên Google Cloud.

Lập mô hình một ngày làm việc

Bảng sau đây mô tả hoạt động của một ngày làm việc đối với những người lái xe đi đầu hoặc cuối cùng tại một công ty giao hàng và hậu cần. Công ty của bạn có thể có thông tin chi tiết khác nhau, nhưng bạn có thể xem cách mình 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 giao hàng cho xe hoặc tuyến đường giao hàng. Bạn có thể tạo trước các nhiệm vụ giao hàng, đến lấy hàng, nghỉ giải lao và các nhiệm vụ khác trong Fleet Engine. Ví dụ: Bạn có thể tạo các nhiệm vụ lấy hàng, nhiệm vụ giao hàng, không có hàng theo lịch hoặc điểm dừng theo lịch.

Phân công nhiệm vụ cho xe sau khi hoàn tất các gói hàng giao và thứ tự giao các gói hàng.
Đầu ngày Tài xế bắt đầu ngày mới tại kho chứa bằng cách đăng nhập vào ứng dụng Driver. Khởi chạy API Trình điều khiển phân phối. Tạo xe giao hàng trong Fleet Engine nếu cần.
Tài xế tải các lô hàng lên xe giao hàng, quét tìm các lô hàng. Nếu bạn không tạo trước nhiệm vụ giao hàng, hãy 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 việc cần làm. Nếu các yêu cầu này không được tạo trước, hãy tạo nhiệm vụ lấy hàng, tình trạng không có hàng theo lịch và điểm dừng theo lịch.
Người lái xe rời khỏi kho và cam kết cần hoàn thành một số nhiệm vụ tiếp theo. Giao tất cả nhiệm vụ hoặc một nhóm nhỏ nhiệm vụ cho xe bằng cách cam kết 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 xe đang đến điểm dừng. Sau khi giao hàng, hãy đóng tác vụ giao hàng và chọn trạng thái vận chuyển tại cửa hàng và các thông tin meta khác (không bắt buộ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 đến điểm dừng tiếp theo, hãy thực hiện các hành động liên quan đến việc xe hoàn thành điểm dừng và xe đang lên đường đến điểm dừng tiếp theo.
Người lái xe gặp một xe trung chuyển để chuyển các lô hàng bổ sung lên xe giao hàng. Điểm gặp gỡ giữa phương tiện giao hàng và xe giao hàng phải được mô hình hoá dưới dạng điểm dừng theo lịch.

Sau khi chuyển và quét các lô hàng, hãy tạo nhiệm vụ giao hàng nếu bạn chưa tạo. Sau đó, hãy cập nhật thứ tự hoàn thành công việc bằng cách giao nhiệm vụ cho một xe và cập nhật thứ tự nhiệm vụ.
Người lái xe nhận được thông báo về yêu cầu đến lấy hàng. Sau khi chấp nhận yêu cầu đến lấy hàng, hãy tạo nhiệm vụ đến lấy hàng. Sau đó, hãy cập nhật thứ tự thực hiện tác vụ bằng cách chỉ định nhiệm vụ cho một xe và cập nhật thứ tự tác vụ.
Trưa Tài xế nghỉ ăn trưa. Nếu một vị trí được liên kết với nhiệm vụ không có sẵn, hãy xem vị trí đó giống như bất kỳ nhiệm vụ nào khác. Thực hiện các hành động liên quan đến việc xe đang đến tại điểm dừng, xe hoàn tất một điểm dừng và xe đang trên đường đến điểm dừng tiếp theo.

Nếu không, bạn không cần làm gì thêm cho đến khi kết thúc phiên chèn quảng cáo. Xoá tác vụ bằng cách xác nhận các tác vụ tiếp theo và các tác vụ còn lại, đồng thời cập nhật thứ tự tác vụ.
Tài xế đến lấy kiện hàng. Địa điểm này được mô hình hoá giống như một điểm dừng giao hàng. Thực hiện các thao tác liên quan đến xe đang đến điểm dừng và đóng một nhiệm vụ cũng như lưu trữ trạng thái vận chuyển cũng như các thông tin meta khác (không bắt buộ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 đến điểm dừng tiếp theo, hãy thực hiện các hành động liên quan đến việc xe hoàn tất một điểm dừng và xe đang lên đường đến điểm dừng tiếp theo. Lưu ý: Để đảm bảo việc thanh toán chính xác, tất cả đơn đặt hàng tự đến lấy phải có một nhiệm vụ giao hàng tương ứng. Nếu tính năng đến lấy hàng được giao đến một vị trí khác trên cùng tuyến đường của tài xế vào ngày hôm đó, bạn nên lập mô hình tác vụ giao hàng đó như mọi tác vụ giao hàng khác trên tuyến đường. Nếu người lái xe đang đưa đơn hàng đến lấy hàng trở lại kho, bạn nên tạo tác vụ giao hàng tại điểm đến của kho.
Người lái xe dừng lại theo lịch để lấy kiện hàng từ thùng chứa hàng. Điểm này được mô hình hoá giống như mọi điểm đến lấy hàng khác. Thực hiện các hành động liên quan đến xe đang đến điểm dừng và đóng một nhiệm vụ. Sau khi hoàn thành tất cả các nhiệm vụ tại điểm dừng và bắt đầu lái đến điểm dừng tiếp theo, hãy thực hiện các hành động liên quan đến việc xe hoàn tất một điểm dừng và xe đang lên đường đến điểm dừng tiếp theo.
Người lái xe sẽ nhận được thông báo về việc một lô hàng đang được chuyển đến một địa điểm khác. Đặt trạng thái của nhiệm vụ giao hàng ban đầu thành COMPLETED (ĐÃ HOÀN TẤT) rồi tạo một nhiệm vụ giao hàng mới cho vị trí giao hàng mới. Để biết thêm thông tin, hãy xem phần Định tuyến lại quá trình vận chuyển.
Tài xế đã cố gắng giao kiện hàng nhưng không thành công. Giá trị này được mô hình hoá tương tự như một điểm dừng phân phối thành công, đánh dấu tác vụ phân phối là đã hoàn thành. Thực hiện các hành động liên quan đến xe đang đến trạm dừng. Nếu không giao được lô hàng, hãy đóng tác vụ và chọn trạng thái vận chuyển tại cửa hàng cũng như các thông tin meta khác (không bắt buộ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 đến điểm dừng tiếp theo, hãy thực hiện các hành động liên quan đến việc xe hoàn tất một điểm dừng và xe đang lên đường đến điểm dừng tiếp theo.
Người lái xe được thông báo đang chờ (không giao) một kiện hàng. Sau khi nhận và xác nhận thông báo, hãy đặt trạng thái của tác vụ thành COMPLETED (ĐÃ HOÀN TẤT).
Tài xế nhận được thông báo giao một lô hàng cụ thể tiếp theo, điều này làm thay đổi đơn đặt hàng giao hàng đã cam kết. Cập nhật thứ tự tác vụ.
Người lái xe chọn giao một lô hàng không đúng đơn đặt hàng. Cập nhật thứ tự tác vụ rồi tiến hành như bình thường.
Tài xế giao nhiều lô hàng đến một địa điểm duy nhất. Điểm này được mô hình hoá tương tự như một điểm dừng 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 một xe đang đến điểm dừng. Sau khi giao từng kiện hàng, hãy đóng từng nhiệm vụ và chọn trạng thái vận chuyển tại cửa hàng và các thông tin meta khác (không bắt buộ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 đến điểm dừng tiếp theo, hãy thực hiện các hành động liên quan đến việc xe hoàn tất một điểm dừng và xe đang lên đường đến điểm dừng tiếp theo.
Cuối ngày Tài xế quay trở lại kho chứa. Nếu người lái xe quay trở lại kho hàng với các kiện hàng được lấy trong tuyến đường của họ, bạn cũng phải tạo và đóng từng gói hàng làm nhiệm vụ giao hàng để đảm bảo việc thanh toán chính xác. Bạn có thể thực hiện việc này bằng cách lập mô hình kho hàng như mọi điểm dừng giao hàng khác. Nếu kho hàng không được dùng làm điểm dừng giao hàng, bạn vẫn có thể tuỳ ý lập mô hình kho hàng thành điểm dừng theo lịch biểu. Việc lập mô hình điểm dừng cho phép tài xế xem tuyến đường trở lại kho và cung cấp thông tin về thời gian đến dự kiến.

Cách hoạt động của thông tin cập nhật về vị trí

Để Fleet Engine đạt hiệu suất tốt nhất, hãy cung cấp cho dịch vụ một luồng thông tin cập nhật về vị trí của xe. Sử dụng một trong những cách sau để cung cấp các nội dung 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ã tuỳ chỉnh – hữu ích nếu vị trí được chuyển tiếp thông qua phần phụ trợ hoặc nếu bạn sử dụng các thiết bị không phải Android hoặc iOS.

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

Trạm dừng xe và địa điểm giao hàng

Trạm dừng xe là nơi xe giao hàng hoàn thành một nhiệm vụ vận chuyển hoặc một nhiệm vụ khác. Đó là một điểm truy cập, chẳng hạn như đế tải hoặc vị trí gặp đường.

Vị trí giao hàng là nơi hàng được giao hoặc đến lấy hàng. Bạn có thể phải đi bộ một chút từ điểm dừng của xe để đến và đi từ địa điểm giao hàng.

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

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

Ví dụ: nếu một tài xế đang giao hàng nhiều lần đến một toà nhà văn phòng, hãy cân nhắc việc chỉ định tất cả nhiệm vụ giao hàng cho một điểm dừng xe. Nếu mỗi nhiệm vụ giao hàng được chỉ định cho điểm dừng xe riêng, thì trải nghiệm theo dõi quá trình vận chuyển sẽ không giúp ích được cho người dùng vì tính năng theo dõi chỉ hoạt động khi xe đã dừng ở một số điểm dừng xe nhất định trước điểm đến. Việc hoàn thành nhiều điểm dừng xe trong một thời gian ngắn không mang lại cho người dùng nhiều thời gian để theo dõi tiến trình giao hàng.

Sử dụng SDK di động

Trước khi bạn thực hiện bất kỳ lệnh gọi nào đến SDK trình điều khiển, hãy nhớ khởi chạy SDK đó.

Khởi chạy API Trình điều khiển phân phối

Trước khi khởi chạy API Trình điều khiển phân phối trong SDK trình điều khiển, hãy nhớ khởi động SDK Điều hướng. Sau đó, hãy khởi chạy API Trình điều khiển phân phối như 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 Deliveries API để 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 các giá trị nhận dạng thực thể duy nhất dùng trong các 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 giá trị nhận dạng không chứa bất kỳ thông tin nhận dạng cá nhân (PII), chẳng hạn như số điện thoại của người lái xe.

Tạo xe

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 cách sử dụng gRPC hoặc REST.

gRPC

Để tạo một chiếc xe mới, hãy thực hiện lệnh gọi CreateDeliveryVehicle đến Fleet Engine. Sử dụng đối tượng CreateDeliveryVehicleRequest để xác định các thuộc tính của xe giao hàng mới. Lưu ý rằng mọi giá trị được chỉ định cho trường Name đều bị bỏ qua theo hướng dẫn API cho 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 cho xe.

Khi tạo DeliveryVehicle, bạn có thể tuỳ ý chỉ định các trường sau:

  • Thuộc tính
  • LastLocation
  • Loại

Đừ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ề một lỗi vì các trường đó ở chế độ chỉ có thể đọ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 đặt bất kỳ trường không bắt buộc nào, bạn có thể không đặt trường DeliveryVehicle trong CreateDeliveryVehicleRequest.

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo 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>

<id> là giá trị nhận dạng duy nhất của xe giao hàng trong nhóm thiết bị của bạn.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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 về API đối với mã nhận dạng do người dùng chỉ định. Đừ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ề một lỗi vì các trường đó ở chế độ chỉ có thể đọc hoặc chỉ có thể được cập nhật bằng cách sử dụng lệnh gọi đến UpdateDeliveryVehicle.

Để tạo một chiếc xe mà không cần cài đặt bất kỳ trường nào, hãy để trống phần nội dung của yêu cầu POST. Sau đó, xe mới tạo sẽ trích xuất mã xe từ tham số deliveryVehicleId trong URL POST.

Ví dụ về lệnh curl:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}"

Tạo nhiệm vụ đến lấy hàng

Bạn có thể tạo tác vụ nhận kiện hàng từ SDK trình điều khiển hoặc từ môi trường máy chủ bằng cách sử dụng gRPC hoặc REST.

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo một nhiệm vụ nhận 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.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ụ nhận hà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>`

<id> là giá trị nhận dạng duy nhất của công việc. Đây không được là số theo dõi của lô hàng. Nếu không có mã công việc trong hệ thống, bạn có thể tạo một giá trị nhận dạng duy nhất (UUID).

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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
    state State.OPEN
    trackingId Số hoặc mã nhận dạng mà bạn đang dùng để theo dõi quá trình vận chuyển.
    plannedLocation Vị trí mà công việc cần hoàn thành, trong trường hợp này là vị trí đến lấy hàng.
    taskDuration Thời gian dự kiến tính bằng giây để nhận kiện hàng tại địa điểm nhận 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 việc cần làm. Đ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 Việc cần làm. Mỗi thuộc tính phải có một khoá duy nhất.

Tất cả các trường khác trong thực thể đều bị bỏ qua khi tạo. Fleet Engine sẽ gửi một trường hợp ngoại lệ nếu yêu cầu có deliveryVehicleId được chỉ định. Bạn giao việc cần làm bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Giao nhiệm vụ cho một chiếc xe và UpdateDeliveryVehicleRequest.

Ví dụ về lệnh curl:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "PICKUP",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Tạo nhiệm vụ giao hàng

Tạo tác vụ phân phối lô hàng từ SDK trình điều khiển hoặc từ môi trường máy chủ bằng cách sử dụng gRPC hoặc REST.

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo một tác vụ phân phối lô hàng:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

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

Để tạo tác vụ phân phối lô hàng từ môi trường máy chủ bằng gRPC hoặc REST, hãy thực hiện lệnh gọi HTTP REST đến CreateTask:

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

<id> là giá trị nhận dạng duy nhất của công việc. Đây không được là số theo dõi của lô hàng. Nếu không có mã công việc trong hệ thống, bạn có thể tạo một giá trị nhận dạng duy nhất (UUID).

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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
    state State.OPEN
    trackingId Số hoặc mã nhận dạng mà bạn đang dùng để theo dõi quá trình vận chuyển.
    plannedLocation Vị trí mà công việc cần hoàn thành, trong trường hợp này là vị trí giao hàng của lô hàng này.
    taskDuration Thời gian dự kiến (tính bằng giây) để giao hàng tại địa điểm giao hàng.

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

    TrườngGiá trị
    targetTimeWindow Khoảng thời gian hoàn thành việc cần làm. Đ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 Việc cần làm. Mỗi thuộc tính phải có một khoá duy nhất.

Tất cả các trường khác trong thực thể đều bị bỏ qua khi tạo. Fleet Engine sẽ gửi ra một trường hợp ngoại lệ nếu yêu cầu bao gồm deliveryvehicleId được chỉ định. Bạn giao việc cần làm bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Giao nhiệm vụ cho một chiếc xe và UpdateDeliveryVehicleRequest.

Ví dụ về lệnh curl:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "DELIVERY",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Tác vụ tạo hàng loạt

Bạn có thể tạo một loạt tác vụ từ môi trường máy chủ bằng cách sử dụng gRPC hoặc REST.

gRPC

Ví dụ sau đây cho thấy cách sử dụng thư viện Java gRPC để tạo hai nhiệm vụ, trong đó có một nhiệm vụ là giao hàng và một nhiệm vụ là đến lấy hàng tại cùng một vị trí:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Delivery Task settings
Task deliveryTask = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("delivery-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8312508")  // Task ID assigned by the Provider
      .setTask(deliveryTask)      // Initial state
      .build();

// Pickup Task settings
Task pickupTask = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("pickup-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(pickupTask)        // Initial state
      .build();

// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;

// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
  BatchCreateTasksRequest.newBuilder()
      .setParent(parent)
      .addRequests(createDeliveryTaskRequest)
      .addRequests(createPickupTaskRequest)
      .build();

// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.

try {
  BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
    batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

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

Để tạo tác vụ giao hàng và đến lấy hàng từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến BatchCreateTasks:

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

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.

Nội dung yêu cầu phải 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 phải chuyển cùng một quy tắc xác thực như một yêu cầu CreateTask, ngoại trừ các trường parent và header là không bắt buộc. Nếu được đặt, thì các trường 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ụ nhận hàng và tạo nhiệm vụ giao hàng để biết các quy tắc xác thực cụ thể cho từng nhiệm vụ.

Để biết thêm thông tin, hãy xem tài liệu 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 có sẵn theo lịch

Bạn có thể tạo một tác vụ cho biết không có sẵn (ví dụ: lỗi người lái xe hoặc nạp nhiên liệu cho xe) từ SDK trình điều khiển hoặc từ môi trường máy chủ sử dụng gRPC hoặc REST. Tác vụ không có sẵn theo lịch không được bao gồm mã theo dõi. Bạn có thể cung cấp vị trí (không bắt buộc).

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo một tác vụ không có sẵn:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String parent = "providers/" + PROJECT_ID;
    Task task = Task.newBuilder()
      .setType(Task.Type.UNAVAILABLE)
      .setState(Task.State.OPEN)
      .setTaskDuration(
        Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
      .build();

    // Task request
    CreateTaskRequest createTaskRequest =
      CreateTaskRequest.newBuilder()  // No need for the header
          .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
          .setTaskId("task-8241890")  // Task ID assigned by the Provider
          .setTask(task)              // Initial state
          .build();

    // Error handling
    // If Fleet Engine does not have task with that ID and the credentials of the
    // requestor pass, the service creates the task successfully.

    try {
      Task createdTask = deliveryService.createTask(createTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

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

Để tạo một tác vụ không thực hiện được từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến CreateTask:

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

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

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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
    state State.OPEN
    taskDuration Thời lượng của điểm chèn tính bằng giây.

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

    TrườngGiá trị
    plannedLocation Vị trí điểm chèn nếu phải được chụp tại một vị trí cụ thể.

Tất cả các trường khác trong thực thể đều bị bỏ qua khi tạo. Fleet Engine sẽ gửi ra một trường hợp ngoại lệ nếu yêu cầu bao gồm deliveryvehicleId được chỉ định. Bạn giao việc cần làm bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Giao nhiệm vụ cho một chiếc xe và UpdateDeliveryVehicleRequest.

Ví dụ về lệnh curl:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "UNAVAILABLE",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "300s"
    }
    EOM

Trạm dừng theo lịch

Bạn có thể tạo tác vụ dừng theo lịch từ SDK Trình điều khiển hoặc từ môi trường máy chủ bằng cách sử dụng gRPC hoặc REST. Tác vụ dừng theo lịch có thể không bao gồm mã theo dõi.

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để tạo tác vụ dừng theo lịch biểu:

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

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

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

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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
    state State.OPEN
    plannedLocation Vị trí của điểm dừng.
    taskDuration Thời lượng dự kiến của điểm dừng tính bằng giây.

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

    • Không có

Tất cả các trường khác trong thực thể đều bị bỏ qua khi tạo. Fleet Engine sẽ gửi ra một trường hợp ngoại lệ nếu yêu cầu bao gồm deliveryvehicleId được chỉ định. Bạn giao việc cần làm bằng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Giao nhiệm vụ cho một chiếc xe và UpdateDeliveryVehicleRequest.

Ví dụ về lệnh curl:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "SCHEDULED_STOP",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "600s"
    }
    EOM

Đặt khoảng thời gian mục tiêu

Khoảng thời gian mục tiêu là TimeWindow, trong thời gian đó tác vụ sẽ hoàn tất. Ví dụ: nếu thông báo về khoảng thời gian giao hàng cho người nhận giao hàng, bạn có thể sử dụng cửa sổ thời gian mục tiêu của tác vụ để chụp khoảng thời gian này và tạo cảnh báo hoặc phân tích hiệu suất sau chuyến đi bằng trường này.

Khoảng thời gian mục tiêu bao gồm thời gian bắt đầu và thời gian kết thúc, đồng thời có thể được đặt trên bất kỳ loại tác vụ nào. Khoảng thời gian mục tiêu không ảnh hưởng đến hành vi định tuyến.

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để thiết lập khoảng thời gian tác vụ:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String TASK_ID = "task-8241890";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
    Task task = Task.newBuilder()
      .setName(taskName)
      .setTargetTimeWindow(
        TimeWindow.newBuilder()
          .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
          .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
      .build();

    // Task request
    UpdateTaskRequest updateTaskRequest =
      UpdateTaskRequest.newBuilder()  // No need for the header
          .setTask(task)
          .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
          .build();

    try {
      Task updatedTask = deliveryService.updateTask(updateTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case NOT_FOUND:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

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

Để đặt khoảng thời gian tác vụ bằng HTTP, hãy gọi UpdateTask:

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

<id> là giá trị nhận dạng duy nhất của công việc.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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 việc cần làm. Chế độ cài đặt này không ảnh hưởng đến hành vi đị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ể sẽ 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ị cho tính năng theo dõi tác vụ

Bạn có thể kiểm soát chế độ hiển thị dữ liệu trong thư viện Theo dõi việc vận chuyển và dữ liệu đó được trả về từ lệnh gọi đến GetTaskTrackingInfo theo từng tác vụ bằng cách đặt TaskTrackingViewConfig cho tác vụ đó. Xem phần Các nhiệm vụ xe đang hoạt động để biết thêm thông tin. Bạn có thể thực hiện việc này khi tạo hoặc cập nhật tác vụ. Sau đây là ví dụ về cách cập nhật tác vụ bằng cấu hình này:

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để thiết lập cấu hình chế độ xem theo dõi 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)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}

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

Để đặt cửa sổ cấu hình chế độ xem theo dõi công việc bằng HTTP, hãy gọi UpdateTask:

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

<id> là giá trị nhận dạng duy nhất của công việc.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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 tác vụ chỉ định những phần tử dữ liệu mà người dùng cuối có thể nhìn thấy 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ể sẽ 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 việc cần làm cho xe

Bạn giao nhiệm vụ cho một xe giao hàng bằng cách cập nhật thứ tự nhiệm vụ cho xe đó. Thứ tự nhiệm vụ của xe được xác định theo danh sách điểm dừng xe của xe giao, và bạn có thể chỉ định một hoặc nhiều nhiệm vụ cho mỗi điểm dừng của xe. Để biết thông tin chi tiết, hãy xem phần Cập nhật thứ tự tác vụ.

Để thay đổi quá trình vận chuyển từ xe này sang xe khác, hãy đóng tác vụ ban đầu, sau đó tạo lại trước khi chỉ định phương tiện mới. Nếu cập nhật thứ tự tác vụ cho một tác vụ đã được giao cho một loại xe khác, bạn sẽ gặp lỗi.

Cập nhật thứ tự tác vụ

Bạn có thể cập nhật các nhiệm vụ theo đơn đặt hàng được chỉ định cho xe được thực hiện từ SDK trình điều khiển hoặc môi trường máy chủ. Không sử dụng cả hai phương thức để tránh điều kiện tranh đấu 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:

  • Giao những nhiệm vụ mới trên xe.
  • Đóng mọi nhiệm vụ đã được chỉ định cho xe trước đó nhưng chưa có theo thứ tự mới cập nhật.

Để thay đổi quá trình vận chuyển từ xe này sang xe khác, hãy đóng tác vụ ban đầu, sau đó tạo lại nhiệm vụ đó trước khi chỉ định phương tiện mới. Nếu cập nhật thứ tự tác vụ cho một tác vụ đã được giao cho một loại xe khác, bạn sẽ gặp lỗi.

Bạn có thể cập nhật thứ tự công việc bất cứ lúc nào.

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để cập nhật thứ tự tác vụ cho xe:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.NEW)))
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

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

Để cập nhật thứ tự tác vụ cho xe từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến UpdateDeliveryVehicle:

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

<id> là giá trị nhận dạng duy nhất của xe giao hàng trong nhóm thiết bị mà bạn dự định cập nhật thứ tự nhiệm vụ. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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 trong hành trình cho các nhiệm vụ theo thứ tự thực hiện. Tác vụ đầu tiên trong danh sách sẽ được thực thi trước.
    còn lạiXeHành trìnhPhân đoạn[i].stop Điểm dừng của tác vụ i trong danh sách.
    còn lạiXeJourney Phân đoạn[i].stop.khuyênLocation Địa điểm theo kế hoạch cho điểm dừng.
    còn lạiXeHành trìnhPhân đoạn[i].stop.tasks Danh sách những việc bạn cần làm tại trạm dừng 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ể sẽ 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ừ một điểm dừng hoặc bắt đầu dẫn đường. Bạn có thể thông báo cho Fleet Engine từ Driver SDK hoặc từ môi trường máy chủ bằng cách sử dụng gRPC hoặc REST. Đừng sử dụng cả hai phương thức để tránh các điều kiện tranh đấu và để duy trì một nguồn đáng tin cậy.

gRPC

Ví dụ sau cho thấy cách sử dụng thư viện Java gRPC để thông báo cho Fleet Engine rằng có 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ôi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến UpdateDeliveryVehicle:

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

<id> là giá trị nhận dạng duy nhất cho xe giao hàng trong nhóm thiết bị mà bạn dự định cập nhật thứ tự nhiệm vụ. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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 có trạng thái đượ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ể đều 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ể thực hiện lệnh gọi trực tiếp đến Fleet Engine kèm theo thông tin vị trí của xe. Đối với mọi xe đang hoạt động, Fleet Engine dự kiến sẽ cập nhật vị trí ít nhất một lần mỗi phút và tối đa là 5 giây một lần.

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để cập nhật thông tin 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 một chiếc xe trong Fleet Engine bằng HTTP REST, hãy gọi đến UpdateDeliveryVehicle:

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

<id> là giá trị nhận dạng duy nhất của xe giao hàng trong tàu của bạn hoặc là giá trị mà bạn dự định cập nhật vị trí. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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 mà xe ở vị trí này.
    lastLocation.supplementalLocationSensor Phải được điền sẵn 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í được 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 đang đến trạm dừng

Fleet Engine phải được thông báo khi xe đến điểm dừng. Bạn có thể thông báo cho Fleet Engine từ SDK trình điều khiển hoặc từ môi trường máy chủ bằng cách sử dụng gRPC hoặc REST. Đừng sử dụng cả hai phương thức để tránh các điều kiện tranh đấu và để duy trì một nguồn đáng tin cậy.

gRPC

Ví dụ sau cho thấy cách sử dụng thư viện Java gRPC để thông báo cho Fleet Engine rằng có một 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()
    // Marking the arrival at stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

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

Để thông báo cho Fleet Engine về việc xe đến điểm dừng từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến UpdateDeliveryVehicle:

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

<id> là giá trị nhận dạng duy nhất cho xe giao hàng trong nhóm thiết bị mà bạn dự định cập nhật thứ tự nhiệm vụ. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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.To, theo sau là danh sách các điểm dừng xe còn lại với trạng thái được đánh dấu là State.NEW.

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

    • Không có

Tất cả các trường khác trong thực thể sẽ 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 thành điểm dừng

Bạn phải thông báo cho Fleet Engine khi xe hoàn tất quá trình dừng. Điều này khiến tất cả các tác vụ liên quan đến điểm dừng đều được đặt thành trạng thái ĐÃ ĐÓNG. 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 cách sử dụng gRPC hoặc REST. Không dùng cả hai phương thức để tránh điều kiện tranh đấu và duy trì một nguồn đáng tin cậy.

gRPC

Ví dụ sau cho thấy cách sử dụng thư viện Java gRPC để thông báo cho Fleet Engine rằng 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 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=remaining_vehicle_journey_segments`

<id> là giá trị nhận dạng duy nhất cho xe giao hàng trong nhóm thiết bị mà bạn dự định cập nhật thứ tự nhiệm vụ. Đây là giá trị nhận dạng mà bạn chỉ định khi tạo xe.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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 Trạm dừng bạn đã hoàn thành sẽ không còn nằm trong danh sách các điểm dừ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ể sẽ 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 việc cần làm đều không thể thay đổi. Tuy nhiên, bạn có thể sửa đổi trạng thái, kết quả của nhiệm vụ, thời gian kết quả của nhiệm vụ, vị trí kết quả của nhiệm vụ và thuộc tính bằng cách cập nhật trực tiếp thực thể của nhiệm vụ đó. Ví dụ: trong trường hợp một nhiệm 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ực tiếp trạng thái.

gRPC

Đây là ví dụ về cách cập nhật một nhiệm vụ thông qua gRPC.

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

Đây là ví dụ về cách cập nhật một tác vụ 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 rằng xe đã hoàn thành điểm dừng nơi nhiệm vụ đó diễn ra hoặc xoá nó khỏi danh sách điểm dừng xe. Để làm điều đó, bạn có thể đặt danh sách các điểm dừng của xe còn lại giống như khi cập nhật thứ tự tác vụ cho một chiếc xe.

Nếu một nhiệm vụ chưa được giao cho xe và cần đóng, hãy cập nhật nhiệm vụ thành trạng thái CLOSED (ĐÃ ĐÓNG). Tuy nhiên, bạn không thể mở lại tác vụ ĐÃ ĐÓNG.

Đóng một tác vụ không có nghĩa là thành công hay thất bại. Mã này cho biết tác vụ không còn được xem là đang thực hiện. Để theo dõi quá trình vận chuyển, điều quan trọng là phải cho biết kết quả thực tế của tác vụ để có thể hiển thị kết quả giao hàng.

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

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

<id> là giá trị nhận dạng duy nhất của công việc.

Tiêu đề yêu cầu của bạn phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

Bạn phải đưa một thực thể Task vào nội dung yêu cầu:

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

    TrườngGiá trị
    state State.CLOSED

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

    TrườngGiá trị
    taskOutcome Kết quả.SUCCEEDED hoặc Outcome.FAILED
    taskOutcomeTime Thời gian hoàn thành việc cần làm.
    taskOutcomeLocation Vị trí đã hoàn thành việc cần làm. Fleet Engine mặc định đặt giá trị này là vị trí cuối cùng của xe, 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ể sẽ 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

Thiết lập kết quả nhiệm vụ và vị trí kết quả

Việc đóng một tác vụ không cho biết là có thành công hay không, mà cho biết tác vụ đó không còn được xem là đang diễn ra. Để theo dõi quá trình vận chuyển, điều quan trọng là phải cho biết kết quả thực tế của nhiệm vụ để có thể hiển thị kết quả giao hàng và có cách tính phí phù hợp cho các dịch vụ. Sau khi đặt, bạn không thể thay đổi kết quả của việc cần làm. 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 chúng được đặt.

Kết quả của những tác vụ đang ở trạng thái ĐÃ ĐÓNG có thể được đặt thành SUCCEEDED (ĐÃ THÀNH CÔNG) hoặc FAILED (KHÔNG THÀNH CÔNG). Fleet Engine chỉ tính phí các tác vụ phân phối có trạng thái là SUCCEEDED.

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

gRPC

Bạn có thể đặt vị trí kết quả nhiệm vụ khi đặt kết quả. Việc đặt vị trí này sẽ không cho phép Fleet Engine đặt vị trí mặc định của vị trí xe gần đây nhất. Sau này, bạn cũng có thể ghi đè vị trí kết quả nhiệm vụ mà Fleet Engine đã đặt. 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ả nhiệm vụ cho một nhiệm vụ chưa đặt kết quả nhiệm vụ. Bạn có thể đặt cả kết quả nhiệm vụ và vị trí kết quả nhiệm vụ trong cùng một yêu cầu.

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để đặt kết quả tác vụ thành SUCCEEDED và đặt vị trí hoàn thành tác vụ:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskOutcome(TaskOutcome.SUCCEEDED)
  .setTaskOutcomeTime(now())
  .setTaskOutcomeLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

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

Để đánh dấu một công việc là đã hoàn thành 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=taskOutcome,taskOutcomeTime,taskOutcomeLocation`

<id> là giá trị nhận dạng duy nhất của công việc.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

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 Kết quả.SUCCEEDED hoặc Outcome.FAILED

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

    TrườngGiá trị
    taskOutcomeLocation Vị trí đã hoàn thành việc cần làm. Nếu bạn không đặt chính sách này, Fleet Engine sẽ đặt mặc định vị trí này là vị trí gần đây nhất của xe.
    taskOutcomeTime Dấu thời gian khi tác vụ hoàn tất.

Tất cả các trường khác trong thực thể sẽ 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í dự kiến của nhiệm vụ đó. Để định tuyến lại lô hàng, hãy đóng nhiệm vụ vận chuyển mà không đặt kết quả, sau đó tạo một nhiệm vụ mới với vị trí dự kiến mới cập nhật. Sau khi tạo việc cần làm mới, hãy giao việc đó cho cùng xe. Để biết thêm thông tin, hãy xem phần đóng tác vụ vận chuyển và giao tác vụ.

Sử dụng xe chuyển dữ liệu và xe giao hàng

Nếu bạn sử dụng xe trung chuyển để vận chuyển các lô hàng đến xe giao hàng trong suốt cả ngày, hãy mô hình hoá việc chuyển lô hàng dưới dạng một nhiệm vụ dừng theo lịch cho xe giao hàng đó. Để đảm bảo theo dõi vị trí chính xác, bạn chỉ nên chỉ định nhiệm vụ giao hàng cho một lô hàng đã vận chuyển sau khi gói hàng đó được tải lên xe giao hàng. Để biết thêm thông tin, hãy xem điểm dừng theo lịch.

Lưu trữ trạng thái vận chuyển và các thông tin meta khác

Khi một nhiệm vụ vận chuyển hoàn tất, trạng thái và kết quả của nhiệm vụ sẽ được ghi lại trong nhiệm vụ đó. Tuy nhiên, bạn nên cập nhật các thông tin meta khác dành riêng cho lô hàng đó. Để lưu trữ thông tin meta khác mà bạn có thể tham chiếu bên ngoài dịch vụ Fleet Engine, hãy sử dụng track_id được liên kết với công việc làm khoá trong bảng bên ngoài.

Để biết thêm thông tin, hãy xem phần Vòng đời của một việc cần làm.

Tra cứu xe

Bạn có thể tra cứu xe qua 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 cho thấy 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)

Để tra cứu xe qua môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến GetVehicle:

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

<id> là giá trị nhận dạng duy nhất của công việc.

<vehicleId> là mã của chiếc xe cần tra cứu.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

Nội dung yêu cầu phải trống.

Nếu tra cứu thành công, nội dung phản hồi sẽ chứa một thực thể phương tiện.

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 một công việc qua môi trường máy chủ bằng gRPC hoặc REST. SDK trình điều khiển không hỗ trợ tính năng tra cứu tác vụ.

gRPC

Ví dụ sau đây cho biết cách dùng thư viện Java gRPC để tra cứu một tác vụ:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
    .setName(taskName)
    .build();

try {
  Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

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

Để tra cứu một công việc từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến GetTask:

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

<id> là giá trị nhận dạng duy nhất của công việc.

<taskId> là mã của công việc cần tra cứu.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Bearer <token>, trong đó <token> là một mã thông báo do một nhà máy mã thông báo Fleet Engine phát hành.

Nội dung yêu cầu phải trống.

Nếu tra cứu thành công, nội dung phản hồi sẽ chứa một thực thể tác vụ.

Ví dụ về lệnh curl:

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

Tra cứu thông tin 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 cách có một mục đích riêng:

  • theo mã công việc: do những người dùng như nhân viên vận hành nhóm có quyền truy cập vào chế độ xem toàn bộ dữ liệu công việc sử dụng.
  • theo mã theo dõi: mà phần mềm ứng dụng khách của bạn sử dụng để cung cấp thông tin có giới hạn cho người dùng cuối, chẳng hạn như thời điểm dự kiến gói hàng sẽ được giao 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 theo 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 bằng mã theo dõi, bạn có thể sử dụng một trong những 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 hiển thị nêu trong phần Kiểm soát chế độ hiển thị của các vị trí được theo dõi.

  • Sử dụng Fleet Engine để tra cứu thông tin vận chuyển bằng mã theo dõi. SDK trình điều khiển không hỗ trợ tra cứu thông tin theo mã theo dõi. Để thực hiện việc này bằng Fleet Engine, bạn cần sử dụng môi trường máy chủ hoặc trình duyệt.

  • Sử dụng mã thông báo hẹp nhất có thể để hạn chế rủi ro bảo mật. Ví dụ: nếu bạn sử dụng Mã thông báo của người tiêu dùng giao hàng, thì mọi lệnh gọi Fleet Engine Deliveries API đều chỉ trả về thông tin liên quan đến người dùng cuối đó, chẳng hạn như người vận chuyển hoặc người nhận của một lô hàng. Mọi thông tin khác trong câu trả lời sẽ bị loại bỏ. Để biết thêm thông tin về mã thông báo, hãy xem phần Tạo mã thông báo web JSON (JWT) để uỷ quyền.

Tra cứu bằng Java bằng gRPC

Ví dụ sau cho thấy cách sử dụng thư viện Java gRPC để tra cứu thông tin về một công việc vận chuyển theo mã theo dõi của công việc đó.

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 một nhiệm vụ vận chuyển trên trình duyệt, hãy thực hiện lệnh gọi HTTP REST đến GetTaskTrackingInfo:

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

<tracking_id> là mã theo dõi được liên kết với công việc.

Tiêu đề yêu cầu phải chứa trường Uỷ quyền có giá trị Barrower <token>, trong đó <token> là một mã thông báo do nhà máy mã thông báo Fleet Engine phát hành.

Nếu quá trình tra cứu thành công, nội dung phản hồi sẽ chứa một thực thể taskTrackingInfo.

Ví dụ về lệnh curl:

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

Liệt kê việc cần làm

Bạn có thể liệt kê các công việc từ môi trường máy chủ hoặc trình duyệt. SDK trình điều khiển không hỗ trợ liệt kê các tác vụ.

Việc cần làm trong danh sách yêu cầu quyền truy cập rộng rãi vào các công việc. Tác vụ liệt kê chỉ dành cho người dùng đáng tin cậy. Sử dụng Trình đọc nhóm phân phối hoặc Mã thông báo xác thực người dùng cao cấp phân phối khi đưa ra yêu cầu tác vụ danh sách.

Những việc cần làm trong danh sách có các trường sau đã bị loại bỏ:

  • VehicleStop.planned_location
  • VehicleStop.state
  • VehicleStop.TaskInfo.taskId

Có thể lọc các công việc trong danh sách theo hầu hết thuộc tính công việc. Để biết cú pháp truy vấn bộ lọc, hãy xem AIP-160. Danh sách sau đây cho thấy các thuộc tính tác vụ hợp lệ mà bạn có thể dùng để lọc:

  • attributes
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_outcome
  • task_outcome_location
  • task_outcome_location_source
  • task_outcome_time
  • tracking_id
  • loại

Sử dụng các định dạng trường sau đây dựa trên Đề xuất cải thiện API của Google:

Loại trường Định dạng Ví dụ:
Dấu thời gian RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Thời lượng Số giây theo sau là s task_duration = 120s
Liệt kê Chuỗi state = CLOSED AND type = PICKUP
Vị trí point.latitude và point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

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

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

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

gRPC

Ví dụ sau cho thấy 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 tác vụ. Phản hồi thành công vẫn có thể trống. Phản hồi trống cho biết không 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 các tác vụ trong danh sách, hãy thêm tham số URL "bộ lọc" với giá trị là truy vấn bộ lọc có ký tự thoát trong URL.

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

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

Câu trả lời thành công vẫn có thể bị trống. Phản hồi trống cho biết không tìm thấy công việc nào đáp ứng tiêu chí bộ lọc đã chỉ định.

Ví dụ về lệnh curl:

    # Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

Liệt kê xe giao hàng

Bạn có thể liệt kê các xe giao hàng từ môi trường máy chủ hoặc trình duyệt. SDK trình điều khiển không hỗ trợ liệt kê xe giao hàng.

Xe giao hàng đăng thông tin yêu cầu quyền truy cập rộng rãi vào xe giao hàng và chỉ dành cho những người dùng đáng tin cậy. Sử dụng Trình đọc nhóm phân phối hoặc Mã thông báo xác thực người dùng cao cấp phân phối khi yêu cầu xe phân phối danh sách.

Các xe giao hàng liệt kê có các trường sau đây bị loại bỏ do ảnh hưởng đến kích thước phản hồi:

  • CurrentRouteSegment
  • RemainingVehicleJourneySegments

Bạn có thể lọc danh sách các xe giao hàng theo tài sản attributes của các xe đó. Ví dụ: để truy vấn một thuộc tính bằng khoá my_key và giá trị my_value, hãy sử dụng attributes.my_key = my_value. Để truy vấn nhiều thuộc tính, hãy kết hợp các truy vấn bằng cách sử dụng các toán tử logic AND và OR như trong attributes.key1 = value1 AND attributes.key2 = value2. Hãy xem phần AIP-160 để biết nội dung mô tả đầy đủ về cú pháp truy vấn của bộ lọc.

Bạn có thể lọc các xe giao hàng trong danh sách theo vị trí bằng cách sử dụng tham số yêu cầu viewport. Tham số yêu cầu viewport xác định khung nhìn bằng cách sử dụng 2 toạ độ giới hạn: cặp toạ độ vĩ độ và kinh độ high (đông bắc) và low (tây nam). Yêu cầu sẽ bị từ chối nếu chứa vĩ độ cao thấp hơn vĩ độ thấp.

Theo mặc định, danh sách xe giao hàng được phân trang bằng một kích thước trang hợp lý. Nếu bạn chỉ định kích thước trang, yêu cầu sẽ chỉ trả về số lượng xe được chỉ định theo giới hạn hoặc ít hơn. Nếu kích thước trang được yêu cầu vượt quá giá trị tối đa nội bộ, thì kích thước tối đa nội bộ sẽ được sử dụng. Kích thước trang mặc định và tối đa đều là 100 xe.

Danh sách phương tiện giao hàng có thể chứa 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ó nhiều trang xe phân phối hơn để truy xuất. Để truy xuất trang tác vụ tiếp theo, hãy sử dụng mã thông báo trang có yêu cầu giống với yêu cầu trước đó.

gRPC

Ví dụ sau cho biết cách sử dụng thư viện Java gRPC để liệt kê các xe giao hàng ở một khu vực cụ thể có một thuộc tính nhất định. Phản hồi thành công vẫn có thể để trống. Khi điều đó xảy ra, điều đó có nghĩa là không có xe nào có thuộc tính được chỉ định xuất hiện trong khung nhìn được chỉ định.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
  ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setViewport(
            Viewport.newBuilder()
              .setHigh(LatLng.newBuilder()
                  .setLatitude(37.45)
                  .setLongitude(-122.06)
                  .build())
              .setLow(LatLng.newBuilder()
                  .setLatitude(37.41)
                  .setLongitude(-122.11)
                  .build())
      .setFilter("attributes.my_key = my_value")
      .build();

try {
  ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
      deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
          break;

      case PERMISSION_DENIED:
          break;
  }
  return;
}

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

Để liệt kê các tác vụ trên một trình duyệt, hãy thực hiện lệnh gọi HTTP REST đến ListDeliveryVehicles:

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

Để áp dụng bộ lọc cho các tác vụ đã liệt kê, hãy thêm tham số URL "filter" với giá trị là truy vấn bộ lọc có ký tự thoát URL.

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

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

Câu trả lời thành công vẫn có thể bị 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 nào đáp ứng truy vấn bộ lọc và khung nhìn đã 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 Fleet Engine Deliveries API để bật tính năng theo dõi quá trình vận chuyển:

  • Ưu tiên: Sử dụng thư viện Theo dõi vận chuyển JavaScript. Thư viện này cho phép bạn trực quan hoá vị trí của xe và vị trí quan tâm được theo dõi trong Fleet Engine. Đối tượng này chứa một thành phần bản đồ JavaScript là tính năng thay thế cho đối tượng google.maps.Map tiêu chuẩn và các thành phần dữ liệu để kết nối với Fleet Engine. Thành phần này cho phép bạn cung cấp trải nghiệm theo dõi vận chuyển dạng ảnh động, có thể tuỳ chỉnh từ web hoặc ứng dụng dành cho thiết bị di động.

  • Triển khai tính năng theo dõi quá trình vận chuyển của riêng bạn ngoài Fleet Engine Deliveries API.

Điều quan trọng là tra cứu các công việc 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 giao hàng, thì mọi lệnh gọi Fleet Engine Deliveries API đều chỉ trả về thông tin liên quan đến người vận chuyển hoặc người nhận. Mọi thông tin khác trong câu trả lời đều bị loại bỏ. Bạn chịu 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ụ đã được thực hiện. Trong tác vụ không hoạt động, 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, hãy xem phần Ghi nhật ký.

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

Như mô tả trong phần Quản lý vòng đời công việc và xe và ghi chú uỷ quyền cho từng trường hợp sử dụng, việc thực hiện 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 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 dùng để cấp các mã thông báo đó có thể có một hoặc nhiều vai trò, mỗi vai trò cấp một nhóm quyền khác nhau.

Để biết thêm thông tin, hãy xem phần Xác thực và uỷ quyền.

Khắc phục các sự cố thường gặp

Hãy xem các phần sau đây để được trợ giúp nếu bạn gặp bất kỳ vấn đề nào.

Khả năng phục hồi

Fleet Engine không được coi là nguồn đáng tin cậy. Bạn chịu trách nhiệm khôi phục trạng thái của hệ thống (nếu cần) mà không cần dựa vào Fleet Engine.

Trạng thái bị mất trong Fleet Engine

Khi làm việc với Fleet Engine, hãy triển khai các ứng dụng khách để hệ thống tự khắc phục nếu có lỗi. Ví dụ: Khi cố gắng cập nhật một chiếc xe, Fleet Engine có thể phản hồi kèm theo thông báo lỗi cho biết rằng xe không tồn tại. Sau đó, ứng dụng sẽ tạo lại xe ở trạng thái mới. Mặc dù vấn đề này hiếm khi xảy ra, nhưng hãy đảm bảo hệ thống của bạn có đủ khả năng xử lý.

Trong tình huống hiếm gặp xảy ra lỗi nghiêm trọng của Fleet Engine, bạn có thể cần phải tạo lại hầu hết hoặc tất cả các xe và nhiệm vụ. Nếu tỷ lệ tạo quá cao, một số yêu cầu có thể lại không thực hiện được do vấn đề về hạn mức vì việc kiểm tra hạn mức được thực hiện để 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ỷ lệ tạo lại bằng cách sử dụng chiến lược thời gian đợi để thử lại.

Trạng thái bị mất trong ứng dụng dành cho người lái xe

Nếu ứng dụng trình điều khiển gặp sự cố, ứng dụng phải tạo lại trạng thái hiện tại trong SDK trình điều khiển. Ứng dụng nên cố gắng tạo lại các tác vụ để đảm bảo rằng các tác vụ đó tồn tại và khôi phục trạng thái hiện tại. Ứng dụng cũng nên 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 vì đang thực hiện một nhiệm vụ không đúng thứ tự?

Trong trường hợp này, trước tiên, hãy cập nhật thứ tự của các tác vụ rồi tiếp tục như bình thường, đánh dấu việc đến điểm dừng, hoàn thành tác vụ và các thông tin 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, 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.