반환할 정보 선택

경로를 계산하거나 경로 매트릭스를 계산하는 메서드를 호출할 때는 응답에서 반환할 필드를 지정하여 원하는 정보를 지정해야 합니다. 반환되는 필드의 기본 목록은 없습니다. 이 목록을 생략하면 메서드가 오류를 반환합니다.

사용자는 응답 필드 마스크를 만들어 필드 목록을 지정합니다. 그런 다음 URL 매개변수 $fields 또는 fields를 사용하거나 HTTP 또는 gRPC 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 두 메서드에 전달합니다.

필드 마스킹은 불필요한 데이터를 요청하지 않도록 하는 좋은 설계 방법이며, 이렇게 하면 불필요한 처리 시간과 청구 요금이 발생하는 것을 피할 수 있습니다.

URL 매개변수에 관한 자세한 내용은 시스템 매개변수를 참고하세요.

응답 필드 마스크 정의

응답 필드 마스크는 쉼표로 구분된 경로 목록이며, 각 경로는 응답 메시지에서 고유한 필드를 지정합니다. 경로는 최상위 응답 메시지에서 시작되며 지정된 필드에 대한 점으로 구분된 경로를 사용합니다.

다음과 같이 필드 경로를 구성합니다.

topLevelField[.secondLevelField][.thirdLevelField][...]
  • 경로 필드 마스크 계산
    • REST: 반환할 응답에서 Route 객체의 필드를 지정합니다. 프리픽스로 routes.를 붙입니다(예: routes.distanceMeters).
    • gRPC: 반환할 응답에서 Route 객체의 필드를 지정합니다.
  • 경로 행렬 필드 마스크 계산

필드 마스크를 구성하는 방법에 대한 자세한 내용은 field_mask.proto를 참조하세요.

사용할 필드 마스크 결정

사용할 필드 마스크를 결정하는 방법은 다음과 같습니다.

  1. * 필드 마스크를 사용하여 모든 필드를 요청합니다.
  2. 응답의 필드 계층 구조를 확인하고 원하는 필드를 결정합니다.
  3. 필드 계층 구조를 사용하여 필드 마스크를 빌드합니다.

예를 들어 대중교통 경로의 부분 응답은 다음과 같습니다.

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

distanceMeters 필드만 반환하려는 경우 필드 마스크는 다음과 같습니다.

routes.legs.distanceMeters

또 다른 예: 응답에서 legs 아래에 있는 모든 항목을 반환하기 위한 필드 마스크는 다음과 같습니다.

routes.legs

필드 경로 지정

이 섹션에는 응답 필드 마스크의 일부로 필드 경로를 지정하는 방법에 대한 예시가 포함되어 있습니다.

computeRoutes에 대한 REST 호출

첫 번째 예시에서는 computeRoutes 메서드에 대한 REST 호출을 사용하여 경로를 계산합니다. 이 예시에서는 헤더에서 필드 마스크를 지정하여 응답에서 Route.distanceMetersRoute.duration 필드를 반환합니다. 필드 이름 앞에 routes를 붙여야 합니다.

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

computeRouteMatrix에 대한 REST 호출

경로 매트릭스를 계산하는 데 사용되는 REST computeRouteMatrix 메서드의 경우 헤더에서 출발지와 목적지의 조합마다 originIndex, destinationIndex, duration를 반환하도록 지정합니다.

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC 호출

gRPC의 경우 응답 필드 마스크가 포함된 변수를 설정합니다. 그런 다음 이 변수를 요청에 전달할 수 있습니다.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

필드 경로 고려사항

응답에 필요한 필드만 포함합니다. 필요한 필드만 반환:

  • 처리 시간이 단축되어 결과가 더 짧은 지연 시간으로 반환됩니다.
  • 안정적인 지연 시간 성능이 보장됩니다(향후 API에서 응답 필드를 더 추가하고 이러한 새 필드에 계산 시간이 추가로 필요한 경우). 모든 필드를 선택하거나 최상위 수준의 모든 필드를 선택하면 모든 새 필드가 자동으로 응답에 포함될 때 성능이 저하될 수 있습니다.
  • 응답 크기가 작아서 네트워크 처리량이 높아집니다.
  • 불필요한 데이터를 요청하지 않습니다. 불필요한 처리 시간과 요금 청구를 방지하는 데 도움이 됩니다.

경로 토큰 요청

Routes API가 생성된 경로의 경로 토큰을 반환하도록 요청하려면 경로 토큰 반환 요구사항을 따른 후 routes.route_token 필드 마스크를 사용하여 토큰을 요청합니다.

  1. travel_modeDRIVING로 설정합니다.
  2. routing_preferenceTRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL으로 설정합니다.
  3. 경로 경유지가 via 경유지가 아닌지 확인하세요.
  4. 경로 토큰 필드 마스크를 지정합니다.
    -H X-Goog-FieldMask: routes.route_token

Navigation SDK에서 계획된 경로를 사용할 수 있습니다. 자세한 내용은 경로 계획하기 (Android) 또는 경로 계획하기 (iOS)를 참조하세요.

경로 토큰 예시

다음은 필드 마스크를 사용하여 경로 토큰을 요청하는 단일 출발지 단일 목적지 경로의 cURL 요청 본문과 경로 소요 시간, 거리, 경로 다중선의 예입니다.

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

자세한 내용은 Compute Routes API 참조를 확인하세요.