다중 목적지 경로 만들기

이 문서에서는 여러 목적지 이동을 만들고, 올바른 필드를 설정하고, 이동을 처리할 차량에 할당하는 방법을 설명합니다. Fleet Engine을 설정하고, 차량을 만들고, 작동하는 드라이버 앱과 소비자 앱(선택사항)이 있다고 가정합니다. 또한 주문형 이동에 사용할 수 있는 다양한 이동 시나리오에 익숙해야 합니다. 자세한 내용은 다음 관련 가이드를 참고하세요.

여행 항목 만들기 기본사항

이 섹션에서는 Fleet Engine에서 이동을 만드는 데 필요한 요청 세부정보를 설명합니다. gRPC 및 REST를 사용하여 생성 요청을 실행합니다.

  • CreateTrip() 메서드: gRPC 또는 REST
  • CreateTripRequest 메시지: gRPC만 해당

이동 필드

다음 필드를 사용하여 Fleet Engine에서 이동을 만듭니다. 단일 또는 다중 목적지, 연속, 공유 풀링 이동 등 다양한 유형의 이동에 서로 다른 필드를 사용할 수 있습니다. 이동을 만들 때 선택적 필드를 제공하거나 나중에 이동을 업데이트할 때 설정할 수 있습니다.

이동 필드
이름 필수 여부 설명
parent 예 프로젝트 ID가 포함된 문자열입니다. 이 ID는 동일한 서비스 계정 역할로 전체 Fleet Engine 통합에서 사용되는 ID와 동일해야 합니다.
trip_id 예 이 이동을 고유하게 식별하는 문자열입니다. 이동 ID에는 참조에 표시된 대로 특정 제한사항이 있습니다.
trip_type 예 만들려는 이동 유형에 따라 TripType을 다음 값으로 설정합니다.
  • 단일 대상: SHARED 또는 EXCLUSIVE로 설정합니다.
  • 다중 대상: EXCLUSIVE로 설정합니다.
  • 연속: EXCLUSIVE로 설정합니다.
  • 공유 풀링: SHARED로 설정합니다.
pickup_point 예 이동의 출발지입니다.
중간 목적지 예

여러 목적지 이동만 해당: 운전자가 승차와 하차 사이에 방문하는 중간 목적지 목록입니다. dropoff_point와 마찬가지로 이 필드도 나중에 UpdateTrip를 호출하여 설정할 수 있지만, 여러 목적지 이동에는 정의상 중간 목적지가 포함됩니다.
vehicle_waypoints 예

공유 풀링 이동만 해당: 이 필드는 여러 이동의 경유지를 인터리브 처리하는 것을 지원합니다. 여기에는 할당된 차량의 나머지 모든 경유지와 이 이동의 승차 및 하차 경유지가 포함됩니다. CreateTrip 또는 UpdateTrip를 호출하여 이 필드를 설정할 수 있습니다. UpdateVehicle 호출을 통해 waypoints 필드를 사용하여 차량 경유지를 업데이트할 수도 있습니다. 개인 정보 보호를 위해 서비스는 GetTrip 호출에 이 정보를 반환하지 않습니다.
number_of_passengers 아니요 이동에 탑승한 승객 수입니다.
dropoff_point 아니요 이동의 목적지입니다.
vehicle_id 아니요 이동에 할당된 차량의 ID입니다.

예: 여러 목적지가 있는 이동 만들기

다음은 승차 지점, 하차 지점, 중간 목적지 1개가 있는 단독 다중 목적지 이동을 만드는 방법을 보여줍니다.

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

여러 목적지 이동 업데이트

Fleet Engine이 경로를 따라 차량을 추적할 수 있도록 차량 ID로 이동을 구성해야 합니다. 이동 업데이트에 관한 자세한 내용은 이동 업데이트 및 상태 관리를 참고하세요.

이동을 만들 때 하차 또는 중간 목적지를 지정하지 않은 경우 이 시점에서 언제든지 지정할 수 있습니다.

이동 업데이트 예시

다음은 이동을 업데이트하여 중간 목적지 목록을 추가하고 차량 ID를 설정하는 방법을 보여줍니다.

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

여러 목적지 이동의 이동 상태 관리

TripStatus 열거형 값 중 하나를 사용하여 이동 상태를 지정합니다. 이동 상태가 변경되면(예: ENROUTE_TO_PICKUP에서 ARRIVED_AT_PICKUP로) Fleet Engine에서 이동 상태를 업데이트해야 합니다. 이동 상태는 항상 NEW 값으로 시작하고 COMPLETE 또는 CANCELED 값으로 끝납니다.

여러 목적지 이동의 경우 단일 목적지 이동과 마찬가지로 이동 상태를 업데이트하는 것 외에도 차량이 중간 목적지에 도달할 때마다 다음을 업데이트해야 합니다.

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

이렇게 하려면 TripStatus 열거형의 다음 값을 사용합니다.

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

중간 목적지가 있는 이동 예시

다음은 승차 지점을 지나 첫 번째 중간 목적지로 이동 중인 다중 목적지 이동을 만드는 방법을 보여줍니다.

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

다음 단계