Update selected routes

本页介绍了如何使用 Roads Selection API 更新已创建的路线：

  • 更新路线：使用 patch 端点更新单条路线的详细信息。
  • 批量更新路线：使用 batchUpdate 端点在单个 请求中更新多条路线的详细信息。

更新路线

如需更新路线，请向 patch 端点发送 PATCH 请求：

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

请求正文 必须是包含要更新的 SelectedRoute 字段的 JSON 对象。可更新的字段包括 displayName、 routeAttributes 和 dynamicRoute。更新路线几何图形 (dynamicRoute) 时，您必须提供整个 dynamicRoute 对象（起点、目的地和中间途经点）。不支持更新部分子字段。无法修改只读系统字段，例如 name、createTime 和 state。BigQuery 中的历史数据将在同一 selectedRouteId 下保留旧几何图形和更新后的几何图形的数据。如果您需要单独的历史数据，请创建新路线，而不是执行更新。

更新路线的几何图形 (dynamicRoute) 需要重新验证。 当路线处于 STATE_RUNNING 或 STATE_INVALID 状态时，允许更新几何图形；如果路线处于 STATE_VALIDATING 或 STATE_DELETING 状态，则会拒绝更新。如需了解详情，请参阅验证和路线状态。 在除 STATE_DELETING 之外的所有状态下，都允许更新元数据，例如 displayName 或 routeAttributes。

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

curl -X PATCH -d '{
    "dynamicRoute": {
      "origin": {
        "latitude": 38.5817,
        "longitude": -121.4944
      },
      "destination": {
        "latitude": 38.5449,
        "longitude": -121.7405
      }
    }
  }' \
-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/"\
"SELECTED_ROUTE_ID?updateMask=dynamicRoute"

成功后，API 会返回更新后的 SelectedRoute 资源：

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": 38.5817,
      "longitude": -121.4944
    },
    "destination": {
      "latitude": 38.5449,
      "longitude": -121.7405
    }
  },
  "createTime": "2026-08-14T20:58:41.345418Z",
  "state": "STATE_VALIDATING"
}

批量更新路线

如需在单个请求中更新多条路线，请使用 batchUpdate 端点。借助此端点，您可以在一次调用中更新最多 1,000 条路线。批量更新是原子操作：如果请求中的任何路线未能通过验证或无法更新，则不会修改批次中的任何路线。

向 batchUpdate 端点发送 POST 请求：

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

请求正文 必须是包含 requests 数组的 JSON 对象。此数组中的每个对象都是一个 UpdateSelectedRouteRequest，用于指定路线 name、可选的商品级 updateMask 以及要更新的 selectedRoute 字段。

updateMask 是一个可选参数，用于指定要更新的字段列表（displayName、routeAttributes 或整个 dynamicRoute 对象）。设置 updateMask=* 表示完全替换。可以在 requests 中的每个单独项内指定 updateMask，也可以将其移至批量请求正文的顶层，以应用于批次中的所有更新路线。 如果省略 updateMask，则表示更新请求中填充的所有可更新字段。如果在批次级和商品级同时设置了 updateMask，则它们必须匹配。指定冲突的掩码会导致 INVALID_ARGUMENT 错误。

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

curl -X POST -d '{
    "requests": [
      {
        "selectedRoute": {
          "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
          "displayName": "DISPLAY_NAME_1",
          "dynamicRoute": {
            "origin": {"latitude": 37.5, "longitude": -122.1},
            "destination": {"latitude": 37.8, "longitude": -122.5}
          }
        },
        "updateMask": "displayName,dynamicRoute"
      },
      {
        "selectedRoute": {
          "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
          "displayName": "DISPLAY_NAME_2",
          "dynamicRoute": {
            "origin": {"latitude": 37.5, "longitude": -122.1},
            "destination": {"latitude": 37.8, "longitude": -122.5}
          }
        },
        "updateMask": "displayName,dynamicRoute"
      }
    ]}' \
-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:batchUpdate"

成功后，API 会返回一个响应，其中包含已更新的 SelectedRoute资源的数组：

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "displayName": "DISPLAY_NAME_1",
      "dynamicRoute": {
        "origin": {
          "latitude": 37.5,
          "longitude": -122.1
        },
        "destination": {
          "latitude": 37.8,
          "longitude": -122.5
        }
      },
      "createTime": "2026-08-14T20:58:41.345418Z",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "displayName": "DISPLAY_NAME_2",
      "dynamicRoute": {
        "origin": {
          "latitude": 37.5,
          "longitude": -122.1
        },
        "destination": {
          "latitude": 37.8,
          "longitude": -122.5
        }
      },
      "createTime": "2026-08-14T20:58:41.345418Z",
      "state": "STATE_VALIDATING"
    }
  ]
}