장소 세부정보(신규), 주변 검색(신규) 또는 텍스트 검색(신규) 메서드를 호출할 때는 응답에 반환할 필드를 지정해야 합니다. 반환되는 필드의 기본 목록은 없습니다. 이 목록을 생략하면 메서드에서 오류를 반환합니다.
지원되는 데이터 필드 및 해당 SKU의 전체 목록은 장소 데이터 필드(신규)를 참고하세요. 각 API에 관한 필드에 관한 자세한 내용은 다음을 참고하세요.
응답 필드 마스크를 만들어 필드 목록을 지정합니다. 그런 다음 매개변수 $fields 또는 fields를 사용하거나 HTTP 또는 gRPC 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 메서드에 전달합니다.
필드 마스크는 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있는 좋은 설계 방법입니다.
응답 필드 마스크 정의
응답 필드 마스크는 쉼표로 구분된 경로 목록으로, 각 경로는 응답 본문의 고유한 필드를 지정합니다. 경로는 최상위 응답 메시지에서 시작하며 지정된 필드까지 점으로 구분된 경로를 사용합니다.
다음과 같이 필드 경로를 구성합니다.
topLevelField[.secondLevelField][.thirdLevelField][...]
필드 마스크 *를 사용하여 모든 필드를 요청할 수 있습니다.
필드 마스크를 구성하는 방법에 관한 자세한 내용은 field_mask.proto를 참고하세요.
사용할 필드 마스크 결정
다음은 사용할 필드 마스크를 결정하는 방법입니다.
- 필드 마스크
*를 사용하여 모든 필드를 요청합니다. - 응답에서 필드의 계층 구조를 살펴보고 원하는 필드를 결정합니다.
- 필드 계층 구조를 사용하여 필드 마스크를 빌드합니다.
주변 지역 검색 (신규) 및 텍스트 검색 (신규)의 응답 필드 마스크 정의
Nearby Search (신규) 및 Text Search (신규)는 응답의 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
장소 세부정보 (신규)의 응답 필드 마스크 정의
Place Details는 다음과 같은 형식으로 단일 장소 객체를 반환합니다.
{
"name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
"id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
"types": [
"locality",
"political"
],
"formattedAddress": "Trinidad, CA 95570, USA",
"displayName": {
"text": "Trinidad",
"languageCode": "en"
}
...
}
따라서 반환하려는 장소 객체의 필드를 지정하여 이 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에 응답 필드가 추가되고 이러한 새 필드에 추가 계산 시간이 필요한 경우 안정적인 지연 시간 성능을 보장합니다. 모든 필드를 선택하거나 최상위 수준에서 모든 필드를 선택하면 모든 새 필드가 응답에 자동으로 포함될 때 성능이 저하될 수 있습니다.
- 응답 크기가 작아져 네트워크 처리량이 증가합니다.
- 불필요한 데이터를 요청하지 않도록 합니다. 이렇게 하면 불필요한 처리 시간과 요금이 청구되지 않습니다.