创建所选路线

本页面将通过以下部分介绍如何使用 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 个字符，有效字符为 a-z、A-Z、0-9、- 或 _。如果未提供 ID，系统会为所选路由生成唯一 ID。

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

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 资源。响应在 name 字段中包含 selectedRouteId。您可以使用此 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"
}

创建包含中间航点的路线

如需创建一条经过起点和终点之间特定地点的路线，请在请求正文的 dynamicRoute 对象中添加 intermediates 数组。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 个字符。

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

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

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

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 端点。此端点可让您在一次调用中定义最多 1,000 条路线。

向 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": [
        {
          "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"
    }
  ]
}