Создать выбранные маршруты

На этой странице описывается, как создавать маршруты и добавлять пользовательские атрибуты с помощью API выбора дорог в следующих разделах:

Создать маршрут

Чтобы создать маршрут, отправьте POST запрос на конечную точку create .

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

Тело запроса должно быть JSON-объектом, определяющим ресурс SelectedRoute . Этот объект содержит следующую информацию:

  • Объект dynamicRoute со следующей информацией:
    • origin выбранного маршрута.
    • destination выбранного маршрута.
    • Любые intermediates маршрута, также называемые путевыми точками.
  • Уникальный selectedRouteId . Это значение должно содержать от 4 до 63 символов и содержать только буквы и цифры . Если вы не укажете идентификатор, система сгенерирует уникальный идентификатор для выбранного маршрута.

В следующем примере кода показана структура запроса POST к конечной точке create .

curl -X POST -d '
    {"dynamic_route": { \
      origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, \
      destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE} \
    }}' \' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

В случае успешного выполнения API возвращает ресурс SelectedRoute . Ответ включает selectedRouteId в поле name . Вы можете использовать selectedRouteId для получения или удаления ресурса SelectedRoute .

В следующем примере кода показана структура ответа успешного create конечной точки.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING"
}

Пакетное создание маршрутов

Чтобы создать несколько маршрутов в одном запросе, используйте конечную точку batchCreate . Эта конечная точка позволяет определить до 1000 маршрутов за один вызов.

Отправьте запрос POST на конечную точку batchCreate :

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

URL использует синтаксис перекодировки gRPC.

Тело запроса должно быть JSON-объектом, содержащим массив requests . Каждый объект в этом массиве представляет собой запрос CreateSelectedRouteRequest , определяющий отдельный ресурс SelectedRoute .

В следующем примере кода показана структура запроса POST к конечной точке batchCreate :

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_2, "longitude": ORIGIN_LONGITUDE_2},
          "destination": {"latitude": DESTINATION_LATITUDE_2, "longitude": DESTINATION_LONGITUDE_2}
        },
        "selectedRouteId": "route-two"
      }
    ]}
  ' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate"

В случае успеха API возвращает ответ, содержащий массив созданных ресурсов SelectedRoute .

В следующем примере кода показана структура ответа конечной точки batchCreate :

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

Создайте маршрут с промежуточными точками

Чтобы создать маршрут, проходящий через определённые точки между начальной и конечной точками, включите массив intermediates в объект dynamicRoute в теле запроса. Каждый элемент массива intermediates — это путевая точка, определяемая её latitude и longitude . Маршрут может содержать до 25 путевых точек.

В следующем примере кода показано, как создать SelectedRoute с промежуточными точками маршрута:

curl -X POST -d '
    {"dynamic_route": { \
        "origin": {"latitude": ORIGIN_LATITUDE , "longitude": ORIGIN_LONGITUDE}, \
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {"latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE}}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

Использовать пользовательские атрибуты маршрута

Для улучшения управления маршрутами и анализа данных в Roads Management Insights объект SelectedRoute включает поле route_attributes .

Используйте поле routeAttributes для определения собственных свойств для отдельных маршрутов, где каждый атрибут представляет собой пару «ключ-значение». Вы можете указать до 10 пар «ключ-значение» для каждого маршрута.

Эти атрибуты полезны для определения конкретных маршрутов или для группировки маршрутов на основе критериев, соответствующих вашим потребностям.

Ниже приведены некоторые примеры атрибутов маршрута, которые вы можете использовать:

  • "road_classification": "highway"
  • "maintenance_zone": "north_district"
  • "event_id": "marathon_2024"
  • "pavement_type": "asphalt"

При определении поля routeAttributes следуйте следующим рекомендациям:

  • Ключи не должны начинаться с префикса goog .
  • Длина каждого ключа и каждого значения не должна превышать 100 символов.

Затем вы можете использовать эти пользовательские routeAttributes в Roads Management Insights следующими способами:

  • Фильтрация уведомлений Pub/Sub: вы можете установить фильтры для своих подписок Pub/Sub, чтобы получать обновления только для тех маршрутов, которые соответствуют или не соответствуют определенным ключам атрибутов и их соответствующим значениям.
  • Уточните анализ BigQuery: в таблицах BigQuery вы можете использовать эти атрибуты для фильтрации определённых маршрутов по их значению. Вы также можете группировать маршруты по ключевому атрибуту для более точного анализа данных.

В следующем примере кода показано, как создать SelectedRoute с пользовательскими routeAttributes .

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"ATTRIBUTE_KEY":"ATTRIBUTE_VALUE"}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"