创建所选路线

本页的以下部分介绍了如何使用 Roads Selection API 创建路线和添加自定义属性：

创建路线

如需创建路线，请向 create 端点发送 POST 请求。

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

请求正文 必须是定义 SelectedRoute 资源的 JSON 对象。此对象指定了以下信息：

  • 一个 dynamicRoute 对象，其中包含以下信息：
  • 一个唯一的 selectedRouteId。此值的长度必须介于 4 到 63 个字符之间，并且只能使用字母数字字符 。如果您未提供 ID，系统会为所选路线生成一个唯一 ID。

以下代码示例展示了向 create端点发送POST请求的结构。

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 条路线。

向 batchCreate 端点发送 POST 请求：

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

网址采用 gRPC 转码语法。

请求正文 必须是包含 requests 数组的 JSON 对象。 此数组中的每个对象都是一个 CreateSelectedRouteRequest，用于 定义单个 SelectedRoute 资源。

以下代码示例展示了向 batchCreate 端点发送 POST 请求的结构：

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"
    }
  ]
}

创建包含中间航点的路线

如需创建一条路线，使其经过起点和 终点之间的特定点，请在请求正文的 dynamicRoute 对象中添加 intermediates 数组。 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 中的路线管理和数据分析， the SelectedRoute 对象包含 route_attributes 字段。

使用 routeAttributes 字段为 各个路线定义自己的自定义属性，其中每个属性都是一个键值对。您可以为每条路线提供最多 10 个自定义键值对。

这些属性有助于识别特定路线，或根据与您的需求相关的条件对路线进行分组。

以下是一些您可以使用的路线属性示例：

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

定义 routeAttributes 字段时，请遵循以下准则：

  • 键不得以 goog 前缀开头。
  • 每个键和每个值的长度不得超过 100 个字符。

然后，您可以在 Roads Management Insights 中通过以下方式使用这些自定义 routeAttributes：

  • 过滤 Pub/Sub 通知 ：您可以对 Pub/Sub 订阅设置过滤条件，以便仅接收与特定属性键及其对应值匹配或不匹配的路线的更新。
  • 优化 BigQuery 分析 ：在 BigQuery 表中，您可以使用这些属性根据属性的值过滤特定路线。您还可以按特定属性键对路线进行分组，以便进行更有针对性的数据分析。

以下代码示例展示了如何创建包含自定义 routeAttributes的SelectedRoute。

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"