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

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

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

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

Дополнительную информацию о параметрах URL см. в разделе Системные параметры .

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

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

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

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

Напротив, вы должны ввести значения параметров, как показано. Например, для routingPreference необходимо ввести TRAFFIC_AWARE .

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

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

Рекомендации по траектории поля

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

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

Примечание. Если при анализе ответного сообщения поле в ответном сообщении содержит значение по умолчанию, это поле может быть опущено в ответе, даже если вы указали его в маске поля ответа. Дополнительную информацию см. в Языковом руководстве (proto3) . Например, когда вы вычисляете матрицу маршрутов, поле distanceMeters ответа может содержать значение 0, его значение по умолчанию. Поскольку 0 — это значение по умолчанию для distanceMeters , оно опускается в ответе.

Дополнительные сведения о создании маски поля см. в файле field_mask.proto .