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

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

Вы указываете список полей, создавая маску поля ответа . Затем вы передаете маску поля ответа любому методу, используя параметр 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 .

Напротив, вы должны ввести значения параметров, как показано. Например, для routingPreference необходимо ввести TRAFFIC_AWARE .

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

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

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

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

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"
)

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

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

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

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

Дополнительные сведения о создании маски поля см. в файле 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 .