Выберите, какую информацию вернуть

Когда вы вызываете метод для вычисления маршрута или вычисления матрицы маршрутов, вы должны указать, какую информацию вы хотите, указав, какие поля вы хотите вернуть в ответе. Не существует списка возвращаемых полей по умолчанию. Если вы опустите этот список, методы вернут ошибку.

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

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

Дополнительную информацию о параметрах URL см. в разделе Системные параметры .

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

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

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

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Вычислить маску поля маршрута
    • REST: указывает поля объекта Route в ответе на возврат с префиксом routes. например, routes.distanceMeters .
    • gRPC: указывает поля объекта Route в возвращаемом ответе.
  • Вычисление масок полей матрицы маршрутов

Дополнительные сведения о том, как создавать маски полей, см. в файле field_mask.proto .

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

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

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

Например, для этого частичного ответа от транзитного маршрута:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

Если вы хотите вернуть только поле distanceMeters , маска поля будет следующей:

routes.legs.distanceMeters

Другой пример: чтобы вернуть в ответ все, что находится под legs , ваша маска поля:

routes.legs

Укажите путь к полю

В этом разделе приведены примеры указания пути к полю как части маски поля ответа.

REST-вызов computeRoutes

В первом примере вы используете вызов REST метода computeRoutes для расчета маршрута. В этом примере в заголовке вы указываете маски полей для возврата полей Route.distanceMeters и Route.duration в ответе. Не забудьте добавить к имени поля префикс routes .

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

REST-вызов computeRouteMatrix

Для метода REST computeRouteMatrix , используемого для вычисления матрицы маршрутов, в заголовке укажите возврат originIndex , destinationIndex и duration для каждой комбинации пункта отправления и назначения:

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

вызов gRPC

Для gRPC установите переменную, содержащую маску поля ответа. Затем вы можете передать эту переменную в запрос.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Рекомендации по траектории поля

Включите в ответ только те поля, которые вам необходимы. Возвращаем только те поля, которые вам нужны:

  • Уменьшает время обработки , поэтому результаты возвращаются с меньшей задержкой.
  • Обеспечивает стабильную задержку, если в будущем API добавит больше полей ответа, и эти новые поля потребуют дополнительного времени вычислений. Если вы выберете все поля или все поля на верхнем уровне, вы можете столкнуться с ухудшением производительности, когда все новые поля будут автоматически включены в ваш ответ.
  • Результатом является меньший размер ответа , что приводит к повышению пропускной способности сети.
  • Гарантирует, что вы не запрашиваете ненужные данные , что помогает избежать ненужного времени обработки и выставленных счетов.

Запросить токен маршрута

Чтобы запросить, чтобы API маршрутов возвращал токены маршрута для сгенерированных маршрутов, следуйте требованиям для возврата токена маршрута, а затем используйте маску поля routes.route_token для запроса токена:

  1. Установите для параметра travel_mode значение DRIVING .
  2. Установите routing_preference значение TRAFFIC_AWARE или TRAFFIC_AWARE_OPTIMAL .
  3. Убедитесь, что ни одна из путевых точек вашего маршрута не проходит via путевые точки.
  4. Укажите маску поля токена маршрута: 
    -H X-Goog-FieldMask: routes.route_token

Вы можете использовать запланированный маршрут в Navigation SDK. Дополнительные сведения см. в разделе «Планирование маршрута» (Android) или «Планирование маршрута» (iOS) .

Пример токена маршрута

Ниже приведен пример тела запроса для одного исходного и одного конечного маршрута и использования масок полей для запроса токена маршрута, а также длительности маршрута, расстояния и полилинии маршрута:

terminal
curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Дополнительные сведения см. в справочнике по API Compute Routes .