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에서 응답 필드를 더 추가하고 이러한 새 필드에 계산 시간이 추가로 필요한 경우). 모든 필드를 선택하거나 최상위 수준의 모든 필드를 선택하면 모든 새 필드가 자동으로 응답에 포함될 때 성능이 저하될 수 있습니다.
- 응답 크기가 작아서 네트워크 처리량이 높아집니다.
- 불필요한 데이터를 요청하지 않습니다. 불필요한 처리 시간과 요금 청구를 방지하는 데 도움이 됩니다.