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 chung, đặt các trường chính xác và chỉ định chuyến đi đó cho một xe để thực hiện. Tài liệu này giả định rằng bạn đã thiết lập Công cụ quản lý đội xe, đã tạo xe, có một ứng dụng cho tài xế đang hoạt động và có thể có một ứng dụng cho người tiêu dùng. Bạn cũng nên làm quen với nhiều tình huống 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êm thông tin:

• Thiết lập Fleet Engine
• Tạo xe
• Các trường hợp 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ề cách 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 chuyến đi trong Fleet Engine. Bạn đưa ra yêu cầu tạo bằng gRPC và REST.

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

Lưu ý: Để sử dụng CreateTrip(), bạn cần có thông tin đăng nhập cho tài khoản đặc quyền được đề cập trong phần Fleet Engine: Vai trò của tài khoản dịch vụ.

Trường chuyến đi

Sử dụng các trường sau để tạo 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: chuyến đi một hoặc nhiều điểm đến, chuyến đi liên tiếp hoặc chuyến đi chung. Bạn có thể cung cấp các trường tuỳ chọn khi tạo chuyến đi hoặc có thể đặt các trường đó 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 chứa mã dự án. Mã này phải giống với mã được dùng trong toàn bộ quá trình tích hợp Fleet Engine, có cùng vai trò tài khoản dịch vụ.
trip_id	Có	Một chuỗi do bạn tạo để xác định riêng biệ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 đích đến: Đặt thành SHARED hoặc EXCLUSIVE. Nhiều đích đến: Đặt thành EXCLUSIVE. Back-to-back (Liên tiếp): Đặt thành EXCLUSIVE. Gộp chung bộ nhớ dùng chung: Đặt thành SHARED.
pickup_point	Có	Điểm xuất phát của chuyến đi.
Điểm đến trung gian	Có	Chỉ dành cho chuyến đi có 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. Giống 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 có nhiều điểm đến sẽ chứa các điểm đến trung gian.
vehicle_waypoints	Có	Chỉ dành cho chuyến đi chung: Trường này hỗ trợ việc xen kẽ các điểm tham chiếu của nhiều chuyến đi. Danh sách 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 điểm tham chiếu của xe thông qua trường waypoints bằng lệnh gọi đến UpdateVehicle. Dịch vụ này không trả về thông tin này trong 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 trong 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 chung 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 xe dưới dạng chuyến đi chung.

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

Thử nghiệm: Là một tính năng thử nghiệm, trường TerminalLocation (gRPC hoặc REST) hiện hỗ trợ việc sử dụng place (gRPC hoặc REST), cùng với hoặc thay cho LatLng.

Cập nhật chuyến đi chung xe

Mọi chuyến đi được tạo trong Fleet Engine đều phải được chỉ định cho một xe để Fleet Engine có thể tính toán thời gian đến dự kiến 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 chung, bạn phải chỉ định thứ tự cho các điểm tham chiếu chưa ghé thăm trong tập hợp đ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 chung.

Ví dụ: hãy xem xét hai chuyến đi chung, Chuyến đi A và Chuyến đi B:

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

Trong một UpdateTripRequest cho Chuyến đi B, bạn đặt vehicleId, đồng thời đặ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:
  B _{Lấy hàng} → A _{Giao hàng} → B _{Giao hàng}.
• getTrip() hoặc lệnh gọi lại onTripRemainingWaypointsUpdated cho Chuyến đi A trả về remainingWaypoints chứa:
  B _{Điểm đón} → A _{Điểm trả khách}.
• Lệnh gọi lại getTrip() hoặc onTripRemainingWaypointsUpdated cho Chuyến đi B trả về remainingWaypoints chứa:
  Điểm đón khách 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à điểm tham chiếu cho hai chuyến đi chung.

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 SDK Tài xế