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

В этой статье рассказывается, как создавать маршруты и добавлять настраиваемые атрибуты с помощью Roads Selection 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 '
    {
      "dynamicRoute": {
        "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"
}

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

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

В приведенном ниже фрагменте кода показано, как создать объект SelectedRoute с промежуточными точками:

curl -X POST -d '
    {
      "dynamicRoute": {
        "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 включает поле routeAttributes.

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

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

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

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

При заполнении поля routeAttributes следуйте приведенным ниже рекомендациям.

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

Затем вы можете использовать эти пользовательские routeAttributes в данных для управления дорогами следующими способами:

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

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

curl -X POST -d '
    {
    "dynamicRoute": {
      "origin": {
        "latitude": ORIGIN_LATITUDE,
        "longitude": ORIGIN_LONGITUDE
      },
      "destination": {
        "latitude": DESTINATION_LATITUDE,
        "longitude": DESTINATION_LONGITUDE
      }
    },
    "routeAttributes": {
      "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"

Как создать несколько маршрутов одновременно

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

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

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

URL имеет синтаксис gRPC Transcoding.

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

В приведенном ниже фрагменте кода показана структура запроса POST к конечной точке batchCreate:

curl -X POST -d '
    {
      "requests": [
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_1,
                "longitude": ORIGIN_LONGITUDE_1
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_1,
                "longitude": DESTINATION_LONGITUDE_1
              }
            }
          },
          "selectedRouteId": "route-one"
        },
        {
          "selectedRoute": {
            "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"
    }
  ]
}