Place Details (New), Nearby Search (New) 또는 Text Search (New) 메서드를 호출할 때 응답에서 반환할 필드를 지정해야 합니다. 반환된 필드의 기본 목록은 없습니다. 이 목록을 생략하면 메서드가 오류를 반환합니다.
사용자는 응답 필드 마스크를 만들어 필드 목록을 지정합니다. 그런 다음 매개변수 $fields
또는 fields
를 사용하거나 HTTP 또는 gRPC 헤더 X-Goog-FieldMask
를 사용하여 응답 필드 마스크를 두 메서드에 전달합니다.
필드 마스킹은 불필요한 데이터를 요청하지 않도록 하는 좋은 설계 방법이며, 이렇게 하면 불필요한 처리에 드는 시간과 요금을 막을 수 있습니다.
응답 필드 마스크 정의
응답 필드 마스크는 쉼표로 구분된 경로 목록이며, 각 경로는 응답 메시지에서 고유한 필드를 지정합니다. 경로는 최상위 응답 메시지에서 시작되며 지정된 필드에 대한 점으로 구분된 경로를 사용합니다.
다음과 같이 필드 경로를 구성합니다.
topLevelField[.secondLevelField][.thirdLevelField][...]
*
필드 마스크를 사용하여 모든 필드를 요청할 수 있습니다.
필드 마스크를 구성하는 방법에 대한 자세한 내용은 field_mask.proto를 참조하세요.
사용할 필드 마스크 결정
사용할 필드 마스크를 결정하는 방법은 다음과 같습니다.
- `*` 필드 마스크를 사용하여 모든 필드를 요청합니다.
- 응답의 필드 계층 구조를 확인하고 원하는 필드를 결정합니다.
- 필드 계층 구조를 사용하여 필드 마스크를 빌드합니다.
주변 검색 (신규) 및 텍스트 검색 (신규)에 대한 응답 필드 마스크 정의
Nearby Search (New) 및 Text Search (New)는 응답의 places
필드에 장소 객체의 배열을 반환합니다. 이러한 API의 경우 places
는 응답의 최상위 필드입니다.
예를 들어 텍스트 검색 (신규)의 전체 응답 객체를 보려면 다음을 입력하세요.
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: *' \ 'https://places.googleapis.com/v1/places:searchText'
텍스트 검색 (신규) 호출의 전체 응답 객체는 다음과 같은 형식입니다.
{ "places": [ { "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0", "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0", "types": [ "vegetarian_restaurant", "vegan_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "nationalPhoneNumber": "0433 479 794", "internationalPhoneNumber": "+61 433 479 794", "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Spiced @ Barangaroo", "languageCode": "en" }, ... }, ... ] }
따라서 이러한 API에 대한 필드 마스크를 다음 형식으로 지정합니다.
places[.secondLevelField][.thirdLevelField][...]
formattedAddress
및 displayName
필드만 반환하려면 필드 마스크를 다음과 같이 설정합니다.
places.formattedAddress,places.displayName
displayName
를 지정하면 displayName
의 text
및 language
필드가 모두 포함됩니다. text
필드만 사용하려면 필드 마스크를 다음과 같이 설정합니다.
places.formattedAddress,places.displayName.text
장소 세부정보의 응답 필드 마스크 정의 (신규)
장소 세부정보는 다음과 같은 형식으로 단일 장소 객체를 반환합니다.
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "types": [ "locality", "political" ], "formattedAddress": "Trinidad, CA 95570, USA", "displayName": { "text": "Trinidad", "languageCode": "en" } ... }
따라서 반환할 Place 객체의 필드를 지정하여 이 API의 필드 마스크를 지정합니다.
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: formattedAddress,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
gRPC 호출
gRPC의 경우 응답 필드 마스크가 포함된 변수를 설정합니다. 그런 다음 이 변수를 요청에 전달할 수 있습니다.
const ( fieldMask = "places.formattedAddress,places.displayName" )
필드 경로 고려사항
응답에 필요한 필드만 포함합니다. 필요한 필드만 반환:
- 처리 시간이 단축되어 결과가 더 짧은 지연 시간으로 반환됩니다.
- 안정적인 지연 시간 성능이 보장됩니다(향후 API에서 응답 필드를 더 추가하고 이러한 새 필드에 계산 시간이 추가로 필요한 경우). 모든 필드를 선택하거나 최상위 수준의 모든 필드를 선택하면 모든 새 필드가 자동으로 응답에 포함될 때 성능이 저하될 수 있습니다.
- 응답 크기가 작아서 네트워크 처리량이 높아집니다.
- 불필요한 데이터를 요청하지 않습니다. 불필요한 처리 시간과 요금 청구를 방지하는 데 도움이 됩니다.