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

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

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

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

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

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

Чтобы узнать, какие поля можно запросить в ответе с помощью масок полей, ознакомьтесь со справочными материалами по 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.