이 문서에서는 실제 사용 사례 시나리오를 사용하여 Route Optimization API에 첫 번째 요청을 하는 방법을 보여줍니다.
이 예시에서는 편의상 HTTP 및 JSON을 사용하여 REST API를 보여줍니다. 하지만 프로덕션 환경에서는 성능 이점을 위해 gRPC를 사용하는 것이 좋습니다. 하지만 gRPC는 설치가 필요합니다. 자세한 내용은 Route Optimization API 클라이언트 라이브러리를 참고하세요.
시나리오
샌프란시스코에서 오전 7시부터 오후 7시까지 반려견 위탁 서비스를 운영하고 있습니다. 오늘 아침에는 도시의 여러 위치에서 세 마리의 개를 데려와 데이케어 센터로 데려가려고 합니다.
버니즈 마운틴 도그와 치와와는 지난주에 예약한 단골 고객입니다. 저먼 셰퍼드는 막바지에 새로 추가된 요청입니다. 가능하면 저먼 셰퍼드를 수용하고 싶지만 일반 고객을 희생시키지 않아야 합니다.
작업에 사용할 밴이 한 대 있고 운전자에게 시간당 $27를 지불합니다. 운전자와 밴은 오전 7시에 어린이집에서 하루를 시작하고 점심시간을 위해 정오까지 아침 픽업을 마치고 돌아와야 합니다.
오늘은 2024년 2월 13일입니다. 이 시나리오의 모든 시간은 샌프란시스코 현지 시간이며, 2월의 태평양 표준시 (UTC-8)입니다. 드라이버에는 다음과 같은 태스크가 있습니다.
- 코이트 타워 근처에서 버니즈 마운틴 도그를 태우세요. 소유자는 오전 8시에서 오전 8시 20분 사이의 짧은 수거 시간을 요청했습니다.
- South Sunset Playground Park에서 치와와를 데려오세요. 소유자는 오전 7시 30분에서 오전 9시 30분 사이에 더 유연한 수령 시간을 제공했습니다.
- 랜드스 엔드에서 저먼 셰퍼드를 데려와 줘. 또한 소유자는 오전 8시에서 오전 8시 20분 사이의 짧은 수거 시간을 요청했습니다.
- 미션 돌로레스 공원의 반려견 유치원에 반려견을 맡깁니다. 어린이집은 오전 9시 30분에서 오전 11시 30분 사이에 등원해야 합니다.
각 승차 및 하차 방문 시 반려견을 태우거나 내리는 데 5분이 걸립니다.
Land's End는 Coit Tower에서 멀리 떨어져 있고 픽업 기간이 충돌하므로 운전자는 세 가지 픽업을 모두 수행할 수 없습니다. 최적화 도구는 총비용 (운전자 임금 및 건너뛰기 페널티)을 최소화하기 위해 건너뛸 개를 선택해야 합니다.
시작하기 전에
이 예시 시나리오에서 코드를 실행하려면 먼저 Route Optimization API 설정의 안내를 완료해야 합니다.
1. 경로 최적화 접근 방식 선택
Route Optimization API에는 최적화 문제의 복잡성에 따라 선택할 수 있는 여러 메서드가 있습니다.
이 반려견 유치원 시나리오는 작고 간단한 요청이므로 optimizeTours와 같은 차단 메서드를 사용하여 작은 요청에 대한 결과를 빠르게 제공합니다. Route Optimization API 엔드포인트에 대한 자세한 내용은 엔드포인트 선택을 참고하세요.
다음 URL을 사용하여 optimizeTours 메서드에 HTTP POST 요청을 수행합니다.
https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours
또한 불필요한 대기 시간을 줄이기 위해 제한 시간 및 기한 설정을 짧게 설정해야 합니다. 이 반려견 유치원 시나리오의 경우 최적화 도구는 요청에 응답하는 데 많은 시간이 필요하지 않으므로 다음 설정을 사용합니다.
timeout매개변수를 2초로 설정합니다.- 기한 설정을 기본값으로 둡니다. REST 요청의 경우 60초입니다.
2. 요청 메시지 본문 구성
차단 optimizeTours 메서드를 선택하고 제한 시간 및 기한 설정을 정의한 후 다음 단계는 요청 메시지의 본문을 구성하는 것입니다.
이 시나리오에서 요청은 REST API에서 JSON으로 인코딩된 OptimizeToursRequest 메시지입니다.
요청 메시지를 구성하려면 다음 단계를 따르세요.
기본 요청 구조로 시작합니다.
{ "timeout": ..., "model": { "shipments": [...], "vehicles": [...], "globalStartTime": "...", "globalEndTime": "..." } }구조에 대한 자세한 내용은 기본 구조 (ShipmentModel, Shipment, Vehicle)의 주요 개념 가이드를 참조하세요.
배송을 정의합니다.
shipments필드에서 아침에 데리러 가고 데려다줘야 하는 각 반려견에 대해Shipment메시지를 추가합니다. 여기에서 반려견 보호자가 선호하는 각 픽업 위치 및 시간과 반려견을 맡길 수 있는 어린이집의 위치 및 시간을 정의합니다.각 반려견에 대해 픽업을 위한
VisitRequest와 배송을 위한 또 다른 를 만듭니다. 이 시나리오에서는 이를 반려견 유치원 하차라고 합니다.픽업에서
arrivalWaypoint를 반려견의 픽업 위치 (버니즈 마운틴 도그의 경우 코이트 타워, 치와와의 경우 사우스 선셋 플레이그라운드 파크, 저먼 셰퍼드의 경우 랜드 엔드)로 설정합니다.timeWindows를 소유자가 요청한 승차 시간 (버니즈 마운틴 도그와 저먼 셰퍼드의 경우 오전 8시~오전 8시 20분, 치와와의 경우 오전 7시 30분~오전 9시 30분)으로 설정합니다.배송에서
arrivalWaypoint를 어린이집으로 설정하고timeWindows를 필요한 하차 시간 (오전 9시 30분~오전 11시 30분)으로 설정합니다.모든 수령 및 배송에 대해
duration를 5분 (300s)으로 설정하여 반려견을 태우고 내리는 시간을 고려합니다.
기간에 대한 자세한 내용은 기간을 참조하세요.
일반 고객의 우선순위를 지정하려면 버니즈 마운틴 도그와 치와와의 경우
penaltyCost를1000로 설정하고 저먼 셰퍼드의 경우100로 설정합니다. 페널티 비용이 설정되면 최적화 도구는 개를 건너뛸 수 있지만 제약 조건으로 인해 모든 픽업을 수행할 수 없는 경우 먼저 저먼 셰퍼드 (페널티가 더 낮음)를 건너뛰는 것을 고려합니다.label필드를 사용하여 각 배송에 대한 식별자(예: 'Bernese mountain dog', 'Chihuahua', 'German shepherd')를 추가할 수 있습니다. 이렇게 하면 응답에서 배송을 식별하는 데 도움이 됩니다.
배송 정의에 관한 자세한 내용은 배송을 참고하세요.
차량을 정의합니다.
vehicles필드에 어린이집을 시작점과 종료점으로 하는 밴 1대, 운전자 임금 비용, 밴 운영 시간에 대한Vehicle메시지를 추가합니다.밴의
startWaypoint및endWaypoint를 미션 돌로레스 공원 근처의 어린이집인 당일 시작 및 종료 위치로 설정합니다.운영 비용을 최소화하려면 비즈니스의 비용 제약 조건을 정의해야 합니다. 비용 매개변수
costPerHour를27로 설정합니다. 이는 반려견 유치원 차량을 운전하는 운전자에게 지불하는 금액입니다. 비용 매개변수에 대한 자세한 내용은 비용 모델을 참조하세요.최적화 도구가 밴의 운영 시간 내에 경로를 만들도록 하려면 차량의 운영 기간을 정의합니다. 이 기간은 경로의 시작 및 종료 시간 제약조건을 설정합니다. 각 시간대의 절반만 정의하면 최적화 도구가 경로를 나중에 시작하거나 더 일찍 종료할 수 있는 유연성을 제공합니다.
startTimeWindows에서startTime를 오전 7시로 설정하면 운전자가 오전 7시부터 교대 근무를 시작할 수 있습니다. 이른 아침에 픽업이 없는 경우 더 늦게 시작할 수도 있습니다.endTimeWindows의endTime를 정오로 설정하면 운전자가 정오까지 교대 근무를 종료해야 합니다. 마지막 배송을 완료하는 즉시 교대 근무를 종료할 수도 있습니다.
나머지 절반의 기간을 생략하면 운전자의 대기 시간과 우회 시간이 최소화됩니다. 기간에 대한 자세한 내용은 기간을 참조하세요.
차량 정의에 관한 자세한 내용은 차량을 참고하세요.
전역 기간을 설정합니다. 전역 시간대는 하루 동안 밴이 어린이집의 픽업 및 하차를 수행할 수 있는 기간을 나타냅니다. 이 시나리오에서는
globalStartTime를 오전 7시로,globalEndTime를 2024년 2월 13일 오후 7시로 설정합니다. 이는 반려견 유치원 운영 시간을 나타냅니다.
3. 요청 전송
다음은 반려견 유치원 시나리오를 기반으로 한 간단한 curl 요청이며 차단 optimizeTours 메서드를 사용합니다.
요청을 보내기 전에 샘플 코드의 PROJECT_NUMBER_OR_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
"timeout": "2s",
"model": {
"shipments": [
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.802395,
"longitude": -122.405822
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T08:00:00-08:00",
"endTime": "2024-02-13T08:20:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "Bernese mountain dog",
"penaltyCost": 1000
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.738067,
"longitude": -122.498593
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T07:30:00-08:00",
"endTime": "2024-02-13T09:30:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "Chihuahua",
"penaltyCost": 1000
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.78018,
"longitude": -122.51194
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T08:00:00-08:00",
"endTime": "2024-02-13T08:20:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "German shepherd",
"penaltyCost": 100
}
],
"vehicles": [
{
"startWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"endWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"costPerHour": 27,
"startTimeWindows": [
{
"startTime": "2024-02-13T07:00:00-08:00"
}
],
"endTimeWindows": [
{
"endTime": "2024-02-13T12:00:00-08:00"
}
]
}
],
"globalStartTime": "2024-02-13T07:00:00-08:00",
"globalEndTime": "2024-02-13T19:00:00-08:00"
}
}
EOM
요청에 사용된 요청 매개변수
다음 표에서는 예시 시나리오의 요청 본문에 사용된 요청 매개변수를 설명합니다. 상위 요소 또는 텍스트 검색으로 콘텐츠를 필터링할 수 있습니다.
| 부모 | 매개변수 | 숙소 유형 | 설명 |
|---|---|---|---|
OptimizeToursRequest |
model |
객체 (ShipmentModel) |
이것이 요청의 핵심입니다. 태우고 내려야 하는 모든 반려견 (shipments)과 차량(vehicles)을 포함하여 전체 문제를 정의하는 단일 객체입니다. 최적화해야 하는 문제의 전체 청사진이라고 생각하면 됩니다. |
timeout |
기간 | 이 매개변수는 서버가 응답을 반환하기 전에 요청을 처리하는 최대 시간을 지정합니다. 이 매개변수를 사용하여 대기 시간을 단축합니다. 이 반려견 유치원 시나리오와 같이 작고 빠른 요청의 경우 이 값을 2초로 설정합니다. | |
ShipmentModel |
shipments[] |
객체 배열 (Shipment) |
각 객체가 데리러 가거나 데려다주어야 하는 반려견을 나타내는 객체 배열입니다. |
vehicles[] |
객체 배열 (Vehicle) |
이는 각 객체가 차량의 차량을 정의하는 객체의 배열입니다. 여기에서 승차 및 하차를 수행하는 밴과 같은 리소스를 설명합니다. 최적화된 경로를 가져오려면 차량을 하나 이상 정의해야 합니다. | |
globalStartTime |
타임스탬프 | 전체 모델에서 이벤트가 발생할 수 있는 가장 이른 시간입니다. 이 매개변수는 최적화 문제를 시간 단위로 좁히므로 정확한 트래픽 및 경로 계산에 매우 중요합니다. 이 반려견 유치원 시나리오에서는 운전자가 하루 동안 밴을 운행할 수 있는 가장 이른 시간인 2024년 2월 13일 오전 7시로 설정합니다. | |
globalEndTime |
타임스탬프 | 전체 모델에서 이벤트가 발생할 수 있는 가장 늦은 시간입니다. 이 반려견 유치원 시나리오에서는 밴이 운행을 종료할 것으로 예상되는 시간인 2024년 2월 13일 오후 7시로 설정합니다. | |
Shipment |
pickups[] |
객체 배열 (VisitRequest) |
배송에 사용할 수 있는 모든 수령 옵션의 목록입니다. 최적화 도구는 문제를 해결하는 데 가장 적합한 것을 선택합니다. 이 반려견 유치원 시나리오의 경우 각 소유자가 각 반려견에 대해 제공한 픽업 위치와 시간대를 나열합니다. |
deliveries[] |
객체 배열 (VisitRequest) |
배송에 사용할 수 있는 모든 하차 옵션의 목록입니다. 최적화 도구는 문제를 해결하는 데 가장 적합한 것을 선택합니다. 이 반려견 유치원 시나리오에서는 반려견 유치원 시설의 위치와 운전자가 각 반려견의 점심 식사를 위해 돌아와야 하는 시간대를 나열합니다. | |
label |
문자열 | 요청의 특정 배송에 대한 식별자입니다. 요청에 라벨을 지정하여 응답을 더 쉽게 읽을 수 있습니다. 이 반려견 유치원 시나리오에서는 API 응답을 받을 때 입력과 일치하는 솔루션을 찾을 수 있도록 '치와와', '버니즈 마운틴 도그' 또는 반려견 이름과 같은 설명 문자열을 사용합니다. | |
penaltyCost |
double | 최적화 도구가 이 배송을 건너뛰는 경우 발생하는 페널티 비용입니다. 기본적으로 배송은 필수입니다. 최적화 도구는 건너뛴 필수 배송을 최소화하는 데 우선순위를 두고 다른 옵션이 없는 경우에만 건너뜁니다. 페널티 비용을 설정하면 최적화 도구에서 배송을 수행할 수 없거나 비용이 너무 많이 드는 경우 배송을 건너뛰고 배송 간의 우선순위를 가중할 수 있습니다. 이 시나리오에서는 일반 고객 (버니즈 마운틴 도그 및 치와와)에게 더 높은 페널티 비용 (1000)을 설정하고 마지막 저먼 셰퍼드 요청에 더 낮은 페널티 비용 (100)을 설정합니다. 이렇게 하면 최적화 도구에 일반 고객을 우선시하도록 지시하므로 모든 픽업을 수행할 수 없는 경우 저먼 셰퍼드를 먼저 건너뛰는 것을 고려합니다. |
|
VisitRequest |
arrivalWaypoint |
객체 (Waypoint) |
경로에서 특정 방문의 위치입니다. 위도 및 경도 좌표, 장소 ID 또는 방향을 사용하여 정의할 수 있습니다. 이 반려견 유치원 시나리오에서는 pickups의 경우 소유자가 제공한 위치로, deliveries의 경우 유치원 주소로 설정합니다. |
timeWindows[] |
객체 배열 (TimeWindow) |
수령 또는 배송의 시간 제약 조건을 정의하는 객체의 배열입니다. 이 시나리오에서는 이를 사용하여 각 반려견의 픽업 기간과 반려견을 데이케어 센터에 맡길 수 있는 기간을 정의합니다. | |
duration |
기간 | 이 매개변수는 방문 기간 (예: 적재 또는 하역 시간)을 지정합니다. 이 시나리오에서는 운전자가 반려견을 태우고 내리는 시간을 고려하여 모든 수령 및 배송에 5분의 버퍼 (300s)를 설정합니다. |
|
Vehicle |
startWaypoint |
객체 (Waypoint) |
위도 및 경도 좌표 또는 장소 ID로 정의된 차량 경로의 시작 위치입니다. 이 파라미터는 차량이 경로를 시작해야 하는 위치를 최적화 도구에 알려줍니다. 이 경유지를 정의하지 않으면 최적화 도구는 수령 또는 배송 중 하나를 시작 위치로 선택합니다. 이 반려견 유치원 시나리오에서는 운전자가 유치원 시설에서 하루를 시작하므로 Mission Dolores Park의 좌표를 사용합니다. |
endWaypoint |
객체 (Waypoint) |
차량 경로의 최종 목적지로, 위도 및 경도 좌표 또는 장소 ID로 정의됩니다. 이 파라미터는 최적화 도구에 차량이 경로를 종료해야 하는 위치를 알려줍니다. 이 경유지를 정의하지 않으면 최적화 도구는 수령 또는 배송 중 하나를 경로의 끝으로 선택합니다. 이 반려견 유치원 시나리오에서는 운전자가 유치원 시설에서 하루를 마쳐야 하므로 Mission Dolores Park의 좌표를 사용합니다. | |
costPerHour |
숫자 | 차량이 이동 중이든 정지 중이든 관계없이 차량이 사용되는 시간당 발생하는 비용입니다. 이 반려견 유치원 시나리오에서는 이를 사용하여 운전자의 시간당 임금을 모델링합니다. | |
startTimeWindows[] |
객체 배열 (TimeWindow) |
기사가 교대 근무를 시작할 수 있는 허용 가능한 시간대입니다. 이 반려견 유치원 시나리오에서는 startTime를 오전 7시로 정의하되 endTime는 생략합니다. 이렇게 하면 첫 번째 수거가 아침 늦게 이루어지는 경우 최적화 도구가 교대 근무 시작을 지연시킬 수 있습니다. startTimeWindows에 endTime를 제공하지 않더라도 시작 시간은 endTimeWindows에 의해 암시적으로 제한됩니다. 차량은 경로가 끝나기 전에 경로를 시작해야 합니다. |
|
endTimeWindows[] |
객체 배열 (TimeWindow) |
운전자가 경로를 완료할 수 있는 허용 가능한 시간대입니다.
이 반려견 유치원 시나리오에서는 endTime를 정오로 정의하되 startTime는 생략합니다. 이렇게 하면 운전자가 마지막 하차 후 즉시 어린이집으로 돌아갈 수 있습니다. |