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

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

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

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