Wybierz pola do zwrócenia

Gdy wywołujesz metodę Szczegóły miejsca (nowe), Wyszukiwanie w pobliżu (nowość) lub Wyszukiwanie tekstowe (nowe), musisz określić, które pola mają być zwracane w odpowiedzi. Nie ma domyślnej listy zwróconych pól. Jeśli pominiesz tę listę, metody zwrócą błąd.

Listę pól określasz przez utworzenie maski pola odpowiedzi. Następnie przekazujesz maskę pola odpowiedzi do dowolnej metody za pomocą parametru $fields lub fields albo nagłówka HTTP lub gRPC X-Goog-FieldMask.

Maskowanie pól to sprawdzona metoda projektowania, dzięki której nie żądasz zbędnych danych. Pozwala to uniknąć zbędnego czasu przetwarzania i pobierania opłat.

Zdefiniuj maskę pola odpowiedzi

Maska pola odpowiedzi to rozdzielana przecinkami lista ścieżek, gdzie każda ścieżka określa unikalne pole w wiadomości odpowiedzi. Ścieżka zaczyna się od wiadomości z odpowiedzią najwyższego poziomu i używa oddzielonej kropkami ścieżki do określonego pola.

Utwórz ścieżkę pola w ten sposób:

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

Możesz zażądać wszystkich pól, używając maski pola *.

Więcej informacji o tworzeniu masek pól znajdziesz w field_mask.proto.

Określenie, których masek pól należy użyć

Oto jak możesz określić, których masek pól chcesz użyć:

1. Żądaj wszystkich pól, używając maski pola „*”.
2. Przeanalizuj hierarchię pól w odpowiedzi i określ, których z nich potrzebujesz.
3. Utwórz maskę pola, korzystając z hierarchii pól.

Definiowanie maski pola odpowiedzi na potrzeby wyszukiwania w pobliżu (nowość) i wyszukiwania tekstowego (nowego)

Funkcje Wyszukiwanie w pobliżu (nowość) i Wyszukiwanie tekstowe (nowe) zwracają tablicę obiektów Miejsc w polu places odpowiedzi. W przypadku tych interfejsów API places jest polem najwyższego poziomu odpowiedzi.

Aby na przykład wyświetlić pełny obiekt odpowiedzi z wyszukiwania tekstowego (nowość):

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'

Obiekt pełnej odpowiedzi z wywołania wyszukiwania tekstowego (nowego) ma postać:

{
  "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"
      },      ...
    },
  ...
  ]
}

W związku z tym określasz maskę pola dla tych interfejsów API w postaci:

places[.secondLevelField][.thirdLevelField][...]

Jeśli chcesz zwrócić tylko pola formattedAddress i displayName, ustaw maskę pola na:

places.formattedAddress,places.displayName

Określenie displayName uwzględnia zarówno pola text, jak i language właściwości displayName. Jeśli potrzebujesz tylko pola text, ustaw maskę pola na:

places.formattedAddress,places.displayName.text

Zdefiniuj maskę pola odpowiedzi dla szczegółów miejsca (nowość)

Szczegóły miejsca zwraca jeden obiekt Place w formularzu:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

Aby określić maskę pola dla tego interfejsu API, określ pola obiektu Place, które chcesz zwrócić:

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

Wywołanie gRPC

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

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

Uwagi na temat ścieżek pól

Uwzględnij w odpowiedzi tylko te pola, które potrzebujesz. Wyświetlając tylko te pola, których potrzebujesz:

• Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
• Zapewnia stabilne działanie opóźnienia, jeśli w przyszłości interfejs API będzie dodawać więcej pól odpowiedzi, a te nowe pola wymagają dodatkowego czasu na obliczenia. Jeśli wybierzesz wszystkie pola lub wybierzesz wszystkie pola na najwyższym poziomie, możesz zauważyć spadek wydajności, gdy wszystkie nowe pola będą automatycznie uwzględniane w odpowiedzi.
• Mniejszy rozmiar odpowiedzi przekłada się na większą przepustowość sieci.
• Zapewnia to, że nie żądasz zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i rozliczonych opłat.