API Giao hàng và gọi xe theo yêu cầu của Fleet Engine giúp bạn quản lý các chuyến đi và trạng thái xe cho các ứng dụng về Tiến trình đặt hàng và Chuyến đi của bạn. Thư viện này xử lý các giao dịch giữa SDK trình điều khiển, SDK người tiêu dùng và dịch vụ phụ trợ – có thể giao tiếp với Fleet Engine bằng cách thực hiện gRPC hoặc REST.
Điều kiện tiên quyết
Để phát triển, hãy đảm bảo rằng bạn cài đặt Cloud SDK (gcloud) và được xác thực để dự án của bạn.
shell
gcloud auth login
Bạn sẽ thấy thông báo thành công, chẳng hạn như:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Kiểm tra để đảm bảo rằng các API Fleet Engine của giải pháp gọi xe và giao hàng theo yêu cầu được định cấu hình phù hợp.
shell
gcloud --project=project-id services enable fleetengine.googleapis.com
Nếu lệnh này dẫn đến lỗi, hãy kiểm tra với quản trị viên dự án của bạn và người đại diện nhóm hỗ trợ Google để có quyền truy cập.
Ghi nhật ký
Fleet Engine có thể viết thông điệp nhật ký về các lệnh gọi API mà Fleet Engine nhận được vào nhật ký của Google Cloud Platform. Xem tài liệu về Ghi nhật ký trên đám mây để biết tổng quan về cách đọc và phân tích nhật ký.
Theo mặc định, tính năng ghi nhật ký có thể không được bật cho những dự án được tạo trước đó Ngày 10 tháng 2 năm 2022. Xem tài liệu về nhật ký để biết thêm chi tiết.
Thư viện ứng dụng
Chúng tôi xuất bản thư viện ứng dụng bằng một số ngôn ngữ lập trình phổ biến. Các các thư viện sẽ giúp cung cấp trải nghiệm tốt hơn cho nhà phát triển so với REST hoặc gRPC thô. Để biết hướng dẫn về cách tải thư viện ứng dụng cho ứng dụng máy chủ của bạn, xem Thư viện ứng dụng.
Các ví dụ Java trong tài liệu này giả định rằng bạn đã quen thuộc với gRPC.
Xác thực và uỷ quyền
Bạn có thể định cấu hình các khả năng do Tiến trình đặt hàng và chuyến đi cung cấp thông qua bảng điều khiển Google Cloud. Các API và SDK này yêu cầu sử dụng Mã thông báo web JSON đã được ký bằng tài khoản dịch vụ được tạo từ Cloud Console.
Thiết lập dự án trên đám mây
Để thiết lập dự án trên đám mây, trước tiên, hãy tạo dự án rồi sau đó tạo tài khoản dịch vụ.
Cách tạo dự án trên Google Cloud:
- Tạo một dự án trên Google Cloud bằng Google Cloud Console.
- Sử dụng Trang tổng quan API và dịch vụ, bật API hỗ trợ gọi xe và giao hàng tại địa phương.
Tài khoản dịch vụ được liên kết với một hoặc nhiều vai trò. Chúng được dùng để tạo Mã thông báo web JSON cấp các nhóm quyền khác nhau tuỳ thuộc vào vai trò. Thông thường, để giảm khả năng lạm dụng, bạn có thể tạo nhiều tài khoản dịch vụ, mỗi tài khoản có số vai trò tối thiểu cần thiết.
Tiến trình đặt hàng và chuyến đi sử dụng các vai trò sau:
Vai trò | Mô tả |
---|---|
Người dùng SDK người tiêu dùng của Fleet Engine
roles/fleetengine.consumerSdkUser |
Cấp quyền tìm kiếm xe và truy xuất thông tin về phương tiện di chuyển và các chuyến đi. Mã thông báo do tài khoản dịch vụ tạo bằng vai trò này thường được dùng trên thiết bị di động có ứng dụng dành cho người tiêu dùng hoặc đi chung xe. |
Người dùng SDK Fleet Engine Driver
roles/fleetengine.driverSdkUser |
Cấp quyền để cập nhật vị trí và tuyến đường của xe và để truy xuất thông tin về xe cộ và các chuyến đi. Đã tạo mã thông báo bởi tài khoản dịch vụ có vai trò này thường được sử dụng từ ứng dụng đi chung xe hoặc ứng dụng dành cho tài xế giao hàng. |
Quản trị viên Fleet Engine theo yêu cầu
roles/fleetengine.ondemandAdmin |
Cấp quyền đọc và ghi mọi tài nguyên về xe cộ và chuyến đi. Những người hiệu trưởng có vai trò này không cần dùng JWT mà thay vào đó sử dụng Thông tin xác thực mặc định của ứng dụng. Các thông báo xác nhận quyền sở hữu JWT tuỳ chỉnh sẽ bị bỏ qua. Vai trò này chỉ được dành cho các môi trường đáng tin cậy (phần phụ trợ của khách hàng). |
roles/fleetengine.serviceSuperUser |
Cấp quyền cho tất cả API về xe và chuyến đi. Số mã thông báo đã tạo
bởi tài khoản dịch vụ có vai trò này thường được sử dụng từ chương trình phụ trợ của bạn
máy chủ. Vai trò này không còn được dùng nữa. Ưu tiên
Hãy roles/fleetengine.ondemandAdmin . |
Ví dụ: tạo một tài khoản dịch vụ cho từng vai trò trong số 3 vai trò này rồi chỉ định vai trò tương ứng của họ.
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
SDK trình điều khiển và SDK người tiêu dùng được xây dựng dựa trên các vai trò chuẩn này.
Ngoài ra, bạn cũng có thể tạo các vai trò tuỳ chỉnh cho phép một tập hợp quyền tuỳ ý cần kết hợp với nhau. SDK Người dùng và Trình điều khiển sẽ hiển thị thông báo lỗi bất cứ khi nào thiếu quyền cần thiết. Do đó, bạn rất nên bằng cách dùng nhóm vai trò chuẩn nêu trên và không dùng vai trò tuỳ chỉnh.
Để thuận tiện, nếu bạn cần tạo mã thông báo JWT cho các ứng dụng không đáng tin cậy, hãy thêm vai trò người tạo mã thông báo của tài khoản dịch vụ cho phép họ tạo mã thông báo bằng công cụ dòng lệnh gcloud.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Trong đó my-user@example.com
là email được dùng để
xác thực bằng gcloud (gcloud auth list
--format='value(account)'
).
Thư viện xác thực Fleet Engine
Fleet Engine sử dụng Mã thông báo web JSON (JWT) để hạn chế quyền truy cập vào Fleet Engine API. Thư viện xác thực Fleet Engine mới, có trên GitHub, đơn giản hoá việc xây dựng Fleet Engine JWT và ký tên một cách an toàn.
Thư viện mang lại những lợi ích sau:
- Đơn giản hoá quy trình tạo Mã thông báo Fleet Engine.
- Cung cấp cơ chế ký mã thông báo ngoài việc sử dụng tệp thông tin xác thực (chẳng hạn như mạo danh một tài khoản dịch vụ.)
- Đính kèm mã thông báo đã ký vào các yêu cầu gửi đi được thực hiện từ mã gRPC hoặc Ứng dụng khách GAPIC.
Tạo Mã thông báo web JSON (JWT) để uỷ quyền
Khi không sử dụng Thư viện xác thực công cụ Fleet, Mã thông báo web JSON (JWT) cần phải được trực tiếp tạo trong cơ sở mã của bạn. Để làm được điều này, bạn cần phải có cả hiểu biết về JWT và mối liên hệ của chúng với Fleet Engine. Đây là lý do chúng tôi Bạn đặc biệt nên tận dụng Thư viện xác thực công cụ Fleet.
Trong Fleet Engine, Mã thông báo web JSON (JWT) cung cấp phương thức xác thực ngắn hạn và đảm bảo rằng thiết bị chỉ có thể sửa đổi xe, chuyến đi hoặc nhiệm vụ cho mà họ được phép. JWT chứa tiêu đề và phần xác nhận quyền sở hữu. Phần tiêu đề có chứa thông tin như khoá riêng tư để sử dụng (lấy từ tài khoản dịch vụ) và mã hoá thuật toán. Phần xác nhận quyền sở hữu có chứa những thông tin như thời gian tạo mã thông báo, thời gian tồn tại của mã thông báo, các dịch vụ hiện có xác nhận quyền truy cập vào và thông tin uỷ quyền khác để thu hẹp phạm vi truy cập; ví dụ: mã xe.
Phần tiêu đề JWT chứa các trường sau đây:
Trường | Mô tả |
---|---|
alg | Thuật toán cần sử dụng. "RS256". |
tiêu chuẩn | Loại mã thông báo. "JWT". |
trẻ em | Mã khoá riêng tư của tài khoản dịch vụ của bạn. Bạn có thể tìm thấy giá trị này trong trường "private_key_id" của tệp JSON trong tài khoản dịch vụ. Hãy nhớ sử dụng khoá trong một tài khoản dịch vụ có cấp độ quyền phù hợp. |
Phần thông báo xác nhận quyền sở hữu JWT chứa các trường sau:
Trường | Mô tả |
---|---|
là | Địa chỉ email của tài khoản dịch vụ của bạn. |
sub | Địa chỉ email của tài khoản dịch vụ của bạn. |
aud | SERVICE_NAME của tài khoản dịch vụ của bạn, trong trường hợp này là https://fleetengine.googleapis.com/ |
kiến thức | Dấu thời gian khi mã thông báo được tạo, được chỉ định bằng giây đã trôi qua kể từ 00:00:00 giờ UTC, ngày 1 tháng 1 năm 1970. Chờ 10 phút để xiên. Nếu dấu thời gian quá xa trong quá khứ hoặc trong tương lai, nên máy chủ có thể báo cáo lỗi. |
thử nghiệm | Dấu thời gian khi mã thông báo hết hạn, được xác định bằng giây đã trôi qua kể từ 00:00:00 giờ UTC, ngày 1 tháng 1 năm 1970. Yêu cầu không thành công nếu dấu thời gian là hơn một giờ trong tương lai. |
khoản uỷ quyền | Tuỳ thuộc vào trường hợp sử dụng, có thể chứa "vehicleid" hoặc "tripid". |
Việc tạo mã thông báo JWT tức là ký mã đó. Để xem hướng dẫn và mã mẫu để tạo và ký JWT, hãy xem Uỷ quyền tài khoản dịch vụ không cần OAuth. Sau đó, bạn có thể đính kèm mã thông báo đã ký vào các lệnh gọi gRPC hoặc các phương thức khác được sử dụng để truy cập Fleet Engine.
Thông báo xác nhận quyền sở hữu JWT
Khi tạo tải trọng JWT, hãy thêm thông tin xác nhận quyền sở hữu bổ sung vào phần uỷ quyền
có khoá vehicleid
hoặc tripid
được đặt thành giá trị của
mã xe hoặc mã chuyến đi mà cuộc gọi đang được thực hiện.
SDK Trình điều khiển luôn sử dụng thông báo xác nhận quyền sở hữu vehicleid
, cho dù hoạt động trên
một chuyến đi hoặc xe cộ. Phần phụ trợ của Fleet Engine giúp đảm bảo rằng chiếc xe
được liên kết với chuyến đi đã yêu cầu trước khi sửa đổi.
SDK người tiêu dùng luôn sử dụng thông báo xác nhận quyền sở hữu tripid
.
Nhà cung cấp dịch vụ đi chung xe hoặc giao hàng phải sử dụng vehicleid
hoặc tripid
có "*" đến
khớp với tất cả Xe và Chuyến đi. Lưu ý rằng JWT có thể chứa cả hai mã thông báo,
ngay cả khi không bắt buộc. Điều này có thể giúp đơn giản hoá quá trình ký mã thông báo.
Trường hợp sử dụng JWT
Sau đây là một mã thông báo mẫu cho máy chủ của Nhà cung cấp:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
Sau đây là ví dụ về mã thông báo cho Ứng dụng người dùng:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
Sau đây là ví dụ về mã thông báo cho ứng dụng Trình điều khiển:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- Đối với trường
kid
trong tiêu đề, hãy chỉ định khoá riêng tư của tài khoản dịch vụ của bạn Mã nhận dạng. Bạn có thể tìm thấy giá trị này trong trườngprivate_key_id
của dịch vụ tệp JSON của tài khoản. - Đối với các trường
iss
vàsub
, hãy chỉ định địa chỉ email của tài khoản dịch vụ của bạn. Bạn có thể tìm thấy giá trị này trong trườngclient_email
của tài khoản dịch vụ Tệp JSON. - Đối với trường
aud
, hãy chỉ định https://SERVICE_NAME/. - Đối với trường
iat
, hãy sử dụng dấu thời gian khi mã thông báo được tạo. được chỉ định là số giây trôi qua kể từ 00:00:00 UTC, ngày 1 tháng 1 năm 1970. Chờ 10 phút để xiên. Nếu dấu thời gian là quá xa trong quá khứ, hoặc trong tương lai, máy chủ có thể báo cáo lỗi. - Đối với trường
exp
, hãy sử dụng dấu thời gian khi mã thông báo hết hạn. được chỉ định dưới dạng giây kể từ 00:00:00 UTC, ngày 1 tháng 1 năm 1970. Tối đa giá trị được phép làiat
+ 3600.
Khi ký JWT để truyền đến một thiết bị di động, hãy nhớ sử dụng tài khoản dịch vụ cho vai trò Người lái xe hoặc SDK Người tiêu dùng. Nếu không, thiết bị di động thiết bị có thể thay đổi trạng thái không nên có.
Tương tự, khi ký JWT để dùng cho các lệnh gọi đặc quyền, hãy đảm bảo để sử dụng tài khoản dịch vụ với vai trò Người dùng cao cấp. Nếu không, giá trị không thành công.
Tạo JWT để kiểm thử
Việc tạo mã thông báo từ thiết bị đầu cuối có thể hữu ích khi kiểm thử.
Để làm theo các bước này, người dùng tài khoản phải có vai trò Người tạo mã thông báo tài khoản dịch vụ:
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Tạo một tệp mới có tên là unsigned_token.json
chứa nội dung ở bên dưới. iat
là thời gian hiện tại (tính bằng giây) sau thời gian bắt đầu của hệ thống, có thể được
truy xuất bằng cách chạy date +%s
trong thiết bị đầu cuối của bạn. Thuộc tính exp
là
thời gian hết hạn tính bằng số giây sau thời gian bắt đầu của hệ thống, có thể được tính bằng cách
thêm 3600 vào iat
. Thời gian hết hạn không được vượt quá một giờ trong
tương lai.
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
Sau đó, chạy lệnh gcloud sau đây để ký mã thông báo thay cho Super của bạn Tài khoản dịch vụ người dùng:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
Giờ đây, một JWT được mã hoá Base64 đã ký sẽ được lưu trữ trong tệp
signed_token.jwt
. Mã thông báo này sẽ có hiệu lực trong giờ tiếp theo.
Giờ đây, bạn có thể kiểm thử mã thông báo bằng cách chạy lệnh curl
đối với List ghi chú là phương tiện di chuyển
Điểm cuối REST:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
Xe cộ và vòng đời của chúng
Xe là thực thể đại diện cho một cặp xe. Hiện tại, Không thể theo dõi riêng người lái xe và xe. Nhà cung cấp dịch vụ đi chung xe hoặc giao hàng tạo xe bằng Mã nhà cung cấp (mã này phải giống với Mã dự án của dự án trên Google Cloud có chứa tài khoản dịch vụ dùng để gọi API Fleet Engine) và Mã xe thuộc quyền sở hữu của Nhà cung cấp dịch vụ đi chung xe hoặc giao hàng.
Một chiếc xe chưa được cập nhật qua UpdateVehicle
sau 7 ngày sẽ
tự động bị xoá và các chuyến đi đã chỉ định của chuyến đi đó (nếu có) sẽ được đánh dấu là
chưa chỉ định. Phương pháp được đề xuất để giúp xe luôn sẵn sàng
trong Fleet Engine là cập nhật vị trí của mình theo định kỳ. Cập nhật cho hầu hết
các trường khác trong thực thể Vehicle
cũng sẽ kéo dài thời gian tồn tại, miễn là
giá trị trường mới khác với giá trị hiện có.
LƯU Ý: Một số trường trên thực thể Vehicle
như device_settings
chỉ đơn thuần là gỡ lỗi
những thông tin mà Fleet Engine không lưu giữ. Việc cập nhật họ sẽ không
kéo dài vòng đời của thực thể Vehicle
.
Xảy ra lỗi khi gọi CreateVehicle
bằng
Cặp mã nhận dạng nhà cung cấp/mã xe đã tồn tại. Trường hợp phương tiện
không được cập nhật thường xuyên có thể được xử lý theo hai cách: gọi thường xuyên
CreateVehicle
có cặp Mã nhà cung cấp/Mã nhận dạng xe dự kiến và việc loại bỏ
lỗi nếu Xe đã tồn tại; hoặc gọi CreateVehicle
sau
UpdateVehicle
trả về kèm theo lỗi NOT_FOUND
.
Thông báo cập nhật vị trí xe
Để Fleet Engine đạt được hiệu suất tốt nhất, hãy cung cấp cho nó một luồng xe cập nhật vị trí. Bạn có thể sử dụng một trong các cách sau để cung cấp các thông tin cập nhật này:
- Sử dụng SDK trình điều khiển – Android, iOS -- lựa chọn đơn giản nhất.
- Sử dụng mã tùy chỉnh -- hữu ích nếu vị trí được chuyển tiếp qua phần phụ trợ của bạn hoặc nếu bạn sử dụng thiết bị không phải là Android hoặc iOS.
Loại phương tiện
Thực thể Xe chứa trường bắt buộc là VehicleType
, trong đó có
Enum Category
có thể được chỉ định là AUTO
, TAXI
, TRUCK
,
TWO_WHEELER
, BICYCLE
hoặc PEDESTRIAN
. Loại xe có thể đóng vai trò là
tiêu chí lọc trong SearchVehicles
và ListVehicles
.
Tất cả tuyến đường cho xe sẽ sử dụng RouteTravelMode
tương ứng nếu
danh mục được đặt thành AUTO
, TWO_WHEELER
, BICYCLE
hoặc PEDESTRIAN
.
Nếu danh mục được đặt thành TAXI
hoặc TRUCK
, thì việc định tuyến sẽ được xử lý giống như
chế độ AUTO
.
Thuộc tính xe
Thực thể Xe chứa một trường lặp lại là VehicleAttribute
. Các
không được Fleet Engine diễn giải. SearchVehicles
API bao gồm một trường bắt buộc Vehicles
phù hợp phải chứa tất cả
các thuộc tính đưa vào được đặt thành giá trị được chỉ định.
Lưu ý rằng trường thuộc tính bổ sung cho một số trường được hỗ trợ khác
trong thông báo Vehicle
, chẳng hạn như vehicle_type
và supported_trip_types
.
Điểm tham chiếu còn lại của xe
Thực thể Xe chứa trường lặp lại là TripWaypoint
(RPC | REST),
có tên là waypoints
(RPC | REST).
Trường này bao gồm các điểm tham chiếu còn lại trong các chuyến đi, theo thứ tự
chiếc xe đến chỗ họ. Fleet Engine tính toán trường này là các chuyến đi
được chỉ định cho xe và cập nhật nó khi các chuyến đi thay đổi trạng thái của chúng.
Bạn có thể xác định các điểm tham chiếu này bằng trường TripId
và trường WaypointType
.
Tăng khả năng xe đủ điều kiện tham gia các trận đấu
Thông thường, các dịch vụ của Dịch vụ đi chung xe hoặc Nhà cung cấp dịch vụ giao hàng sẽ chịu trách nhiệm tìm chuyến đi trùng khớp
các yêu cầu đối với xe. Dịch vụ này có thể sử dụng các thuộc tính của xe để thêm
xe xuất hiện trong một số lượng lớn các lượt tìm kiếm. Ví dụ: nhà cung cấp có thể triển khai
một nhóm thành các thuộc tính tương ứng với cấp đặc quyền hoặc khả năng do
một chiếc xe. Ví dụ: 3 cấp có thể là một tập hợp các thuộc tính có boolean
các giá trị: is_bronze_level
, is_silver_level
và is_gold_level
. Một chiếc xe
đều có thể đủ điều kiện tham gia
cả ba loại chiến dịch này. Khi Fleet Engine nhận được yêu cầu về một
chuyến đi yêu cầu tính năng ở cấp độ Bạc, thì nội dung tìm kiếm sẽ bao gồm chiếc xe đó.
Việc sử dụng thuộc tính theo cách này áp dụng cho cả những chiếc xe cung cấp nhiều loại
các chức năng khác nhau.
Có hai cách để cập nhật các thuộc tính của xe. Một là UpdateVehicle
API. Khi bạn sử dụng API này, toàn bộ bộ Thuộc tính xe sẽ được
được đặt thành giá trị. Bạn không thể chỉ cập nhật một thuộc tính duy nhất.
Một phương thức khác là API UpdateVehicleAttributes
. Phương pháp này chỉ mất
các thuộc tính cần cập nhật. Các thuộc tính có trong yêu cầu sẽ được
đặt thành giá trị mới hoặc được thêm vào giá trị mới; thuộc tính không xác định sẽ không bị thay đổi.
HƯỚNG DẪN: Tạo xe
Bạn phải tạo một thực thể Vehicle
cho mỗi Chiếc xe để theo dõi trong hệ thống thiết bị.
Sử dụng điểm cuối CreateVehicle
với CreateVehicleRequest
để tạo một
Xe.
provider_id
của Vehicle
phải là Mã dự án
(ví dụ: dự án theo yêu cầu của tôi) của Dự án Google Cloud có chứa
Các tài khoản dịch vụ sẽ được dùng để gọi Fleet Engine. Xin lưu ý rằng mặc dù
nhiều tài khoản dịch vụ có thể truy cập vào Fleet Engine cho cùng một dịch vụ Đi chung xe
hoặc Nhà cung cấp dịch vụ giao hàng, Fleet Engine hiện không hỗ trợ các tài khoản dịch vụ từ
nhiều dự án Google Cloud truy cập vào cùng một Vehicles
.
Bạn có thể tạo Vehicle
ở trạng thái OFFLINE
hoặc ONLINE
. Nếu
đã tạo ONLINE
. Phản hồi này có thể được trả về ngay lập tức để phản hồi SearchVehicles
truy vấn.
last_location
ban đầu có thể được đưa vào lệnh gọi CreateVehicle
.
Mặc dù được phép, bạn không nên tạo Vehicle
ở trạng thái ONLINE
nếu không có
last_location
.
Xem danh sách Loại xe để biết thông tin chi tiết về xe trường nhập.
Xem phần Thuộc tính xe để biết chi tiết trên trường thuộc tính.
Giá trị được CreateVehicle
trả về là thực thể Vehicle
đã tạo.
Ví dụ:
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Xem providers.vehicles.create tham chiếu.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
Nhật ký của Google Cloud Platform dùng cho việc tạo xe
API Fleet Engine ghi mục nhập nhật ký thông qua nhật ký của Google Cloud Platform khi
đã nhận được lệnh gọi đến điểm cuối CreateVehicle
. Mục nhập nhật ký bao gồm
thông tin về các giá trị trong yêu cầu CreateVehicle
. Nếu cuộc gọi
Nếu thành công, dữ liệu này cũng sẽ bao gồm thông tin về Vehicle
đã
bị trả lại.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
Phải in một bản ghi tương tự như bản ghi sau:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
Thông báo của Cloud Pub/Sub về việc tạo xe
Fleet Engine API phát hành một thông báo qua Cloud Pub/Sub khi một chiếc xe được tạo ra. Để nhận những thông báo này, vui lòng làm theo xem hướng dẫn tại đây.
CÁCH THỰC HIỆN: Cập nhật vị trí của xe
Nếu không sử dụng SDK trình điều khiển để cập nhật vị trí của xe, bạn có thể gọi trực tiếp đến Fleet Engine để biết vị trí của xe. Đối với mọi xe đang hoạt động, Fleet Engine mong muốn cập nhật vị trí ít nhất một lần mỗi phút và tối đa là một lần mỗi 5 giây. Những bản cập nhật này chỉ yêu cầu người dùng SDK Trình điều khiển động cơ Fleet đặc quyền.
Ví dụ:
shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
Xem providers.vehicles.update tham chiếu.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
CÁCH THỰC HIỆN: Cập nhật các trường khác về Xe
Việc cập nhật các thuộc tính khác của trạng thái xe ít xảy ra hơn
thông tin cập nhật vị trí. Yêu cầu cập nhật cho các thuộc tính không phải last_location
Đặc quyền của người dùng cao cấp của Fleet Engine.
UpdateVehicleRequest
bao gồm update_mask
để cho biết những trường nào cần
cập nhật. Hành vi của trường này như trong tài liệu Protobuf dành cho
mặt nạ trường.
Như đã nêu trong mục Thuộc tính xe, việc cập nhật
Trường attributes
yêu cầu ghi tất cả thuộc tính cần được bảo toàn. Nó
không thể chỉ cập nhật giá trị của một cặp khoá-giá trị trong một
Cuộc gọi UpdateVehicle
. Để cập nhật giá trị của các thuộc tính cụ thể, phương thức
Có thể sử dụng API UpdateVehicleAttributes
.
Ví dụ:
Ví dụ này bật back_to_back
.
shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
Xem providers.vehicles.update tham chiếu.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
Nhật ký của Google Cloud Platform dành cho xe cập nhật
API Fleet Engine ghi mục nhập nhật ký thông qua nhật ký của Google Cloud Platform khi
đã nhận được lệnh gọi đến điểm cuối UpdateVehicle
. Mục nhập nhật ký bao gồm
thông tin về các giá trị trong yêu cầu UpdateVehicle
. Nếu cuộc gọi
Nếu thành công, dữ liệu này cũng sẽ bao gồm thông tin về Vehicle
đã
bị trả lại.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
Thông báo của Cloud Pub/Sub về việc cập nhật xe
Fleet Engine API phát hành một thông báo qua Cloud Pub/Sub khi một xe đã được cập nhật. Để nhận những thông báo này, vui lòng làm theo xem hướng dẫn tại đây.
CÁCH THỰC HIỆN: Tìm xe
Fleet Engine hỗ trợ tìm kiếm xe. SearchVehicles
API giúp bạn tìm thấy những người lái xe hiện có ở gần và phù hợp nhất cho một công việc như
phục vụ chuyến đi hoặc yêu cầu giao hàng. API SearchVehicles
trả về một
danh sách được xếp hạng người lái xe phù hợp với thuộc tính nhiệm vụ với thuộc tính của phương tiện ở
hệ thống thiết bị của bạn. Để biết thêm thông tin, hãy xem
Tìm tài xế ở gần.
Ví dụ:
Khi tìm kiếm xe hiện có, Fleet Engine sẽ loại trừ những xe trên các chuyến đi đang hoạt động theo mặc định. Dịch vụ của Nhà cung cấp dịch vụ đi chung xe hoặc giao hàng cần phải đưa chúng vào yêu cầu tìm kiếm. Ví dụ sau đây trình bày cách bao gồm những chiếc xe đó trong tìm kiếm các xe phù hợp với chuyến đi từ Grand Trung tâm mua sắm Đông Indonesia đến Trung tâm hội nghị Balai Sidang Jakarta.
shell
Trước tiên, hãy cập nhật vị trí của chiếc xe mà chúng ta đã tạo ở các bước trước để xe đó đủ điều kiện. Trong thực tế, việc này là nhờ SDK Trình điều khiển chạy trên thiết bị Android hoặc iOS trong xe.
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Việc tìm kiếm ít nhất phải mang lại cho bạn chiếc xe đó.
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
Xem providers.vehicles.search tham chiếu.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Cụm từ tìm kiếm về bộ lọc xe
Chế độ lọc hỗ trợ SearchVehicles
và ListVehicles
cho các thuộc tính của xe
bằng cách sử dụng truy vấn lọc. Đối với cú pháp truy vấn lọc, hãy xem
AIP-160 để biết các ví dụ.
Xin lưu ý rằng các cụm từ tìm kiếm bộ lọc CHỈ hỗ trợ lọc theo các thuộc tính về xe và
Không thể sử dụng cho các trường khác. Các hàm truy vấn bộ lọc là mệnh đề AND
với các hạn chế khác, chẳng hạn như minimum_capacity
hoặc vehicle_types
trong
SearchVehiclesRequest
.
CÁCH THỰC HIỆN: Đăng thông tin về xe
SearchVehicles
được tối ưu hoá để tìm một số lượng nhỏ xe trong thứ hạng
đặt hàng rất nhanh và chủ yếu dùng để tìm người lái xe gần đó phù hợp nhất
một tác vụ. Tuy nhiên, đôi khi bạn muốn tìm tất cả các xe đáp ứng một số
ngay cả khi việc phân trang thông qua kết quả là cần thiết. ListVehicles
là
được thiết kế cho trường hợp sử dụng đó.
API ListVehicles
giúp bạn tìm thấy tất cả xe đáp ứng một số yêu cầu
các tuỳ chọn yêu cầu. API ListVehicles
trả về một danh sách xe được phân trang trong
dự án phù hợp với một số yêu cầu.
Để lọc các thuộc tính của xe, vui lòng tham khảo Cụm từ tìm kiếm về việc lọc xe.
Ví dụ:
Ví dụ này thực hiện lọc trên vehicle_type
và các thuộc tính bằng cách sử dụng
Chuỗi filter
.
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
Xem providers.vehicles.list tham chiếu.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Chuyến đi và vòng đời của chuyến đi
API Chuyến đi và vòng đời tương tự như API và vòng đời của xe.
Nhà cung cấp dịch vụ đi chung xe chịu trách nhiệm tạo các chuyến đi bằng Fleet Engine
giao diện. Fleet Engine cung cấp cả dịch vụ RPC,
TripService
và tài nguyên REST, provider.trips
của Google. Các giao diện này cho phép tạo thực thể Chuyến đi, yêu cầu thông tin, tìm kiếm
chức năng và khả năng cập nhật.
Trip
có một trường trạng thái để theo dõi tiến trình của nó trong suốt vòng đời.
Các giá trị di chuyển từ NEW
sang COMPLETE
cùng với CANCELED
và UNKNOWN_TRIP_STATUS
của Google. Tham khảo trip_status
đối với RPC
hoặc TripStatus cho REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Dịch vụ của bạn có thể cập nhật chuyến đi đến CANCELED
từ bất kỳ trạng thái nào sau đây.
Khi dịch vụ của bạn tạo ra một chuyến đi, công cụ sẽ đặt trạng thái là NEW
. Đáp
vehicle_id
là không bắt buộc. Tương tự như với phương tiện di chuyển, các dịch vụ sẽ tự động xoá những chuyến đi chưa được chỉ định
sau 7 ngày mà không có bản cập nhật. Nếu dịch vụ của bạn cố gắng tạo chuyến đi bằng
Mã nhận dạng đã tồn tại, hệ thống sẽ trả về lỗi. Chuyến đi được coi là "đang hoạt động" nếu
nó đang có trạng thái không phải là COMPLETE
hoặc CANCELED
. Sự khác biệt này
quan trọng trong trường active_trips
trong thực thể Xe và SearchTripsRequest
.
Dịch vụ của bạn chỉ có thể thay đổi vehicle_id
được chỉ định cho một chuyến đi khi chuyến đi đó
đang hoạt động. Ví dụ: bạn sẽ thực hiện việc này khi người lái xe huỷ một chuyến đi trong khi vi
tuyến đường và chuyến đi được xếp lại vào một xe khác.
Trạng thái là quan trọng khi triển khai tính năng so sánh song song hỗ trợ chuyến đi. Dịch vụ hỗ trợ này giúp Nhà cung cấp chỉ định một chuyến đi mới cho một Xe khi Xe đó đang trong một Chuyến đi đang hoạt động. Đoạn mã để tạo Chuyến đi khứ hồi cũng giống như một chuyến đi duy nhất và sử dụng cùng một mã xe. Fleet Engine thêm điểm khởi hành và điểm đến của chuyến đi mới vào điểm tham chiếu của xe. Để biết thêm thông tin về các chuyến đi khứ hồi, hãy xem Tạo các chuyến đi nhiều chặng.
Điểm tham chiếu còn lại của chuyến đi
Thực thể Chuyến đi chứa trường lặp lại là TripWaypoint
(RPC | REST),
có tên là remainingWaypoints
(RPC | REST).
Trường này bao gồm tất cả các điểm tham chiếu mà xe sẽ cần di chuyển theo thứ tự
trước điểm trả cuối cùng của chuyến đi này. Giá trị này tính từ
Điểm tham chiếu còn lại của xe.
Trong các trường hợp sử dụng tính năng Quay lại và đi chung xe, danh sách này chứa các điểm tham chiếu từ
những chuyến đi khác sẽ được di chuyển trước chuyến đi này, nhưng không bao gồm bất kỳ điểm tham chiếu nào
sau chuyến đi này. Có thể xác định điểm tham chiếu trong danh sách theo TripId
và WaypointType
.
Mối quan hệ giữa trạng thái của chuyến đi và số điểm tham chiếu còn lại của xe
Các điểm tham chiếu còn lại của xe (RPC | REST) sẽ
được cập nhật khi Fleet Engine nhận được yêu cầu thay đổi trạng thái chuyến đi. Chiến lược phát hành đĩa đơn
điểm tham chiếu trước đó sẽ bị xoá khỏi danh sách điểm tham chiếu còn lại của Xe khi
tripStatus
(RPC | REST)
được thay đổi từ trạng thái khác thành ENROUTE_TO_XXX. Tức là, khi
trạng thái chuyến đi được thay đổi từ ENROUTE_TO_PICKUP thành ARRIVED_AT_PICKUP, của chuyến đi
điểm đến lấy hàng vẫn sẽ nằm trong danh sách điểm tham chiếu còn lại của Xe, nhưng khi chuyến đi
trạng thái được thay đổi thành ENROUTE_TO_INTERMEDIATE_PLACE hoặc ENROUTE_TO_DROPOFF,
điểm nhận hàng sau đó sẽ được loại bỏ khỏi các điểm tham chiếu còn lại của xe.
Điều này áp dụng tương tự cho ARRIVED_AT_INTERMEDIATE_PLACE và ENROUTE_TO_INTERMDEDIATE_DESTINATION. Khi ARRIVED_AT_INTERMEDIATE_destination, điểm đến trung gian hiện tại sẽ không bị xoá khỏi phần còn lại của Xe danh sách điểm tham chiếu cho đến khi xe báo cáo rằng xe đang đi đến điểm tham chiếu tiếp theo.
Khi trạng thái chuyến đi được thay đổi thành COMPLETED
, sẽ không có điểm tham chiếu nào từ chuyến đi này
trong danh sách điểm tham chiếu còn lại của Xe.
HƯỚNG DẪN: Tạo chuyến đi
Bạn phải tạo một thực thể Trip
để theo dõi và theo dõi mỗi yêu cầu chuyến đi
khớp với Xe trong nhóm xe. Sử dụng điểm cuối CreateTrip
với CreateTripRequest
để tạo một Chuyến đi.
Các thuộc tính sau đây là bắt buộc để tạo chuyến đi:
parent
- Một chuỗi bao gồm Mã nhà cung cấp được tạo khi Google Đã tạo dự án trên Cloud.trip_id
– Chuỗi do Nhà cung cấp dịch vụ đi chung xe tạo.trip
– Vùng chứa có siêu dữ liệu cơ bản mô tả chuyến đi.trip_type
– Enum thể hiện liệu chuyến đi có thể có người lái khác hay không từ điểm khởi hành và điểm đến khác trong cùng một chiếc xe (SHARED
) hoặc chỉ một bên (EXCLUSIVE
).pickup_point
– TerminalLocation biểu thị điểm gốc của . Tham khảo Tài liệu tham khảo về RPC hoặc tài liệu tham khảo về REST
Khi tạo chuyến đi, bạn có thể cung cấp number_of_passengers
, dropoff_point
và vehicle_id
. Mặc dù đây không phải là trường bắt buộc, nhưng nếu bạn cung cấp chúng,
thì chúng vẫn được giữ lại. Tất cả các trường Chuyến đi khác sẽ bị bỏ qua. Ví dụ: tất cả các chuyến đi
bắt đầu bằng trip_status
là NEW
ngay cả khi bạn truyền vào trip_status
CANCELED
trong yêu cầu tạo.
Ví dụ:
Ví dụ sau đây tạo ra một chuyến đi đến Trung tâm mua sắm Grand Indonesia East. Chuyến đi
dành cho hai hành khách và dành riêng cho hai hành khách. provider_id
của Trip
phải là
giống với Mã dự án. Trong ví dụ này, Nhà cung cấp dịch vụ đi chung xe đã tạo
Dự án trên Google Cloud, project-id. Dự án này phải có
Tài khoản dịch vụ dùng để gọi Fleet Engine. Trạng thái của chuyến đi là NEW
.
Sau đó, sau khi dịch vụ khớp với chuyến đi đến một chiếc xe, dịch vụ có thể gọi
UpdateTrip
và thay đổi vehicle_id
khi chuyến đi được chỉ định cho một chiếc xe.
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
Xem providers.trips.create tham chiếu.
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Nhật ký của Google Cloud Platform dành cho tính năng Tạo chuyến đi
API Fleet Engine ghi mục nhập nhật ký bằng cách sử dụng nhật ký của Google Cloud Platform khi
đã nhận được lệnh gọi đến điểm cuối CreateTrip
. Mục nhập nhật ký bao gồm
thông tin về các giá trị trong yêu cầu CreateTrip
. Nếu cuộc gọi
thành công thì tệp này cũng sẽ bao gồm thông tin về Trip
đã được trả về.
HƯỚNG DẪN: Cập nhật chuyến đi
Thực thể Chuyến đi chứa các trường cho phép theo dõi theo dịch vụ và
báo cáo tiến trình của chuyến đi bằng SDK tài xế và cho
SDK người tiêu dùng. Để cập nhật các thuộc tính, hãy dùng UpdateTripRequest
. Thao tác này sẽ cập nhật các trường Chuyến đi theo field_mask
của yêu cầu.
Hãy tham khảo UpdateTripRequest.
Nhà cung cấp dịch vụ đi chung xe chịu trách nhiệm cập nhật các thuộc tính sau:
- Trạng thái chuyến đi.
- Mã xe. Tại thời điểm tạo hoặc sau khi so khớp xe với một .
- Thay đổi đối với điểm đến lấy hàng, trả khách hoặc điểm tham chiếu.
Fleet Engine tự động cập nhật các trường sau đây khi sử dụng Tính năng Chia sẻ hành trình thông qua SDK trình điều khiển hoặc SDK người tiêu dùng:
- Tuyến đường
- ETA
- Quãng đường còn lại
- Vị trí xe
- Điểm tham chiếu còn lại
Tham khảo Trip
trong RPC hoặc
Resource.Trip
trong REST.
Nhật ký của Google Cloud Platform cho thông tin cập nhật về chuyến đi
API Fleet Engine ghi mục nhập nhật ký bằng cách sử dụng nhật ký của Google Cloud Platform khi
đã nhận được lệnh gọi đến điểm cuối UpdateTrip
. Mục nhập nhật ký bao gồm
thông tin về các giá trị trong yêu cầu UpdateTrip
. Nếu lệnh gọi thành công,
thì mã này cũng sẽ bao gồm thông tin về Trip
đã được trả về.
HƯỚNG DẪN: Tìm kiếm chuyến đi
Fleet Engine hỗ trợ tìm kiếm các chuyến đi. Như đã lưu ý trước đó, một Chuyến đi là
tự động bị xoá sau 7 ngày, nên SearchTrips
sẽ không
hiển thị toàn bộ nhật ký về tất cả Chuyến đi.
Mặc dù SearchTrips
là API linh hoạt, nhưng danh sách dưới đây xem xét 2 trường hợp sử dụng.
Xác định chuyến đi đang hoạt động của xe -- Nhà cung cấp có thể xác định các chuyến đi hiện đang hoạt động của xe. Trong
SearchTripsRequest
,vehicle_id
được đặt thành xe đang được xem xét vàactive_trips_only
phải được đặt thànhtrue
.Đối chiếu trạng thái Nhà cung cấp và Trạng thái công cụ nhóm – Nhà cung cấp có thể sử dụng
SearchTrips
để đảm bảo trạng thái Chuyến đi của họ và trạng thái của Fleet Engine trùng khớp. Điều này đặc biệt quan trọng đối với TripStatus. Nếu trạng thái của chuyến đi đã được chỉ định với Xe chưa được đặt đúng cách thànhCOMPLETE
hoặcCANCELED
thì Xe không có trongSearchVehicles
.
Để sử dụng SearchTrips
theo cách này, hãy để trống vehicle_id
, đặt active_trips_only
thành true
rồi đặt minimum_staleness
thành khoảng thời gian lớn hơn hầu hết thời lượng chuyến đi.
Ví dụ: bạn có thể sử dụng một giờ. Kết quả bao gồm Chuyến đi không được
ĐÃ HOÀN THÀNH hoặc ĐÃ HUỶ và chưa được cập nhật trong hơn một giờ. Nhà cung cấp
nên kiểm tra các Chuyến đi này để đảm bảo rằng trạng thái của chúng trong Fleet Engine là
được cập nhật đúng cách.
Khắc phục sự cố
Trong trường hợp xảy ra Lỗi DEADLINE_EXCEEDED
, trạng thái của Fleet Engine là
không xác định. Nhà cung cấp sẽ gọi lại CreateTrip
để trả về một
201 (ĐÃ TẠO) hoặc 409 (Xung đột). Trong trường hợp sau, yêu cầu trước đó đã thành công
trước DEADLINE_EXCEEDED
. Xem hướng dẫn về API người tiêu dùng để biết thêm thông tin
về cách xử lý lỗi chuyến đi: Android
hoặc iOS.
Hỗ trợ đi chung xe
Bạn có thể chỉ định nhiều chuyến đi SHARED
cho một xe hỗ trợ TripType.SHARED
.
Bạn cần chỉ định thứ tự của tất cả các điểm tham chiếu không được vượt qua cho tất cả Chuyến đi được chỉ định cho
Xe trong chuyến đi chung này qua Trip.vehicle_waypoints
khi bạn chỉ định
vehicle_id
cho một chuyến đi chung (trong yêu cầu CreateTrip
hoặc UpdateTrip
).
Tham khảo vehicle_waypoints
đối với RPC
hoặc vehicleWaypoints
cho REST.
Hỗ trợ nhiều đích đến
Xác định một đích đến trung gian
Trường intermediateDestinations
và trường intermediateDestinationIndex
trong Chuyến đi (RPC | REST)
được kết hợp để dùng cho mục đích biểu thị đích đến.
Cập nhật vị trí xuất hiện trung gian
Bạn có thể cập nhật các đích đến trung gian thông qua UpdateTrip
. Khi cập nhật
đích đến trung gian, bạn phải cung cấp một danh sách đầy đủ các đích đến trung gian,
bao gồm cả những trang web đã được truy cập, chứ không chỉ là trang web mới
thêm hoặc cần sửa đổi.
Khi intermediateDestinationIndex
trỏ đến một chỉ mục sau vị trí của
đích đến trung gian mới được thêm/sửa đổi, đích đến trung gian mới/cập nhật
điểm đến sẽ không được thêm vào waypoints
của Xe hoặc remainingWaypoints
của Chuyến đi.
Lý do là mọi đích đến trung gian trước intermediateDestinationIndex
được coi là đã được truy cập.
Các thay đổi về trạng thái chuyến đi
Trường intermediateDestinationsVersion
trong (RPC | REST)
là bắt buộc trong yêu cầu cập nhật trạng thái Chuyến đi được gửi đến Fleet Engine để cho biết
đã vượt qua một đích đến trung gian. Đích đến trung gian được nhắm đến
được chỉ định qua trường intermediateDestinationIndex
.
Khi tripStatus
(RPC | REST) là ENROUTE_TO_INTERMEDIATE_Destination, một số nằm giữa
[0..N-1] cho biết điểm đến trung gian nào xe sẽ đi qua tiếp theo.
Khi tripStatus
là ARRIVED_AT_INTERMEDIATE_destination, một số nằm giữa
[0..N-1] cho biết xe đang ở điểm đến trung gian nào.
Ví dụ:
Ví dụ về mã sau đây minh hoạ cách cập nhật trạng thái của một chuyến đi để đang lên tuyến với đích đến trung gian đầu tiên, giả sử rằng bạn đã tạo một chuyến đi nhiều điểm đến và chuyến đi đã qua điểm đón.
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// Trip update request
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the
// update mask.
.build())
.build();
// Error handling
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
CÁCH THỰC HIỆN: Đăng ký nhận thông báo từ API Fleet Engine
API Fleet Engine sử dụng Google Cloud Pub/Sub để xuất bản thông báo về chủ đề do người dùng thông thường tạo bằng Google Cloud Dự án. Theo mặc định, Pub/Sub không được bật cho Fleet Engine trên Google Cloud dự án. Vui lòng gửi yêu cầu hỗ trợ hoặc liên hệ với Kỹ sư khách hàng của bạn để bật Pub/Sub.
Để tạo một chủ đề trong dự án trên Google Cloud, hãy làm theo hướng dẫn tại đây. Mã chủ đề phải là 'fleet_engine_notification'.
Chủ đề phải được tạo trong cùng một dự án Cloud có tên là Fleet Engine API.
Sau khi tạo chủ đề, bạn sẽ cần cấp cho Fleet Engine API
quyền xuất bản về chủ đề này. Để làm như vậy, hãy nhấp vào chủ đề mà bạn
vừa tạo và thêm quyền mới. Bạn có thể phải nhấp vào HIỂN THỊ BẢNG ĐIỀU KHIỂN THÔNG TIN để mở trình chỉnh sửa quyền.
Tên chính phải là geo-fleet-engine@system.gserviceaccount.com
và vai trò sẽ là Pub/Sub publisher
.
Để thiết lập dự án trên đám mây của bạn cho việc đăng ký nhận thông báo, làm theo các hướng dẫn này
Fleet Engine API sẽ xuất bản từng thông báo trong hai dữ liệu khác nhau
protobuf
và
json
. Định dạng dữ liệu của mỗi thông báo được biểu thị trong
Thuộc tính PubsubMessage
với khoá là data_format
và giá trị là protobuf
hoặc json
.
Giản đồ thông báo:
Protobuf
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}