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

Выберите поля для возврата

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

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

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

Полевые ссылки

Чтобы узнать, какие поля можно запросить в ответе с помощью масок полей, обратитесь к справочникам Routes API Compute Routes или Compute Route Matrix, ссылки на которые приведены в следующем списке. Указывайте поля в стиле «camel», как показано в справочнике. Например, routePreference .

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

  • Вычислить маску поля маршрута
    • 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"
)

Соображения относительно траектории поля

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

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

Более подробную информацию о построении маски поля см. в field_mask.proto .