Выберите поля для возврата

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

Полный список поддерживаемых полей данных и соответствующих им SKU можно найти в Place Data Fields (New) . Для получения информации о полях, специфичных для каждого API, см. следующее:

  • Сведения о месте (новые) Параметры FieldMask
  • Параметры FieldMask поиска поблизости (новые)
  • Параметры текстового поиска (новые) FieldMask

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

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

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

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

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

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

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

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

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

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

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

Определите маску поля ответа для поиска поблизости (новый) и текстового поиска (новый)

Nearby Search (New) и Text Search (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'

Полный объект ответа на вызов Text Search (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

Определите маску поля ответа для сведений о месте (новое)

Place Details (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 добавит больше полей ответа в будущем, и эти новые поля потребуют дополнительного времени вычислений. Если вы выберете все поля или все поля на верхнем уровне, вы можете столкнуться с падением производительности, когда все новые поля будут автоматически включены в ваш ответ.
  • В результате размер ответа уменьшается , что приводит к повышению пропускной способности сети.
  • Гарантирует, что вы не запрашиваете ненужные данные , что помогает избежать ненужного времени обработки и дополнительных расходов.