Как выбрать поля для возврата

Введение

При вызове методов Place Details (New), Nearby Search (New) или Text Search (New) необходимо указать, какие поля должны быть возвращены в ответе. Список возвращаемых полей по умолчанию отсутствует. Если вы не укажете этот список, методы вернут ошибку.

Полный список поддерживаемых полей данных и соответствующих им кодов можно найти в разделе Поля данных о местах (новые). Информацию о полях, относящихся к каждому API, можно найти в следующих статьях:

• Параметры FieldMask в информации о местах (New)
• Параметры FieldMask в новом Nearby Search
• Параметры FieldMask в новой версии текстового поиска

Чтобы указать список полей, создайте маску полей ответа. Затем вы передаете маску поля ответа любому из методов, используя параметр $fields или fields или заголовок HTTP или gRPC X-Goog-FieldMask.

Маски полей помогут вам не запрашивать ненужные данные и тем самым сократить время обработки и снизить расходы.

Как определить маску поля ответа

Маска поля ответа – это список путей, разделенных запятыми, где каждый путь указывает на уникальное поле в теле ответа. Путь начинается с сообщения ответа верхнего уровня и использует путь к указанному полю, разделенный точками.

Путь к полю создается следующим образом:

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

Чтобы запросить все поля, используйте маску *.

Дополнительную информацию о создании масок полей можно найти в файле field_mask.proto.

Как определить, какие маски полей использовать

Вот как определить, какие маски полей вам нужны:

1. Запросите все поля, используя маску *.
2. Посмотрите на иерархию полей в ответе и определите, какие поля вам нужны.
3. Создайте маску поля, используя иерархию полей.

Как определить маску поля ответа для новых версий поиска поблизости и текстового поиска

Новые функции поиска поблизости (New) и текстового поиска (New) возвращают массив объектов Place в поле places ответа. Для этих API places – это поле верхнего уровня в ответе.

Например, чтобы увидеть полный объект ответа от нового текстового поиска, выполните следующее:

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'

Полный объект ответа на вызов текстового поиска (New) имеет следующий вид:

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

Поэтому для этих API вы указываете маску поля в форме:

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

Если вы хотите получить только поля formattedAddress и displayName, задайте следующую маску:

places.formattedAddress,places.displayName

Если указать displayName, будут включены поля text и language объекта displayName. Если вам нужно только поле text, задайте маску поля следующим образом:

places.formattedAddress,places.displayName.text

Как определить маску полей ответа для информации о местах (New)

Информация о местах (New) возвращает один объект Place в следующем формате:

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

Поэтому вы указываете маску поля для этого API, указывая поля объекта Place, которые вы хотите вернуть:

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

Вызов gRPC

Для gRPC задайте переменную, содержащую маску поля ответа. Затем вы можете передать эту переменную в запрос.

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

Примечания о путях к полям

Включайте в ответ только нужные поля. Возвращая только те поля, которые вам нужны:

• Сокращает время обработки, поэтому результаты возвращаются с меньшей задержкой.
• Обеспечивает стабильную задержку, если в будущем в API будут добавлены новые поля ответа, требующие дополнительного времени на вычисления. Если вы выберете все поля или все поля верхнего уровня, то можете столкнуться со снижением производительности, когда все новые поля будут автоматически включены в ответ.
• Уменьшает размер ответа, что повышает пропускную способность сети.
• Вы не запрашиваете ненужные данные, что позволяет сократить время обработки и снизить расходы.