Wybierz pola do zwrócenia

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wprowadzenie

Gdy wywołujesz metody informacje o miejscu (New), Wyszukiwanie w pobliżu (New), lub Wyszukaj tekst (New) , musisz określić, które pola mają zostać zwrócone w odpowiedzi. Nie ma domyślnej listy zwracanych pól. Jeśli pominiesz tę listę, metody zwrócą błąd.

Pełną listę obsługiwanych pól danych i odpowiadających im kodów SKU znajdziesz w artykule Pola danych o miejscach (nowość). Informacje o polach specyficznych dla poszczególnych interfejsów API znajdziesz w tych artykułach:

  • Informacje o miejscu (nowe) FieldMask parametry
  • Wyszukiwanie w pobliżu (nowe) FieldMask parametry
  • Parametry FieldMask w Wyszukaj tekst (Nowe)

Listę pól określasz, tworząc maskę pola odpowiedzi. Następnie przekazujesz maskę pola odpowiedzi do jednej z metod za pomocą parametru $fields lub fields, albo za pomocą nagłówka HTTP lub gRPC X-Goog-FieldMask.

Maskowanie pól to dobra praktyka projektowania, która pozwala uniknąć żądania niepotrzebnych danych, co pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.

Definiowanie maski pola odpowiedzi

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

Ścieżkę pola utwórz 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ślanie masek pól do użycia

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

  1. Zażądaj wszystkich pól, używając maski pola *.
  2. Sprawdź hierarchię pól w odpowiedzi i określ, które pola chcesz uzyskać.
  3. Utwórz maskę pola na podstawie hierarchii pól.

Definiowanie maski pola odpowiedzi dla Wyszukiwania w pobliżu (New) i Wyszukiwania tekstowego (New)

Wyszukiwanie w pobliżu (New) i Wyszukaj tekst (New) zwracają tablicę obiektów Place w polu places odpowiedzi. W przypadku tych interfejsów API places jest polem najwyższego poziomu odpowiedzi.

Aby na przykład zobaczyć pełny obiekt odpowiedzi z Wyszukaj tekst (New):

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'

Pełny obiekt odpowiedzi z wywołania Wyszukaj tekst (New) 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"
      },      ...
    },
  ...
  ]
}

Dlatego maskę pola dla tych interfejsów API określasz w ten sposób:

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

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

places.formattedAddress,places.displayName

Określenie displayName obejmuje zarówno pola text, jak i language w displayName. Jeśli chcesz uzyskać tylko pole text, ustaw maskę pola w ten sposób:

places.formattedAddress,places.displayName.text

Definiowanie maski pola odpowiedzi dla informacji o miejscu (New)

Informacje o miejscu (Nowe) zwracają pojedynczy obiekt Place w postaci:

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

Dlatego maskę pola dla tego interfejsu API określasz, podając 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 dotyczące ścieżki pola

W odpowiedzi uwzględnij tylko te pola, których potrzebujesz. Zwracanie tylko tych pól, których potrzebujesz:

  • Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
  • Zapewnia stabilną wydajność opóźnienia , jeśli interfejs API doda w przyszłości więcej pól odpowiedzi, a te nowe pola będą wymagać dodatkowego czasu obliczeń. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, możesz zauważyć spadek wydajności, gdy wszystkie nowe pola zostaną automatycznie uwzględnione w odpowiedzi.
  • Zmniejsza rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.
  • Gwarantuje, że nie będziesz żądać niepotrzebnych danych, co pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.