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

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

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

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

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