반환할 필드 선택

유럽 경제 지역 (EEA) 개발자

지오코딩 요청을 할 때 필드 마스크를 사용하여 응답에서 반환할 필드의 목록을 지정할 수 있습니다. 주소 지오코딩, 위치 지오코딩, 장소 지오코딩 메서드의 경우 응답 객체의 모든 필드가 기본적으로 반환됩니다. Search for destinations(여행 목적지 검색) 메서드의 경우 API 요청에 필드 마스크를 지정해야 합니다.

필드 마스크를 사용하여 불필요한 데이터의 요청을 방지하면 응답 지연 시간을 줄일 수 있습니다.

응답 필드 마스크 정의

응답 필드 마스크는 공백이 없는 쉼표로 구분된 경로 목록으로, 각 경로는 응답 객체의 고유한 필드를 지정합니다. 경로는 최상위 응답 필드에서 시작하며 점으로 구분된 경로를 사용하여 지정된 필드로 이동합니다.

URL 매개변수 $fields 또는 fields를 사용하거나 HTTP 또는 gRPC 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 요청에 전달합니다.

필드 마스크 예

아래는 순방향 지오코딩 요청의 전체 응답입니다.

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    ...
}

다음 형식으로 응답 필드의 계층 구조를 사용하여 필드 마스크를 구성합니다.

topLevelField[.secondLevelField][.thirdLevelField][...]

예를 들어 응답에서 placeId 필드만 반환하려면 다음 필드 마스크를 사용하세요.

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://"geocode.googleapis.com/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

이제 대답은 다음과 같습니다.

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE"
    }
  ]
}

viewport 필드를 반환하려면 필드 마스크는 다음과 같습니다.

-H 'X-Goog-FieldMask: results.viewport'

이제 대답은 다음과 같습니다.

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

두 항목을 모두 반품하려면 다음 단계를 따르세요.

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

이제 대답은 다음과 같습니다.

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

gRPC 필드 마스크

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

const (
  fieldMask = "results.placeId,results.viewport"
)

필드 경로 고려사항

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

  • 처리 시간을 줄여 결과가 더 낮은 지연 시간으로 반환됩니다.
  • 안정적인 지연 시간 성능을 보장합니다. 모든 필드를 선택하거나 최상위 수준에서 모든 필드를 선택하면 새 필드가 추가된 후 응답에 자동으로 포함될 때 성능이 저하될 수 있습니다.
  • 응답 크기가 작아지므로 네트워크 처리량이 높아집니다.

필드 마스크 구성에 관한 자세한 내용은 field_mask.proto를 참고하세요.