반환할 필드 선택

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

소개

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

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

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

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

필드 마스크를 사용하면 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있습니다.

응답 필드 마스크 정의

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

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

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

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

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

사용할 필드 마스크 결정

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

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

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

주변 검색 (신규) 및 텍스트 검색 (신규)은 응답의 places 필드에 Place 객체의 배열을 반환합니다. 이러한 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 객체를 반환합니다.

{
  "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에서 향후 더 많은 응답 필드를 추가하고 이러한 새 필드에 추가 계산 시간이 필요한 경우 안정적인 지연 시간 성능을 보장 합니다. 모든 필드를 선택하거나 최상위 수준에서 모든 필드를 선택하면 모든 새 필드가 응답에 자동으로 포함될 때 성능 저하가 발생할 수 있습니다.
  • 응답 크기가 작아지므로 네트워크 처리량이 높아집니다.
  • 불필요한 데이터를 요청하지 않도록 보장하므로 불필요한 처리 시간과 청구된 요금을 방지할 수 있습니다.