Разработчики из Европейской экономической зоны (ЕЭЗ)

Выберите поля, которые нужно вернуть

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

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

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

Подробную информацию о параметрах URL можно найти в статье Системные параметры.

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

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

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

  1. Найдите поля, содержащие нужную информацию. Подробнее о ссылках на поля…
  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
Примеры и подробные сведения приведены в разделах ниже.

Справочник по полям

Чтобы узнать, какие поля можно запрашивать в ответе с помощью масок полей, ознакомьтесь с документацией по методам Compute Routes и Compute Route Matrix в Routes API. Ссылки на нее приведены ниже. Указывайте поля в верблюжьем регистре, как показано в справочнике. например routePreference (2-е издание).

В этих справочных материалах перечислены доступные поля, но чтобы определить полный путь маски поля, необходимо обратиться к иерархии полей. Подробнее о том, как получить иерархию полей…

  • Маска поля для расчета маршрута
    • REST: указывает поля объекта Route, которые нужно вернуть в ответе. Перед ними добавляется префикс routes., например routes.distanceMeters.
    • gRPC: указывает, какие поля объекта Route нужно вернуть в ответе.
  • Маски полей Compute Route Matrix
    • 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 к computeRoutes

Для метода gRPC computeRoutes, используемого для расчета маршрута, задайте переменную, содержащую маску поля ответа, чтобы в ответе возвращались поля маршрута distanceMeters, duration и закодированной ломаной линии. Затем вы можете передать эту переменную в запрос:

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

Вызов gRPC к computeRouteMatrix

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

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

Примечания о путях к полям

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

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

Подробную информацию о создании маски поля можно найти в статье field_mask.proto.