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

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

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