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

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

Примечание. Если при анализе ответного сообщения поле в ответном сообщении содержит значение по умолчанию, это поле может быть опущено в ответе, даже если вы указали его в маске поля ответа. Дополнительную информацию см. в Языковом руководстве (proto3) .