Gdy wywołujesz metody Szczegóły miejsca (nowa), Wyszukiwanie w pobliżu (nowa) lub Wyszukiwanie tekstowe (nowa), 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 odpowiednich kodów SKU znajdziesz w sekcji Pola danych o miejscach (nowa wersja). Informacje o polach konkretnych dla poszczególnych interfejsów API znajdziesz w tych artykułach:
- Szczegóły miejsca (nowe) – parametry FieldMask
- Wyszukiwanie w pobliżu (nowy format) – parametry FieldMask
- Parametry wyszukiwania tekstowego (nowego) FieldMask
Listę pól określasz, tworząc maskę pola odpowiedzi. Następnie przekazujesz maskę pola odpowiedzi do dowolnej metody 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 rozliczeniowych.
Definiowanie maski pola odpowiedzi
Maska pola odpowiedzi to lista ścieżek oddzielonych przecinkami, z których każda określa niepowtarzalne pole w ciele odpowiedzi. Ścieżka zaczyna się od wiadomości odpowiedzi na najwyższym poziomie i korzysta ze ścieżki oddzielonej kropkami do określonego pola.
Aby utworzyć ścieżkę pola:
topLevelField[.secondLevelField][.thirdLevelField][...]
Aby poprosić o wszystkie pola, użyj maski pola *.
Więcej informacji o tworzeniu masek pól znajdziesz w pliku field_mask.proto.
Wybieranie masek pól
Aby określić, których masek pól chcesz użyć:
- Żądaj wszystkich pól, używając maski pola
*. - Sprawdź hierarchię pól w odpowiedzi i określ, które z nich chcesz wykorzystać.
- Utwórz maskę pola, korzystając z hierarchii pól.
Definiowanie maski pola odpowiedzi w przypadku wyszukiwania w pobliżu (nowa wersja) i wyszukiwania tekstowego (nowa wersja)
Wyszukiwanie w pobliżu (nowy) i Wyszukiwanie tekstowe (nowy) zwracają tablicę obiektów Miejsce w polu places odpowiedzi. W przypadku tych interfejsów API places jest najwyższym poziomem pola odpowiedzi.
Aby na przykład zobaczyć pełny obiekt odpowiedzi z wyszukiwania tekstowego (nowa wersja):
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 metody tekstowej wyszukiwarki (nowej) 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 w przypadku tych interfejsów API musisz podać maskę pola w takim formacie:
places[.secondLevelField][.thirdLevelField][...]
Jeśli chcesz zwrócić tylko pola formattedAddress i displayName, ustaw maskę pola na:
places.formattedAddress,places.displayName
Podanie wartości displayName obejmuje pola text i language w displayName. Jeśli interesuje Cię tylko pole text, ustaw maskę pola:
places.formattedAddress,places.displayName.text
Definiowanie maski odpowiedzi dla szczegółów miejsca (nowa wersja)
Szczegóły miejsca zwracają pojedynczy obiekt Miejsce w formacie:
{
"name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
"id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
"types": [
"locality",
"political"
],
"formattedAddress": "Trinidad, CA 95570, USA",
"displayName": {
"text": "Trinidad",
"languageCode": "en"
}
...
}
Dlatego dla tego interfejsu API musisz określić maskę pól, podając pola obiektu Miejsce, 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 pola, których potrzebujesz. zwraca tylko te pola, których potrzebujesz:
- Krótszy czas przetwarzania, dzięki czemu wyniki są zwracane z mniejszym opóźnieniem.
- Zapewnia stabilną wydajność w zakresie opóźnień, jeśli interfejs API doda w przyszłości więcej pól odpowiedzi, a te nowe pola będą wymagać dodatkowego czasu na przetwarzanie. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, może to spowodować pogorszenie skuteczności, ponieważ wszystkie nowe pola zostaną automatycznie uwzględnione w odpowiedzi.
- Powoduje mniejszy rozmiar odpowiedzi, co przekłada się na większą przepustowość sieci.
- Upewnij się, że nie prosisz o niepotrzebne dane, co pomoże Ci uniknąć niepotrzebnego czasu przetwarzania i niepotrzebnych opłat.