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

Разработчики Европейской экономической зоны (ЕЭЗ)

Введение

При вызове методов 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. Создайте маску поля, используя иерархию полей.

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

Функции «Поиск рядом» (новый) и «Текстовый поиск» (новый) возвращают массив объектов 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'

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

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