Выберите, какую информацию вернуть
Когда вы вызываете метод для вычисления маршрута или матрицы маршрутов, вы должны указать, какую информацию вы хотите, перечислив поля, которые будут возвращены в ответе. Не существует списка возвращаемых полей по умолчанию. Если вы опустите этот список, методы вернут ошибку.
Вы указываете список полей, создавая маску поля ответа . Затем вы передаете маску поля ответа любому методу, используя параметр URL-адреса $fields
или fields
или используя заголовок HTTP или gRPC X-Goog-FieldMask
.
Использование маски поля — это хорошая практика проектирования, позволяющая избежать запроса ненужных данных, что, в свою очередь, помогает избежать ненужного времени обработки и выставленных счетов.
Дополнительную информацию о параметрах URL см. в разделе Системные параметры .
Определить маску поля ответа
Маска поля ответа представляет собой список путей, разделенных запятыми, где каждый путь указывает уникальное поле в ответном сообщении. Путь начинается с ответного сообщения верхнего уровня и использует путь к указанному полю, разделенный точками.
Создайте и укажите путь к полю следующим образом:
- Найдите поля, содержащие необходимую информацию, в API маршрутов. Подробности см. в разделе «Ссылки на поля» .
- Определите пути к нужным вам полям и создайте для них маски полей . Подробности см. в разделе Определение маски поля, которую вы хотите использовать .
Объедините маски полей для всех необходимых вам полей , разделяя маски полей запятыми. Например, чтобы запросить
distanceMeters
для участка маршрута, а также продолжительность каждого шага участка маршрута, введите их оба, разделенные запятой, без пробелов:routes.legs.distanceMeters,routes.legs.steps.duration
Отправьте маску поля вместе с запросом API . Например, в запросе cURL вы должны указать маску поля с помощью
-H
иX-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Ссылки на поля
Чтобы просмотреть поля, которые вы можете запросить в ответе через маски полей, обратитесь к ссылкам на API маршрутов, указанным в следующем списке. Укажите поля в верблюжьем регистре, как показано в ссылке. Например, routePreference
.
Эти ссылки включают доступные поля; однако вам необходимо обратиться к иерархии полей, чтобы определить полный путь к маске поля. Подробные сведения о получении иерархии полей см. в разделе Определение маски поля, которую вы хотите использовать .
- Вычислить маску поля маршрута
- Вычисление масок полей матрицы маршрутов
- REST: указывает возвращаемые поля тела ответа .
- gRPC: указывает поля объекта RouteMatrixElement в возвращаемом ответе.
Определите, какие маски полей использовать
Вот как вы можете определить, какие поля вы хотите использовать, и построить для них маски полей:
- Запросите все поля, используя маску поля
*
. - Посмотрите на иерархию полей в ответе на те поля, которые вам нужны.
Создайте маски полей, используя иерархию полей, показанную на предыдущем шаге, в следующем формате:
topLevelField[.secondLevelField][.thirdLevelField][...]
Например, для этого частичного ответа от маршрута:
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
Если вы хотите вернуть только поле distanceMeters
для участка маршрута; то есть последние distanceMeters
в предыдущем примере, ваша маска поля выглядит следующим образом:
routes.legs.distanceMeters
Если вы хотите, вместо этого вы хотите вернуть поле distanceMeters
для каждого шага участка маршрута; то есть distanceMeters
в steps
предыдущего примера, ваша маска поля следующая:
routes.legs.steps.distanceMeters
Если вы хотите вернуть оба результата с приведенным выше результатом, ваша маска поля будет следующей:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
Примеры путей маски полей
В этом разделе содержатся дополнительные примеры указания пути к полю как части маски поля ответа в вызовах REST и gRPC.
REST-вызов computeRoutes
В первом примере вы используете вызов REST метода computeRoutes
для расчета маршрута. В этом примере в заголовке вы указываете маски полей для возврата полей distanceMeters
и duration
маршрута в ответе. Не забудьте добавить к имени поля префикс routes
.
X-Goog-FieldMask: routes.distanceMeters,routes.duration
REST-вызов computeRouteMatrix
Для метода REST computeRouteMatrix
, используемого для вычисления матрицы маршрутов, в заголовке укажите возврат originIndex
, destinationIndex
и duration
для каждой комбинации пункта отправления и назначения:
X-Goog-FieldMask: originIndex,destinationIndex,duration
вызов gRPC
Для gRPC установите переменную, содержащую маску поля ответа. Затем вы можете передать эту переменную в запрос.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
Рекомендации по траектории поля
Включите в ответ только те поля, которые вам нужны, чтобы вернуть только те поля, которые вам нужны:
- Уменьшает время обработки , поэтому результаты возвращаются с меньшей задержкой.
- Обеспечивает стабильную задержку . Если вы выберете все поля или выберете все поля на верхнем уровне, вы можете столкнуться с ухудшением производительности при добавлении новых полей, которые затем автоматически включаются в ваш ответ.
- Результатом является меньший размер ответа , что приводит к повышению пропускной способности сети.
- Гарантирует, что вы не запрашиваете ненужные данные , что помогает избежать ненужного времени обработки и выставленных счетов.
Дополнительные сведения о создании маски поля см. в файле field_mask.proto .
Запросить токен маршрута
Чтобы запросить, чтобы API маршрутов возвращал токены маршрутов для сгенерированных маршрутов, выполните следующие действия:
- Установите следующие параметры, необходимые для возврата токена маршрута:
- Установите для
travelMode
значениеDRIVE
. - Установите для
routingPreference
значениеTRAFFIC_AWARE
илиTRAFFIC_AWARE_OPTIMAL
.
- Установите для
- Убедитесь, что ни одна из путевых точек вашего маршрута не проходит
via
путевые точки. - Укажите маску поля
routes.routeToken
, чтобы вернуть токен маршрута:X-Goog-FieldMask: routes.routeToken
Вы можете использовать токен маршрута для запланированного маршрута в Navigation SDK. Дополнительные сведения см. в разделах «Планирование маршрута» (Android) или «Планирование маршрута» (iOS) .
Пример токена маршрута
Вот пример тела запроса cURL для одного исходного и одного конечного маршрута с использованием масок полей для запроса токена маршрута, а также длительности маршрута, расстояния и полилинии маршрута:
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-Api-Key: YOUR_API_KEY' \ -H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
Дополнительные сведения см. в справочнике по Compute Routes API .