Tạo các chuyến đi nhiều điểm đến

Tài liệu này mô tả cách tạo chuyến đi nhiều điểm đến, đặt đúng các trường và chỉ định chuyến đi đó cho một xe để thực hiện. Giả sử bạn đã thiết lập Công cụ của đội xe, bạn đã tạo xe, có ứng dụng trình điều khiển đang hoạt động và có thể có ứng dụng người dùng. Bạn cũng nên nắm rõ các tình huống chuyến đi khác nhau 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 để rằng:

• Thiết lập Công cụ của đội xe
• Tạo xe
• Tình huống 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 Công cụ quản lý đội xe. 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 ý: Việc sử dụng CreateTrip() yêu cầu thông tin đăng nhập cho tài khoản đặc quyền đề cập trong Fleet Engine: Vai trò trong tài khoản dịch vụ.

Trường chuyến đi

Sử dụng các trường sau để tạo một chuyến đi trong Công cụ quản lý đội xe. Bạn có thể sử dụng các trường cho các loại chuyến đi khác nhau: một điểm đến hoặc nhiều điểm đến, các chuyến đi gộp hoặc liên kết chung. Bạn có thể cung cấp các trường tuỳ chọn khi tạo chuyến đi, hoặc bạn có thể đặt các trường đó khi bạn cập nhật chuyến đi.

Trường chuyến đi

Tên	Bắt buộc?	Mô tả
cha mẹ	Có	Một chuỗi chứa mã dự án. Mã này phải giống với mã được sử dụng trong toàn bộ quá trình tích hợp Fleet Engine, với cùng vai trò tài khoản dịch vụ.
trip_id	Có	Một chuỗi bạn tạo để nhận dạng duy nhất chuyến đi này. Mã chuyến đi có 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 (Quay lại): Đặt thành EXCLUSIVE. Gộp chung: Đặt thành SHARED.
pickup_point	Có	Điểm xuất phát của chuyến đi.
Đích đến trung gian	Có	Chỉ dành cho 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 trong khoảng thời gian từ khi đón đến khi trả khách. Giống như dropoff_point, bạn cũng có thể thiết lập 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 sẽ chứa các điểm đến trung gian.
vehicle_waypoints	Có	Chỉ dành cho các chuyến đi chung: Trường này hỗ trợ xen kẽ các điểm trung gian của nhiều chuyến đi. Tệp này chứa tất cả các điểm trung gian còn lại cho xe được chỉ định, cũng như điểm trung gian đón và trả khách cho chuyến đi này. Bạn có thể thiết lập 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 qua trường waypoints bằng gọi đến UpdateVehicle. Dịch vụ 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ư.
số_người_cùng_đi	Không	Số lượng hành khách trên chuyến đi.
điểm_đưa_rơi	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 chuyến đi nhiều điểm đến

Phần sau đây minh hoạ cách tạo một chuyến đi nhiều điểm đến độc quyền có điểm đón, điểm trả khách và một điểm đến trung gian.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip initial settings.
String parent = "providers/" + PROJECT_ID;

Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE)
    .setPickupPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.195139).setLongitude(106.820826)))
    .setNumberOfPassengers(1)
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.1275).setLongitude(106.6537)))
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .build();

// Create the Trip request.
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_ID)  // Trip ID assigned by the Provider server.
    .setTrip(trip)       // Initial state is NEW.
    .build();

// Error handling.
try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:  // Trip already exists.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Cập nhật chuyến đi có nhiều điểm đến

Bạn phải định cấu hình chuyến đi bằng mã nhận dạng xe để Công cụ quản lý đội xe có thể theo dõi xe dọc theo tuyến đường của xe. Để biết chi tiết về cách cập nhật chuyến đi, hãy xem Cập nhật chuyến đi và quản lý trạng thái chuyến đi.

Nếu không chỉ định điểm trả khách hoặc điểm trung gian khi tạo chuyến đi, bạn luôn có thể thực hiện việc này tại thời điểm này.

Lưu ý: Bất cứ khi nào bạn đặt hoặc cập nhật intermediate_destinations trên một chuyến đi, Công cụ quản lý đội xe sẽ điền sẵn intermediate_destinations_version trong thực thể chuyến đi đã tạo. Bạn phải lưu trường này vào bộ nhớ đệm trong hệ thống của mình và chuyển vào UpdateTripRequest khi bạn cập nhật intermediate_destination_index sau này. Điều này giúp các đích đến trung gian đồng bộ hoá giữa ứng dụng trình điều khiển và Công cụ của đội xe.

Ví dụ về thông tin cập nhật chuyến đi

Phần sau đây minh hoạ cách cập nhật một chuyến đi để thêm danh sách các điểm đến trung gian và đặt mã nhận dạng xe.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

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

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .setVehicleId("8241890")
    .build();

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

// Error handling.
try {
  Trip updatedTrip =
      tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:            // The trip doesn't exist.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Quản lý trạng thái chuyến đi cho các chuyến đi nhiều điểm đến

Bạn chỉ định trạng thái của một chuyến đi bằng một trong các giá trị liệt kê TripStatus giá trị. Khi trạng thái của chuyến đi thay đổi, ví dụ như từ ENROUTE_TO_PICKUP thành ARRIVED_AT_PICKUP thân mến, bạn phải cập nhật trạng thái chuyến đi trong Fleet Engine. Chuyến đi trạng thái luôn bắt đầu bằng giá trị NEW và kết thúc bằng giá trị COMPLETE hoặc CANCELED.

Đối với chuyến đi nhiều điểm đến, ngoài việc cập nhật trạng thái chuyến đi như bạn làm đối với chuyến đi một điểm đến, bạn cũng phải cập nhật những thông tin sau mỗi khi xe của bạn đến một điểm đến trung gian:

• intermediateDestinationIndex
• intermediateDestinationsVersion

Để thực hiện việc này, hãy sử dụng các giá trị sau đây trong bản liệt kê TripStatus.

• ENROUTE_TO_PICKUP
• ARRIVED_AT_PICKUP
• ENROUTE_TO_INTERMEDIATE_DESTINATION
• ARRIVED_AT_INTERMEDIATE_DESTINATION
• ENROUTE_TO_DROPOFF
• COMPLETE

Lưu ý: Chuyến đi sẽ chuyển đổi qua cả hai ENROUTE_TO_INTERMEDIATE_DESTINATION và ARRIVED_AT_INTERMEDIATE_DESTINATION một lần cho mỗi đích đến trung gian.

Ví dụ về chuyến đi có điểm đến trung gian

Phần sau đây cho biết cách tạo một chuyến đi nhiều điểm đến đã đi qua điểm đón và hiện đang trên đường đến điểm đến trung gian đầu tiên.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

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

// Get the trip object from either the Fleet Engine or storage.
Trip trip = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Trip status cannot return to a previous state once it has passed.
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)

    // Enroute to the first intermediate destination.
    .setIntermediateDestinationIndex(0)

    // You must provide an intermediate_destinations_version to ensure that you
    // have the same intermediate destinations list as the Fleet Engine.
    .setIntermediateDestinationsVersion(
         trip.getIntermediateDestinationsVersion())
    .build();

// The 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:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // Either the trip status is invalid, or the
                               // intermediate_destinations_version doesn't
                               // match Fleet Engine's.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Các bước tiếp theo

• Tạo chuyến đi liên tiếp
• Thiết lập SDK trình điều khiển