이 페이지는 Cloud Translation API를 통해 번역되었습니다.

선택한 경로 만들기

이 페이지에서는 다음 섹션에서 Roads Selection API를 사용하여 경로를 만들고 맞춤 속성을 추가하는 방법을 설명합니다.

경로 만들기: create 엔드포인트를 사용하여 단일 경로를 정의합니다.
경로 일괄 생성: batchCreate 엔드포인트를 사용하여 단일 요청에서 여러 경로를 정의합니다.
중간 경유지를 사용하여 경로 만들기: 최대 25개의 중간 경유지를 사용하여 경로를 정의합니다.
맞춤 경로 속성 활용: 조직 관리를 위해 경로에 최대 10개의 맞춤 키-값 쌍을 추가합니다.

경로 만들기

경로를 만들려면 create 엔드포인트에 POST 요청을 전송합니다.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

요청 본문은 SelectedRoute 리소스를 정의하는 JSON 객체여야 합니다. 이 객체는 다음 정보를 지정합니다.

다음 정보가 포함된 dynamicRoute 객체:
- 선택한 경로의 origin입니다.
- 선택한 경로의 destination입니다.
- 경로의 intermediates(경유지라고도 함)입니다.
고유한 selectedRouteId 이 값은 4~63자(영문 기준)여야 하며 영숫자 문자만 사용해야 합니다. ID를 제공하지 않으면 시스템에서 선택한 경로의 고유 ID를 생성합니다.

다음 코드 샘플은 create 엔드포인트에 대한 POST 요청의 구조를 보여줍니다.

curl -X POST -d '
    {"dynamic_route": { \
      origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, \
      destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE} \
    }}' \' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

성공하면 API가 SelectedRoute 리소스를 반환합니다. 응답에는 name 필드에 selectedRouteId이 포함됩니다. 이 selectedRouteId를 사용하여 SelectedRoute 리소스를 검색하거나 삭제할 수 있습니다.

다음 코드 샘플은 성공적인 create 엔드포인트 응답의 구조를 보여줍니다.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING"
}

경로 일괄 생성

단일 요청에서 여러 경로를 만들려면 batchCreate 엔드포인트를 사용하세요. 이 엔드포인트를 사용하면 한 번의 호출로 최대 1,000개의 경로를 정의할 수 있습니다.

batchCreate 엔드포인트에 POST 요청을 전송합니다.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

URL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문은 requests 배열이 포함된 JSON 객체여야 합니다. 이 배열 내의 각 객체는 개별 SelectedRoute 리소스를 정의하는 CreateSelectedRouteRequest입니다.

다음 코드 샘플은 batchCreate 엔드포인트에 대한 POST 요청의 구조를 보여줍니다.

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_2, "longitude": ORIGIN_LONGITUDE_2},
          "destination": {"latitude": DESTINATION_LATITUDE_2, "longitude": DESTINATION_LONGITUDE_2}
        },
        "selectedRouteId": "route-two"
      }
    ]}
  ' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate"

성공하면 API는 생성된 SelectedRoute 리소스의 배열이 포함된 응답을 반환합니다.

다음 코드 샘플은 batchCreate 엔드포인트 응답의 구조를 보여줍니다.

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

중간 경유지가 있는 경로 만들기

출발지와 목적지 사이의 특정 지점을 통과하는 경로를 만들려면 요청 본문의 dynamicRoute 객체 내에 intermediates 배열을 포함합니다. intermediates 배열의 각 요소는 latitude 및 longitude로 정의된 경유지이며, 경로에는 최대 25개의 경유지가 있을 수 있습니다.

다음 코드 샘플은 중간 경유지를 사용하여 SelectedRoute를 만드는 방법을 보여줍니다.

curl -X POST -d '
    {"dynamic_route": { \
        "origin": {"latitude": ORIGIN_LATITUDE , "longitude": ORIGIN_LONGITUDE}, \
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {"latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE}}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

맞춤 경로 속성 활용

Roads Management Insights에서 경로 관리 및 데이터 분석을 개선하기 위해 SelectedRoute 객체에는 route_attributes 필드가 포함됩니다.

routeAttributes 필드를 사용하여 개별 경로에 대한 맞춤 속성을 정의합니다. 각 속성은 키-값 쌍입니다. 경로당 최대 10개의 맞춤 키-값 쌍을 제공할 수 있습니다.

이러한 속성은 특정 경로를 식별하거나 필요에 맞는 기준에 따라 경로를 그룹화하는 데 유용합니다.

다음은 사용할 수 있는 경로 속성의 몇 가지 예입니다.

"road_classification": "highway"
"maintenance_zone": "north_district"
"event_id": "marathon_2024"
"pavement_type": "asphalt"

routeAttributes 필드를 정의할 때는 다음 가이드라인을 따르세요.

키는 goog 접두사로 시작할 수 없습니다.
각 키와 각 값의 길이는 100자를 초과할 수 없습니다.

그런 다음 다음과 같은 방법으로 도로 관리 통계 내에서 이러한 맞춤 routeAttributes를 사용할 수 있습니다.

Pub/Sub 알림 필터링: Pub/Sub 구독에 필터를 설정하여 특정 속성 키 및 해당 값과 일치하거나 일치하지 않는 경로에 대한 업데이트만 수신할 수 있습니다.
BigQuery 분석 개선: BigQuery 테이블에서 이러한 속성을 사용하여 속성 값을 기반으로 특정 경로를 필터링할 수 있습니다. 특정 속성 키로 경로를 그룹화하여 더 타겟팅된 데이터 분석을 실행할 수도 있습니다.

다음 코드 샘플은 맞춤 routeAttributes을 사용하여 SelectedRoute를 만드는 방법을 보여줍니다.

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"ATTRIBUTE_KEY":"ATTRIBUTE_VALUE"}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"