Wybierz pola do zwrócenia

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Gdy wysyłasz żądanie geokodowania, możesz użyć maski pola, aby określić listę pól, które mają być zwracane w odpowiedzi. W przypadku punktów końcowych Geocode an address, Geocode a location i Place geocoding domyślnie zwracane są wszystkie pola w obiekcie odpowiedzi. W przypadku punktu końcowego Search for destinations musisz określić maskę pola w żądaniu do interfejsu API.

Używaj maski pola, aby nie żądać niepotrzebnych danych, co z kolei pomaga zmniejszyć opóźnienie odpowiedzi.

Definiowanie maski pola odpowiedzi

Maska pola odpowiedzi to lista ścieżek rozdzielonych 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 adresu 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",
    ...
}

Utwórz maski pól, 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/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Odpowiedź brzmi teraz:

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

Aby zwrócić pole viewport, maska pola musi mieć postać:

-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.