Tạo chuyến đi gộp được chia sẻ

Tài liệu này mô tả cách tạo một chuyến đi ghép xe, đặt các trường chính xác và chỉ định chuyến đi đó cho một chiếc xe để thực hiện. Tài liệu này giả định rằng bạn đã thiết lập Fleet Engine, đã tạo xe, có một ứng dụng dành cho tài xế đang hoạt động và tuỳ ý có một ứng dụng dành cho người tiêu dùng. Bạn cũng nên làm quen với nhiều kịch bản chuyến đi có sẵn cho các chuyến đi theo yêu cầu. Hãy xem các hướng dẫn liên quan sau đây để biết thông tin đó:

Thiết lập Fleet Engine
Tạo xe
Các kịch bản chuyến đi trong phần tổng quan về Chuyến đi theo yêu cầu

Kiến thức cơ bản về việc tạo chuyến đi

Phần này mô tả thông tin chi tiết về yêu cầu cần thiết để tạo một chuyến đi trong Fleet Engine. Bạn đưa ra yêu cầu tạo bằng gRPC hoặc REST.

CreateTrip() phương thức: gRPC hoặc REST
Thông báo CreateTripRequest: gRPC

Trường chuyến đi

Sử dụng các trường sau để tạo một chuyến đi trong Fleet Engine. Bạn có thể sử dụng các trường khác nhau cho nhiều loại chuyến đi: một hoặc nhiều điểm đến, liên tiếp hoặc chuyến đi ghép xe. Bạn có thể cung cấp các trường không bắt buộc khi tạo chuyến đi hoặc bạn có thể đặt các trường này sau khi cập nhật chuyến đi.

Trường chuyến đi
Tên	Bắt buộc?	Mô tả
parent	Có	Một chuỗi bao gồm mã dự án. Mã này phải là mã giống nhau được sử dụng trên toàn bộ quá trình tích hợp Fleet Engine, với các vai trò tài khoản dịch vụ giống nhau.
trip_id	Có	Một chuỗi do bạn tạo để xác định duy nhất chuyến đi này. Mã chuyến đi có một số hạn chế nhất định, như được nêu trong tài liệu tham khảo.
trip_type	Có	Đặt TripType thành các giá trị sau cho loại chuyến đi mà bạn đang tạo: Một điểm đến: Đặt thành `SHARED` hoặc `EXCLUSIVE`. Nhiều điểm đến: Đặt thành `EXCLUSIVE`. Liên tiếp: Đặt thành `EXCLUSIVE`. Ghép xe: Đặt thành `SHARED`.
pickup_point	Có	Điểm khởi hành của chuyến đi.
Điểm đến trung gian	Có	Chỉ chuyến đi nhiều điểm đến: Danh sách các điểm đến trung gian mà tài xế ghé thăm giữa điểm đón và điểm trả khách. Tương tự như `dropoff_point`, bạn cũng có thể đặt trường này sau bằng cách gọi `UpdateTrip`, nhưng theo định nghĩa, chuyến đi nhiều điểm đến chứa các điểm đến trung gian.
vehicle_waypoints	Có	Chỉ chuyến đi ghép xe: Trường này hỗ trợ xen kẽ các điểm tham chiếu từ nhiều chuyến đi. Trường này chứa tất cả các điểm tham chiếu còn lại cho xe được chỉ định, cũng như các điểm tham chiếu đón và trả khách cho chuyến đi này. Bạn có thể đặt trường này bằng cách gọi `CreateTrip` hoặc `UpdateTrip`. Bạn cũng có thể cập nhật các điểm tham chiếu của xe thông qua trường `waypoints` bằng cách gọi `UpdateVehicle`. Dịch vụ không trả về thông tin này trên các lệnh gọi `GetTrip` vì lý do liên quan đến quyền riêng tư.
number_of_passengers	Không	Số lượng hành khách trên chuyến đi.
dropoff_point	Không	Điểm đến của chuyến đi.
vehicle_id	Không	Mã của xe được chỉ định cho chuyến đi.

Ví dụ: tạo một chuyến đi ghép xe

Mẫu tích hợp phần phụ trợ sau đây minh hoạ cách tạo một chuyến đi và chỉ định chuyến đi đó cho một chiếc xe dưới dạng chuyến đi ghép xe.

// Vehicle with VEHICLE_ID ID is already created and it is assigned Trip A.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "shared-trip-A";
static final String VEHICLE_ID = "your-vehicle-id";
static final String TRIP_A_ID = "trip-a-id";
static final String TRIP_B_ID = "trip-b-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;

LatLng tripBPickup =
    LatLng.newBuilder().setLatitude(-12.12314).setLongitude(88.142123).build();
LatLng tripBDropoff =
    LatLng.newBuilder().setLatitude(-14.12314).setLongitude(90.142123).build();

TerminalLocation tripBPickupTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBPickup).build();
TerminalLocation tripBDropoffTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBDropoff).build();

// TripA already exists and it's assigned to a vehicle with VEHICLE_ID ID.
Trip tripB = Trip.newBuilder()
    .setTripType(TripType.SHARED)
    .setVehicleId(VEHICLE_ID)
    .setPickupPoint(tripBPickupTerminalLocation)
    .setDropoffPoint(tripBDropoffTerminalLocation)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripBPickupTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripBDropoffTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// Create Trip request
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_B_ID)
    .setTrip(tripB)
    .build();

try {
  // createdTrip.remainingWaypoints will contain shared-pool waypoints.
  // [tripB.pickup, tripA.dropoff, tripB.dropoff]
  Trip createdTrip = tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Cập nhật chuyến đi ghép xe

Mọi chuyến đi được tạo trong Fleet Engine đều phải được chỉ định cho một chiếc xe để Fleet Engine có thể tính toán thời gian đến dự kiến (ETA) của chuyến đi và theo dõi chuyến đi đó. Bạn có thể thực hiện việc này trong quá trình tạo chuyến đi hoặc sau khi cập nhật chuyến đi.

Đối với các chuyến đi ghép xe, bạn phải chỉ định một thứ tự cho các điểm tham chiếu chưa được ghé thăm trong tập hợp các điểm tham chiếu của xe trong chuyến đi (Trip.vehicle_waypoints). Fleet Engine sử dụng danh sách này để tự động cập nhật các điểm tham chiếu của chuyến đi cho tất cả các chuyến đi trong nhóm ghép xe.

Ví dụ: hãy xem xét 2 chuyến đi ghép xe, Chuyến đi A và Chuyến đi B:

Chuyến đi A đang trên đường đến điểm trả khách.
Chuyến đi B sau đó được thêm vào cùng một chiếc xe.

Trong một UpdateTripRequest cho Chuyến đi B, bạn đặt vehicleId và cũng đặt Trip.vehicle_waypoints thành thứ tự điểm tham chiếu tối ưu: B _{Điểm đón} → A _{Điểm trả khách} → B _{Điểm trả khách}.

Việc gọi getVehicle() sẽ trả về remainingWaypoints chứa:
Điểm đón _B → Điểm trả khách _A → Điểm trả khách _B.
_{_{`getTrip()` hoặc lệnh gọi lại
onTripRemainingWaypointsUpdated cho
Chuyến đi A sẽ trả về remainingWaypoints
chứa:

Điểm đón B →
Điểm trả khách A.}}getTrip()
_{_{_{getTrip() hoặc lệnh gọi lại
onTripRemainingWaypointsUpdated cho
Chuyến đi B sẽ trả về remainingWaypoints
chứa:

Điểm đón} B →
Điểm trả khách} A →
Điểm trả khách} B.

Ví dụ:

Mẫu tích hợp phần phụ trợ sau đây minh hoạ cách cập nhật một chuyến đi bằng mã xe và các điểm tham chiếu cho 2 chuyến đi ghép xe.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_A_ID = "share-trip-A";
static final String TRIP_B_ID = "share-trip-B";
static final String VEHICLE_ID = "Vehicle";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_B_ID;

// Get Trip A and Trip B objects from either the Fleet Engine or storage.
Trip tripA = …;
Trip tripB = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId(VEHICLE_ID)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getPickupPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getDropoffPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_id")
        .addPaths("vehicle_waypoints"))
    .build();

// Error handling. If Fleet Engine has both a trip and vehicle with the IDs,
// and if the credentials validate, and if the given vehicle_waypoints list
// is valid, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:          // Either the trip or vehicle does not exist.
      break;
    case PERMISSION_DENIED:
      break;
    case INVALID_REQUEST:    // vehicle_waypoints is invalid.
      break;
  }
  return;
}

Bước tiếp theo

Thiết lập Driver SDK