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

Введение

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

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

• Параметры FieldMask для запроса информации о месте (новая версия)
• Параметры FieldMask для поиска поблизости (Новое)
• Параметры 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)

Запрос информации о местах (новый) возвращает один объект 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 будут добавлены новые поля ответа, для обработки которых потребуется дополнительное время. Если вы выберете все поля или все поля на верхнем уровне, то можете столкнуться со снижением производительности, когда все новые поля будут автоматически включены в ответ.
• Уменьшает размер ответа, что повышает пропускную способность сети.
• Позволяет не запрашивать ненужные данные, что помогает сократить время обработки и снизить расходы.