반환할 필드 선택

장소 세부정보 (신규), 주변 검색 (신규) 또는 텍스트 검색 (신규) 메서드를 호출할 때는 응답에 반환할 필드를 지정해야 합니다. 반환되는 필드의 기본 목록은 없습니다. 이 목록을 생략하면 메서드에서 오류를 반환합니다.

지원되는 데이터 필드 및 해당 SKU의 전체 목록은 장소 데이터 필드(신규)에서 확인할 수 있습니다. 각 API에 관한 필드에 관한 자세한 내용은 다음을 참고하세요.

  • 장소 세부정보 (신규) FieldMask 매개변수
  • 주변 검색 (신규) FieldMask 매개변수
  • 텍스트 검색 (신규) FieldMask 매개변수

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

필드 마스크는 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있는 좋은 설계 방법입니다.

응답 필드 마스크 정의

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

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

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

필드 마스크 *를 사용하여 모든 필드를 요청할 수 있습니다.

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

사용할 필드 마스크 결정

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

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

주변 지역 검색 (신규) 및 텍스트 검색 (신규)의 응답 필드 마스크 정의

주변 지역 검색 (신규) 및 텍스트 검색 (신규)은 응답의 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에 응답 필드가 추가되고 이러한 새 필드에 추가 계산 시간이 필요한 경우 안정적인 지연 시간 성능을 보장합니다. 모든 필드를 선택하거나 최상위 수준에서 모든 필드를 선택하면 모든 새 필드가 응답에 자동으로 포함될 때 성능이 저하될 수 있습니다.
  • 응답 크기가 작아지므로 네트워크 처리량이 증가합니다.
  • 불필요한 데이터를 요청하지 않도록 합니다. 이렇게 하면 불필요한 처리 시간과 청구된 요금을 방지할 수 있습니다.