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

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

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

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

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

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

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

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

  1. Найдите поля, содержащие необходимую информацию, в API маршрутов. Подробности см. в разделе «Ссылки на поля» .
  2. Определите пути к нужным вам полям и создайте для них маски полей . Подробности см. в разделе Определение маски поля, которую вы хотите использовать .

  3. Объедините маски полей для всех необходимых вам полей , разделяя маски полей запятыми. Например, чтобы запросить distanceMeters для участка маршрута, а также продолжительность каждого шага участка маршрута, введите их оба, разделенные запятой, без пробелов:

    routes.legs.distanceMeters,routes.legs.steps.duration

  4. Отправьте маску поля вместе с запросом API . Например, в запросе cURL вы должны указать маску поля с помощью -H и X-Goog-FieldMask :

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Примеры и дополнительную информацию см. в следующих разделах.

Ссылки на поля

Чтобы просмотреть поля, которые вы можете запросить в ответе через маски полей, обратитесь к ссылкам на API маршрутов, указанным в следующем списке. Укажите поля в верблюжьем регистре, как показано в ссылке. Например, routePreference .

Эти ссылки включают доступные поля; однако вам необходимо обратиться к иерархии полей, чтобы определить полный путь к маске поля. Подробные сведения о получении иерархии полей см. в разделе Определение маски поля, которую вы хотите использовать .

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

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

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

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

  3. Создайте маски полей, используя иерархию полей, показанную на предыдущем шаге, в следующем формате:

    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 маршрутов возвращал токены маршрутов для сгенерированных маршрутов, выполните следующие действия:

  1. Установите следующие параметры, необходимые для возврата токена маршрута:
    • Установите для travelMode значение DRIVE .
    • Установите для routingPreference значение TRAFFIC_AWARE или TRAFFIC_AWARE_OPTIMAL .
  2. Убедитесь, что ни одна из путевых точек вашего маршрута не проходит via путевые точки.
  3. Укажите маску поля 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'

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