Wybierz pola do zwrócenia

Gdy wysyłasz żądanie geokodowania, możesz użyć maski pola, aby określić listę pól, które mają zostać zwrócone w odpowiedzi. Maski pól pomagają zmniejszyć opóźnienie odpowiedzi, ponieważ dzięki nim nie musisz wysyłać żądań niepotrzebnych danych.

W przypadku metod Geocode an address, Geocode a location i Place geocoding domyślnie zwracane są wszystkie pola w obiekcie odpowiedzi. Maska pola nie jest wymagana, ale zdecydowanie zalecamy jej używanie, aby zmniejszyć opóźnienie odpowiedzi.

Definiowanie maski pola odpowiedzi

Maska pola odpowiedzi to lista ścieżek rozdzielona przecinkami bez spacji, gdzie każda ścieżka określa unikalne pole w obiekcie odpowiedzi. Ścieżka zaczyna się od pola odpowiedzi najwyższego poziomu i używa ścieżki rozdzielonej kropkami do określonego pola.

Przekaż maskę pola odpowiedzi do żądania za pomocą parametru URL $fields lub fields albo za pomocą nagłówka HTTP lub gRPC X-Goog-FieldMask.

Przykładowe maski pól

Poniżej znajdziesz pełną odpowiedź na żądanie geokodowania do przodu:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    ...
}

Maski pól twórz, korzystając z hierarchii pól odpowiedzi w formacie:

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

Jeśli na przykład chcesz zwrócić w odpowiedzi tylko pole placeId, użyj maski pola:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA

Odpowiedź brzmi teraz:

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE"
    }
  ]
}

Aby zwrócić pole viewport, Twoja maska pola to:

-H 'X-Goog-FieldMask: results.viewport'

Odpowiedź brzmi teraz:

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

Aby zwrócić oba produkty:

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

Odpowiedź brzmi teraz:

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

Maski pól gRPC

W przypadku gRPC ustaw zmienną zawierającą maskę pola odpowiedzi. Następnie możesz przekazać tę zmienną do żądania.

const (
  fieldMask = "results.placeId,results.viewport"
)

Uwagi dotyczące ścieżki pola

W odpowiedzi uwzględnij tylko te pola, które są Ci potrzebne:

• Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
• Zapewnia stabilną wydajność w zakresie opóźnień. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, po dodaniu nowych pól i automatycznym uwzględnieniu ich w odpowiedzi może nastąpić spadek wydajności.
• Zmniejsza rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.

Więcej informacji o tworzeniu maski pola znajdziesz w pliku field_mask.proto.