이 페이지는 Cloud Translation API를 통해 번역되었습니다.

반환할 필드 선택

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

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

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

응답 필드 마스크 정의

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

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

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

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

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

사용할 필드 마스크 결정

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

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

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

주변 지역 검색 (신규) 및 텍스트 검색 (신규)은 응답의 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'

Text Search (New) 호출의 전체 응답 객체는 다음 형식을 취합니다.

{
  "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는 단일 Place 객체를 다음 형식으로 반환합니다.

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