Wybierz pola do zwrócenia

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

Aby określić listę pól, utwórz maskę pola odpowiedzi. Następnie przekaż maskę pola odpowiedzi do wybranej metody za pomocą parametru $fields lub fields albo nagłówka HTTP lub gRPC X-Goog-FieldMask.

Maskowanie pól to dobra praktyka projektowa, która pozwala uniknąć żądania zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i opłat.

Zdefiniuj maskę pola odpowiedzi

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

Utwórz ścieżkę pola w następujący 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 na stronie field_mask.proto.

Określanie, których masek pól używać

Aby określić, których masek pól chcesz używać:

1. Żądaj wszystkich pól za pomocą maski pola „*”.
2. Przyjrzyj się hierarchii pól w odpowiedzi i ustal, których pól potrzebujesz.
3. Utwórz maskę pola, korzystając z hierarchii pól.

Zdefiniuj maskę pola odpowiedzi dla wyszukiwania w pobliżu (nowość) i wyszukiwania tekstowego (nowość)

Wyszukiwanie w pobliżu (nowość) i wyszukiwanie tekstowe (nowe) zwracają tablicę obiektów Place w polu places odpowiedzi. W przypadku tych interfejsów API pole najwyższego poziomu odpowiedzi to places.

Aby np. wyświetlić obiekt pełnej 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"
      },      ...
    },
  ...
  ]
}

Dlatego maskę pola dla tych interfejsów API określasz w formularzu:

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

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

places.formattedAddress,places.displayName

Określenie displayName obejmuje zarówno pole text, jak i language właściwości displayName. Jeśli potrzebujesz tylko pola text, ustaw maskę pola w ten sposób:

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

Dlatego maskę pola dla tego interfejsu API określasz, określają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 na temat ścieżki pola

Uwzględnij w odpowiedzi tylko pola, które są wymagane. Zwracając tylko te pola, które są potrzebne:

• Skraca czas przetwarzania, dzięki czemu wyniki są zwracane z krótszym czasem oczekiwania.
• Gwarantuje stabilne opóźnienia, jeśli interfejs API doda w przyszłości więcej pól odpowiedzi, co będzie wymagało dodatkowego czasu obliczania. Jeśli wybierzesz wszystkie pola lub wybierzesz wszystkie pola na najwyższym poziomie, może nastąpić spadek wydajności, gdy wszystkie nowe pola zostaną automatycznie uwzględnione w odpowiedzi.
• Mniejszy rozmiar odpowiedzi przekłada się na większą przepustowość sieci.
• Zapewnia brak żądań zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i naliczania opłat.