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

Tài liệu này mô tả cách tạo một chuyến đi có nhiều điểm đến, đặ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à không bắt buộc phải có ứ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:

Thông tin 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 cách sử dụng gRPC và REST.

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

Trường chuyến đi

Hãy sử dụng các trường sau đây để 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 chung. 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 giống với mã được sử dụng trong toàn bộ quá trình tích hợp Fleet Engine, có cùng vai trò của tài khoản dịch vụ.
trip_id Có Một chuỗi mà 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ư được chỉ ra 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.
  • Chuyến đi 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ỉ 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. Tương tự như dropoff_point, trường này cũng có thể đặt 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ỉ chuyến đi chung: 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ụ này không trả về thông tin này trên các lệnh gọi GetTrip vì lý do 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 có nhiều điểm đến

Ví dụ sau đây minh hoạ cách tạo một chuyến đi riêng có nhiều điểm đế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ã xe để Fleet Engine có thể theo dõi xe dọc theo tuyến đường. Để biết thông tin chi tiết về cách cập nhật chuyến đi, hãy xem bài viết Cập nhật chuyến đi và quản lý trạng thái của chuyến đi.

Nếu không chỉ định điểm trả khách hoặc điểm đến 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.

Ví dụ về việc cập nhật chuyến đi

Ví dụ 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ã 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 chuyến đi có nhiều điểm đến

Bạn chỉ định trạng thái của một chuyến đi bằng cách sử dụng một trong các TripStatus giá trị liệt kê. Khi trạng thái của một chuyến đi thay đổi, chẳng hạn như từ ENROUTE_TO_PICKUP thành ARRIVED_AT_PICKUP, bạn phải cập nhật trạng thái chuyến đi trong Fleet Engine. Trạng thái chuyến đ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 có nhiều điểm đến, ngoài việc cập nhật trạng thái chuyến đi như đối với chuyến đi có một điểm đến, bạn cũng phải cập nhật các thông tin sau đây 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 danh sách liệt kê TripStatus.

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

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

Ví dụ sau đây cho biết cách tạo một chuyến đi có nhiều điểm đến đã 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;
}

Bước tiếp theo