你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Route - Post Route Range

参考

服务:: Maps

API 版本:: 2024-07-01-preview

适用于：请参阅定价层。

路线范围 API 创建一个多边形，该多边形描述根据指定的时间或距离预算，从特定阈值内的给定位置到达的区域。多边形边界（或 Isochrone）以逆时针方向返回，以及作为原点结果的精确多边形中心。

返回的多边形可用于空间筛选，以搜索所提供的 Isochrone 中感兴趣的特征。

有关国家/地区路由可用性的信息，请参阅 Azure Maps 路由覆盖范围。

重要

通过使用此功能，你同意预览版法律条款。有关更多详细信息，请参阅预览版补充条款。

POST https://atlas.microsoft.com/route/range?api-version=2024-07-01-preview

URI 参数

名称	在	必需	类型	说明
api-version	query	True	string	Azure Maps API 的版本号。

请求头

Media Types: "application/geo+json"

名称	必需	类型	说明
x-ms-client-id		string	指定哪个帐户与 Microsoft Entra ID 安全模型结合使用。它表示 Azure Maps 帐户的唯一 ID，可以从 Azure Maps 管理平面帐户 API 检索。若要在 Azure Maps 中使用 Microsoft Entra ID 安全性，请参阅以下文章以获取指导。

请求正文

Media Types: "application/geo+json"

名称	必需	类型	说明
geometry	True	RouteRangePointGeometry	指定 `GeoJSON` Point Geometry 对象。有关详细信息，请参阅 RFC 7946。
properties	True	InputRouteRangeProperties	指定要用于计算时序多边形的参数。
type	True	FeaturesItemTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 Feature。有关详细信息，请参阅 RFC 7946。

响应

名称	类型	说明
200 OK	RouteRangeResponse	还行 Media Types: "application/geo+json", "application/json"
Other Status Codes	MapsErrorResponse	发生意外错误。 Media Types: "application/geo+json", "application/json" 标头 x-ms-error-code: string

名称

类型

说明

200 OK

RouteRangeResponse

还行

Media Types: "application/geo+json", "application/json"

Other Status Codes

MapsErrorResponse

发生意外错误。

Media Types: "application/geo+json", "application/json"

标头

x-ms-error-code: string

安全性

AADToken

这些 Microsoft Entra OAuth 2.0 流。与 Azure 基于角色的访问配对时，控制它可用于控制对 Azure Maps REST API 的访问。 Azure 基于角色的访问控制用于指定对一个或多个 Azure Maps 资源帐户或子资源的访问。任何用户、组或服务主体都可以通过内置角色或由一个或多个对 Azure Maps REST API 的权限组成的自定义角色授予访问权限。

若要实现方案，建议查看身份验证概念。总之，此安全定义提供了一种解决方案，用于通过能够针对特定 API 和范围进行访问控制的对象对应用程序建模。

注意

此安全定义要求使用 x-ms-client-id 标头来指示应用程序请求访问的 Azure Maps 资源。这可以从地图管理 API获取。
Authorization URL 特定于 Azure 公有云实例。主权云具有唯一的授权 URL，Microsoft Entra ID 配置。
Azure 基于角色的访问控制是通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 从 Azure 管理平面配置的。
使用 Azure Maps Web SDK 允许为多个用例设置基于应用程序的配置。
有关Microsoft标识平台的详细信息，请参阅 Microsoft标识平台概述。

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/authorize

作用域

名称	说明
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

这是在通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面创建 Azure Maps 资源时预配的共享密钥。

使用此密钥，任何应用程序都有权访问所有 REST API。换句话说，这些密钥当前可视为为其颁发的帐户的主密钥。

对于公开的应用程序，我们建议使用可安全地存储此密钥的 Azure Maps REST API 的服务器到服务器访问。

类型: apiKey
在: header

SAS Token

这是一个共享访问签名令牌，它通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面在 azure Maps 资源上的列表 SAS 操作创建。

使用此令牌，任何应用程序都有权使用 Azure 基于角色的访问控制进行访问，并精细控制特定令牌的过期、速率和区域。换句话说，SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。

对于公开的应用程序，建议在映射帐户资源上配置允许的源的特定列表，以限制呈现滥用并定期续订 SAS 令牌。

类型: apiKey
在: header

示例

Successfully retrieve a set of locations that can be reached from the origin point based on the specified conditions

示例请求

HTTP

POST https://atlas.microsoft.com/route/range?api-version=2024-07-01-preview

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      5.86605,
      50.9745
    ]
  },
  "properties": {
    "timeBudgetInSec": 6000
  }
}

示例响应

状态代码:: 200

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          5.86605,
          50.9745
        ]
      },
      "properties": {
        "type": "center"
      }
    },
    {
      "type": "Feature",
      "bbox": [
        3.62838,
        49.83259,
        7.9826,
        52.25674
      ],
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              5.73602,
              52.03704
            ],
            [
              5.59435,
              52.09456
            ],
            [
              5.42279,
              52.16815
            ],
            [
              5.21276,
              52.25047
            ],
            [
              5.15355,
              52.21374
            ],
            [
              4.96687,
              52.25674
            ],
            [
              4.739,
              52.07834
            ],
            [
              4.72513,
              52.05647
            ],
            [
              4.53237,
              51.94553
            ],
            [
              4.31165,
              51.70119
            ],
            [
              4.28917,
              51.5837
            ],
            [
              3.82685,
              51.48463
            ],
            [
              3.62838,
              51.21096
            ],
            [
              3.89244,
              50.6814
            ],
            [
              3.93493,
              50.66791
            ],
            [
              3.98156,
              50.49042
            ],
            [
              4.47995,
              50.30944
            ],
            [
              4.60502,
              50.24448
            ],
            [
              4.89999,
              50.24467
            ],
            [
              5.04206,
              50.08735
            ],
            [
              5.23042,
              49.99214
            ],
            [
              5.40994,
              49.88478
            ],
            [
              5.46178,
              49.85797
            ],
            [
              5.7196,
              49.86279
            ],
            [
              5.74151,
              49.83259
            ],
            [
              5.9387,
              50.22239
            ],
            [
              6.08535,
              50.0011
            ],
            [
              6.12089,
              50.04616
            ],
            [
              6.28373,
              50.09472
            ],
            [
              6.51654,
              49.95863
            ],
            [
              6.61034,
              50.00485
            ],
            [
              6.70295,
              50.00587
            ],
            [
              6.65865,
              50.2947
            ],
            [
              6.79276,
              50.36903
            ],
            [
              7.32163,
              50.31614
            ],
            [
              7.58782,
              50.36737
            ],
            [
              7.7626,
              50.46919
            ],
            [
              7.9826,
              50.96246
            ],
            [
              7.55924,
              51.07086
            ],
            [
              7.58138,
              51.36614
            ],
            [
              7.67861,
              51.52015
            ],
            [
              7.35175,
              51.65781
            ],
            [
              7.21664,
              51.81916
            ],
            [
              7.0467,
              51.9587
            ],
            [
              6.67267,
              51.82713
            ],
            [
              6.48424,
              51.81133
            ],
            [
              6.27316,
              51.9368
            ],
            [
              6.14452,
              52.01701
            ],
            [
              6.09312,
              52.20847
            ],
            [
              6.01297,
              52.23705
            ],
            [
              5.86605,
              50.9745
            ],
            [
              5.73602,
              52.03704
            ]
          ]
        ]
      },
      "properties": {
        "type": "boundary"
      }
    }
  ]
}

定义

名称	说明
AdrTunnelRestrictionCodeEnum	ADR 隧道限制代码。 ADR是一项欧洲关于道路危险品国际运输的协议。 ADR 隧道限制代码用于确定是否允许车辆通过隧道，并限制危险品的运输。
FeaturesItemTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 Feature。有关详细信息，请参阅 RFC 7946。
FeatureTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。
InputRouteRangeProperties	指定要用于计算时序多边形的参数。
MapsErrorDetail	错误详细信息。
MapsErrorResponse	Azure Maps API 的常见错误响应，以返回失败操作的错误详细信息。
MapsInnerError	包含与当前对象有关错误的更具体信息的对象。
RouteRangeAvoidEnum	指定确定可访问位置时路由计算应遵循的限制。避免在请求中支持多个值。示例：“avoid”： [“limitedAccessHighways”， “tollRoads”]
RouteRangeFeatureProperties	路由范围属性。
RouteRangeFeaturesItem	包含 Geometry 对象的 GeoJSON 特征对象以及路由的其他属性。
RouteRangeOptimizeRouteEnum	指定要用于优化路由的参数。如果未定义，则默认值为“fastestWithoutTraffic”，它将返回路线，以尽量减少旅行时间，而无需使用当前交通信息。示例：“optimizeRoute”：“shortest”
RouteRangePointGeometry	指定 `GeoJSON` Point Geometry 对象。有关详细信息，请参阅 RFC 7946。
RouteRangePolygonGeometry	指定 `GeoJSON` 多边形 Geometry 对象。有关详细信息，请参阅 RFC 7946。
RouteRangeRequest	指定范围计算的起点。 `GeoJSON` 功能对象和其他属性。有关详细信息，请参阅 RFC 7946。
RouteRangeResponse	此对象是从成功调用返回的。
RouteRangeTravelModeEnum	指定计算范围多边形时要考虑的旅行配置文件。如果未指定，则默认值为“driving”。示例：“travelMode”：“driving”
RouteRangeTypeEnum	响应中返回的功能对象的特征类型。
RouteRangeVehicleSpec	指定计算可到达位置时要考虑的车辆高度、重量、最大速度、货物类型等车辆属性。这有助于避免低桥通关、道路限制、难以右转，根据车辆规格提供优化的卡车路线。车辆属性在 vehicleSpec 属性中指定。
VehicleLoadTypeEnum	可能归类为危险物质的货物类型，并受某些道路限制。可用的 vehicleLoadType 值为美国 Hazmat 类 1 到 9，以及用于其他国家/地区的通用分类。以 USHazmat 开头的值用于美国路由，而其他Hazmat 应用于所有其他国家/地区。 vehicleLoadType 支持请求中的多个值。

AdrTunnelRestrictionCodeEnum

枚举

ADR 隧道限制代码。 ADR是一项欧洲关于道路危险品国际运输的协议。 ADR 隧道限制代码用于确定是否允许车辆通过隧道，并限制危险品的运输。

值	说明
B	具有代码 B 的车辆受限于 ADR 隧道类别 B、C、D 和 E 的道路。
C	具有代码 C 的车辆受 ADR 隧道类别 C、D 和 E 的道路限制
D	具有代码 D 的车辆受 ADR 隧道类别 D 和 E 的道路限制。
E	具有代码 E 的车辆受 ADR 隧道类别 E 的道路限制。

FeaturesItemTypeEnum

枚举

指定 GeoJSON 类型。唯一支持的对象类型是 Feature。有关详细信息，请参阅 RFC 7946。

值	说明
Feature	指定功能对象类型 `GeoJSON`。

FeatureTypeEnum

枚举

指定 GeoJSON 类型。唯一支持的对象类型是 FeatureCollection。有关详细信息，请参阅 RFC 7946。

值	说明
FeatureCollection	指定 `GeoJSONFeatureCollection` 对象类型。

InputRouteRangeProperties

Object

指定要用于计算时序多边形的参数。

名称	类型	默认值	说明
avoid	RouteRangeAvoidEnum[]		指定确定可访问位置时路由计算应遵循的限制。避免在请求中支持多个值。示例：“avoid”： [“limitedAccessHighways”， “tollRoads”]
departAt	string		从原点出发的日期和时间（格式为 dateTime 值）由 RFC 3339，第 5.6 节定义。如果未指定时区偏移量，则假定 UTC。如果未设置 `departAt`，则默认值为当前时间。例： “departAt”： “2023-06-01T09：30：00.000-07：00”
distanceBudgetInMeters	number		距离预算指定可从原点行驶的最大范围（以米为单位）。指定 `timeBudgetInSec` 时无法设置它。当 `isSimplifiedPolygon` 为 false 时，支持的最大距离为 360,000 米;否则为 500,000 米。示例：“distanceBudgetInMeters”：5000
isSimplifiedPolygon	boolean	true	使用此函数可以指定是否需要简化多边形，以减小多边形顶点的数量，同时保留形状。默认情况下，API 返回低定义多边形。
optimizeRoute	RouteRangeOptimizeRouteEnum	fastestWithoutTraffic	指定要用于优化路由的参数。如果未定义，则默认值为“fastestWithoutTraffic”，它将返回路线，以尽量减少旅行时间，而无需使用当前交通信息。示例：“optimizeRoute”：“shortest”
timeBudgetInSec	number		时间预算指定可用于旅行的最长时间（以秒为单位），定义从出发点到此时间约束内可以走多远。指定 `distanceBudgetInMeters` 时无法设置它。当 `isSimplifiedPolygon` 为 false 时，支持的最大时间为 14,400 秒;否则为 21,600 秒。示例：“timeBudgetInSec”：3600
travelMode	RouteRangeTravelModeEnum	driving	指定计算范围多边形时要考虑的旅行配置文件。如果未指定，则默认值为“driving”。示例：“travelMode”：“driving”
vehicleSpec	RouteRangeVehicleSpec		指定计算可到达位置时要考虑的车辆高度、重量、最大速度、货物类型等车辆属性。这有助于避免低桥通关、道路限制、难以右转，根据车辆规格提供优化的卡车路线。车辆属性在 vehicleSpec 属性中指定。

MapsErrorDetail

Object

错误详细信息。

名称	类型	说明
code	string	服务器定义的错误代码集之一。
details	MapsErrorDetail[]	导致此报告错误的特定错误的详细信息数组。
innererror	MapsInnerError	包含与当前对象有关错误的更具体信息的对象。
message	string	错误的人工可读表示形式。
target	string	错误的目标。

MapsErrorResponse

Object

Azure Maps API 的常见错误响应，以返回失败操作的错误详细信息。

名称	类型	说明
error	MapsErrorDetail	错误详细信息。

MapsInnerError

Object

包含与当前对象有关错误的更具体信息的对象。

名称	类型	说明
code	string	错误代码。
innererror	MapsInnerError	包含与当前对象有关错误的更具体信息的对象。

RouteRangeAvoidEnum

枚举

指定确定可访问位置时路由计算应遵循的限制。避免在请求中支持多个值。

示例：“avoid”： [“limitedAccessHighways”， “tollRoads”]

值	说明
borderCrossings	避免在路线中越过国家/地区边界。
carTrains	避免汽车列车。
carpools	避免需要使用汽车池的路线。
ferries	避免在路线中使用渡轮。
limitedAccessHighways	避免在路线中使用有限的访问高速公路。
lowEmissionZones	避免路由中的低排放区域。
tollRoads	避免在路线中使用收费公路。
tunnels	避免在路由中使用隧道。
unpavedRoads	避免路线中未修补的道路。

RouteRangeFeatureProperties

Object

路由范围属性。

名称	类型	说明
type	RouteRangeTypeEnum	响应中返回的功能对象的特征类型。

RouteRangeFeaturesItem

Object

包含 Geometry 对象的 GeoJSON 特征对象以及路由的其他属性。

名称	类型	说明
bbox	number[]	地球上的矩形区域定义为边界框对象。矩形的两侧由纬度和经度值定义。有关详细信息，请参阅 RFC 7946 第 5 节。示例：“bbox”： [-10.0， -10.0， 10.0， 10.0]
geometry	RouteRangeGeometry: RouteRangePointGeometry RouteRangePolygonGeometry	有效的 `GeoJSON` Geometry 对象。有关详细信息，请参阅 RFC 7946。
properties	RouteRangeFeatureProperties	路由范围属性。
type	FeaturesItemTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 Feature。有关详细信息，请参阅 RFC 7946。

RouteRangeOptimizeRouteEnum

枚举

指定要用于优化路由的参数。如果未定义，则默认值为“fastestWithoutTraffic”，它将返回路线，以尽量减少旅行时间，而无需使用当前交通信息。

示例：“optimizeRoute”：“shortest”

值	说明
fastestWithTraffic	计算路由，以最大程度地减少使用当前流量信息的时间。 `Note`：仅支持驾驶和卡车旅行模式。
fastestWithoutTraffic	查找最快的路线，而不考虑交通信息。
shortest	计算路线以最大程度地减少距离。不使用流量信息。

RouteRangePointGeometry

Object

指定 GeoJSON Point Geometry 对象。有关详细信息，请参阅 RFC 7946。

名称	类型	说明
coordinates	number[]	`Position` 是包含两个或多个元素的数字数组。前两个元素经度和纬度，精确按顺序排列。海拔/海拔是可选的第三个元素。有关详细信息，请参阅 RFC 7946。
type	string: Point	指定 `GeoJSON` Geometry 对象的几何类型。有关详细信息，请参阅 RFC 7946。

RouteRangePolygonGeometry

Object

指定 GeoJSON 多边形 Geometry 对象。有关详细信息，请参阅 RFC 7946。

名称	类型	说明
coordinates	number[]	`GeoJson Polygon` 几何图形类型的坐标。
type	string: Polygon	指定 `GeoJSON` Geometry 对象的几何类型。有关详细信息，请参阅 RFC 7946。

RouteRangeRequest

Object

指定范围计算的起点。 GeoJSON 功能对象和其他属性。有关详细信息，请参阅 RFC 7946。

名称	类型	说明
geometry	RouteRangePointGeometry	指定 `GeoJSON` Point Geometry 对象。有关详细信息，请参阅 RFC 7946。
properties	InputRouteRangeProperties	指定要用于计算时序多边形的参数。
type	FeaturesItemTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 Feature。有关详细信息，请参阅 RFC 7946。

RouteRangeResponse

Object

此对象是从成功调用返回的。

名称	类型	说明
features	RouteRangeFeaturesItem[]	`GeoJSON` 包含 Geometry 对象和其他属性的功能对象。有关详细信息，请参阅 RFC 7946 第 3.2 节。
type	FeatureTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。

RouteRangeTravelModeEnum

枚举

指定计算范围多边形时要考虑的旅行配置文件。如果未指定，则默认值为“driving”。

示例：“travelMode”：“driving”

值	说明
driving	适用于汽车的路由配置文件用于范围多边形计算。
truck	适用于卡车等商用车辆的路线配置文件用于范围多边形计算。

RouteRangeTypeEnum

枚举

响应中返回的功能对象的特征类型。

值	说明
boundary	边界特征类型表示范围多边形。
center	中心点特征类型表示用于范围多边形计算的点。

RouteRangeVehicleSpec

Object

指定计算可到达位置时要考虑的车辆高度、重量、最大速度、货物类型等车辆属性。这有助于避免低桥通关、道路限制、难以右转，根据车辆规格提供优化的卡车路线。车辆属性在 vehicleSpec 属性中指定。

名称	类型	默认值	说明
adrTunnelRestrictionCode	AdrTunnelRestrictionCodeEnum		ADR 隧道限制代码。 ADR是一项欧洲关于道路危险品国际运输的协议。 ADR 隧道限制代码用于确定是否允许车辆通过隧道，并限制危险品的运输。
axleCount	integer		车辆上的轴数。
axleWeight	integer	0	车辆每轴重量（以公斤为单位）。值为 0 表示不考虑每个轴的重量限制。
height	number	0	车辆的高度（以米为单位）。值为 0 表示不考虑高度限制。
isVehicleCommercial	boolean	False	车辆是否用于商业目的。商业车辆不得在一些公路上行驶。
length	number	0	车辆长度（以米为单位）。值为 0 表示不考虑长度限制。
loadType	VehicleLoadTypeEnum[]		可能归类为危险物质的货物类型，并受某些道路限制。可用的 vehicleLoadType 值为美国 Hazmat 类 1 到 9，以及用于其他国家/地区的通用分类。以 USHazmat 开头的值用于美国路由，而其他Hazmat 应用于所有其他国家/地区。 vehicleLoadType 支持请求中的多个值。
maxSpeed	integer	0	车辆的最大速度（以公里/小时为单位）。车辆配置文件中的最大速度用于检查是否允许车辆在高速公路上。值为 0 表示将在路线规划期间确定并应用车辆的相应值。在路由规划期间，可能会重写非零值。例如，当前流量流为 60 公里/小时。如果车辆最大速度设置为 50 公里/小时，路由引擎将考虑 60 公里/小时，因为这是目前的情况。如果车辆的最大速度为 80 公里/小时，但当前交通流量为 60 公里/小时，则路由引擎将再次使用 60 公里/小时。
weight	integer	0	车辆重量（以公斤为单位）。值为 0 表示不考虑权重限制。
width	number	0	车辆宽度（以米为单位）。值为 0 表示不考虑宽度限制。

VehicleLoadTypeEnum

枚举

可能归类为危险物质的货物类型，并受某些道路限制。可用的 vehicleLoadType 值为美国 Hazmat 类 1 到 9，以及用于其他国家/地区的通用分类。以 USHazmat 开头的值用于美国路由，而其他Hazmat 应用于所有其他国家/地区。 vehicleLoadType 支持请求中的多个值。

值	说明
USHazmatClass1	炸药
USHazmatClass2	压缩气体
USHazmatClass3	易燃液体
USHazmatClass4	易燃固体
USHazmatClass5	Oxidizers
USHazmatClass6	毒药
USHazmatClass7	放射性
USHazmatClass8	腐蚀
USHazmatClass9	杂项
otherHazmatExplosive	炸药
otherHazmatGeneral	杂项
otherHazmatHarmfulToWater	有害于水