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ć czas oczekiwania na odpowiedź, ponieważ dzięki nim nie prosisz o niepotrzebne dane.

W przypadku podstawowych metod geokodowania (Geokodowanie adresu, Geokodowanie lokalizacji i Geokodowanie miejsca) domyślnie zwracane są wszystkie pola w obiekcie odpowiedzi, w przeciwieństwie do metody Wyszukiwanie miejsc docelowych, w której wymagane jest określenie maski pola. Chociaż maska pola nie jest wymagana w przypadku podstawowych metod, zdecydowanie zalecamy jej używanie, aby zmniejszyć opóźnienie odpowiedzi.

Definiowanie maski pola odpowiedzi

Maska pola odpowiedzi to lista rozdzielona przecinkami ścieżek 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 rozdzielanej kropkami do określonego pola.

Przekaż maskę pola odpowiedzi do żądania, używając parametru adresu URL $fields lub fields albo nagłówka HTTP lub gRPC X-Goog-FieldMask.

Przykładowe maski pól

Poniżej znajduje się pełna odpowiedź na żądanie geokodowania bezpośredniego:

{
  "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 możesz tworzyć, korzystając z hierarchii pól odpowiedzi w tej postaci:

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

Maski pól miejsc docelowych wyszukiwania

Podczas wywoływania SearchDestinations podaj dokładne atrybuty miejsca docelowego, których potrzebujesz, takie jak informacje o miejscu, wejścia, punkty nawigacyjne, kontury budynków (displayPolygon) i punkty orientacyjne:

curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations

Maski pól podstawowego geokodowania

Aby na przykład w odpowiedzi GeocodeAddress zwrócić 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ź jest teraz taka:

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

Aby zwrócić pole viewport, maska pola powinna wyglądać tak:

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

Odpowiedź jest teraz taka:

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

Aby zwrócić oba urządzenia:

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

Odpowiedź jest teraz taka:

{
  "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

Uwzględnij tylko te pola, które są wymagane w odpowiedzi, aby zwrócić tylko te pola, których potrzebujesz:

• Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
• Zapewnia stabilne opóźnienie. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, może dojść do pogorszenia wydajności, gdy zostaną dodane nowe pola, które zostaną automatycznie uwzględnione w odpowiedzi.
• 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.