创建所选路线

本页将在以下部分中介绍如何使用 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 资源。响应中的 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"
}

批量创建路线

如需在单个请求中创建多条路线，请使用 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": [
      {
        "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 中的路线管理和数据分析功能，SelectedRoute 对象包含一个 route_attributes 字段。

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

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

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

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

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

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

然后，您可以通过以下方式在道路管理数据洞见中使用这些自定义 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"