Bắt đầu với Công cụ nhóm

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.

gcloud auth login

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.

gcloud --project=project-id services enable fleetengine.googleapis.com

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:

1. Tạo một dự án trên Google Cloud bằng Google Cloud Console.
2. 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:

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:

Phần thông báo xác nhận quyền sở hữu JWT chứa các trường sau:

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ường private_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ường client_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:

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

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 để bao gồ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ụ:

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

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.

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'

---
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ụ:

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

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.

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

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.

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.

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

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

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.

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

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;
}

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.

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

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 Triptrong 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ành true.

• Đố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ành COMPLETE hoặc CANCELED thì Xe không có trong SearchVehicles.

Để 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.

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;
}

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

• Xe
• FieldMask

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"
    }
  }
}