你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
本文介绍如何将必应地图 计算路线 API 迁移到 Azure Maps 路线方向 API。 Azure Maps 路线方向是一个 API，它返回汽车（驾驶）、商业卡车和步行路线的出发地和目的地之间的理想路线。 该路线考虑到多个因素，例如当天的当前交通状况和一周中该天该时段的典型道路速度。
先决条件
- 一个 Azure 帐户
- Azure Maps 帐户
- 订阅密钥或其他形式的 Azure Maps 身份验证
显著差异
- 必应地图计算路线 API 支持 GET 请求。 Azure Maps 路线方向 API 支持 POST 请求。
- 必应地图计算路线 API 支持 XML 和 JSON 响应格式。 Azure Maps 路线方向 API 支持 GeoJSON 格式。
- 必应地图计算路线 API 要求 waypoints 和 viaWaypoints 采用纬度/经度格式，而 Azure Maps 要求它们采用经度/纬度格式，如 GeoJSON 格式定义。
- 必应地图 Calculate a Route API 支持 waypoints 和 viaWaypoints 作为点、地标或地址。 Azure Maps 路线方向 API 仅支持点。 若要将地标或地址转换为某个点，可以使用 Azure Maps 获取地理编码 API。
- 必应地图的计算路线 API 支持公共交通路线。 Azure Maps 路线指引 API 不支持该功能。
- 与必应地图企业版不同，Azure Maps 是一项支持指定地理范围的全局服务，允许对欧洲（欧盟）或美国（美国）地理区域（地理区域）的数据驻留限制。 所有请求（包括输入数据）都专门在指定的地理区域进行处理。 有关详细信息，请参阅 地理范围。
安全性和身份验证
必应地图企业版仅支持 API 密钥身份验证。 Azure Maps 支持通过多种方式对 API 调用进行身份验证，例如订阅密钥、Microsoft Entra ID 和共享访问签名 (SAS) 令牌。 有关 Azure Maps 中的安全性和身份验证的详细信息，请参阅 Azure Maps 路线说明文档中的 “使用 Azure Maps 进行身份验证 ”和“ 安全”部分 。
请求参数
下表列出了必应地图 计算路线 请求参数和 Azure Maps 等效项：
| 必应地图请求参数 | 必应地图请求参数别名 | Azure Maps 请求参数 | Azure Maps 中必需 | Azure Maps 数据类型 | DESCRIPTION |
|---|---|---|---|---|---|
| avoid | avoid | 假 | 字符串 | 下面是必应地图计算路线 API 到 Azure Maps 路线方向 API 的 avoid 等效项（如果支持）： tolls：tollRoads ferry：ferries borderCrossings：borderCrossings minimizeDrivingSideTurn：不支持 minimizeAgainstDrivingSideTurn：不支持 minimizeUTurn：不支持 minimizeTolls：不支持 highways：limitedAccessHighways minimizeHighways：不支持 |
|
| dateTime | dt | departAt | 假 | 字符串 | Azure Maps 路线方向 API 还支持用于指定所需到达日期和时间的 arriveAt 参数。 它不能与 departAt 一起使用。 |
| distanceBeforeFirstTurn | dbft | 不支持 | 不支持 | 不支持 | |
| distanceUnit | du | 不需要 | 不需要 | 不需要 | 在 Azure Maps 路线方向 API 中，距离单位为米。 |
| heading | hd | heading | 假 | 整数 | |
| itineraryGroups | ig | 不支持 | 不支持 | ||
| maxSolutions | maxSolns | maxRouteCount | 假 | 整数 | |
| optimize | optmz | 优化路线 | 假 | 字符串 | 下面是必应地图计算路线 API 到 Azure Maps 路线方向 API 的 optimizeRoute 等效项： time：fastestWithoutTraffic timeWithTraffic：fastestWithTraffic Azure Maps 路线方向 API 还支持通过将最短路线指定为“optimizeRoute”输入值来按距离优化路线以返回最短路线。 |
| optimizeWaypoints | optWp | optimizeWaypointOrder | 假 | boolean | |
| routeAttributes | ra | routeOutputOptions | 假 | 字符串 | 下面是必应地图计算路线 API 到 Azure Maps 路线方向 API 的 routeOutputOptions 等效项： routePath：routePath regionTravelSummary：regionTravelSummary Azure Maps 路线方向 API 支持更多值，例如行程和路线。 有关详细信息，请参阅 RouteOutputOption。 |
| routePathOutput | rpo | routeOutputOptions | 假 | 字符串 | Azure Maps 路线方向 API 支持通过在请求中传递 routeOutputOptions=routePath 来返回路线路径几何图形的坐标。 |
| 时间类型 | tt | 不支持 | 不支持 | 不支持 | Azure Maps 路线 API 不支持公共交通路线。 |
| tolerances | tl | 不支持 | 不支持 | 不支持 | |
| travelMode | travelMode | 假 | 字符串 | 下面是必应地图计算路线 API 到 Azure Maps 路线方向 API 的 travelMode 等效项： Driving：driving Walking：walking 交通：不支持 Azure Maps 支持用于卡车路线的额外 travelMode “卡车”。 |
|
| viaWaypoint.n | vwp.n | 功能 InputWaypointFeaturesItem[] |
True | GeoJSON Point | waypoint 和 viaWaypoint 被指定为特征，这是必需的参数。 但是，只有 waypoint 是一种必需的点类型，并且请求无需通过 viaWaypoint 即可发出。 在必应地图计算路线 API 中，viaWaypoint 可以是点、地标或地址，而在 Azure Maps 路线方向 API 中，它必须是一个点。 若要将地标或地址转换为某个点，可以使用 Azure Maps 获取地理编码 API。 必应地图计算路线 API 要求 viaWaypoints 采用纬度/经度格式，而 Azure Maps 要求它们采用经度/纬度格式，如 GeoJSON 格式定义。 |
| waypoint.n | wp.n | features InputWaypointFeaturesItem[] | True | GeoJSON Point | 在必应地图计算路线 API 中，路点可以是点、地标或地址，而在 Azure Maps 路线方向 API 中，它必须是一个点。 若要将地标或地址转换为某个点，可以使用 Azure Maps 获取地理编码 API。 必应地图计算路线 API 要求 waypoints 采用纬度/经度格式，而 Azure Maps 要求它们采用经度/纬度格式，如 GeoJSON 格式定义。 |
有关 Azure Maps 路线方向 API 请求参数的详细信息，请参阅 URI 参数。
请求示例
必应地图 计算路线 API 请求：
http://dev.virtualearth.net/REST/V1/Routes/driving?wp.0=47.610173,-122.204171&wp.1=47.612440,-122.204171key={Your-Bing-Maps-Key}
Azure Maps 路线方向 API POST 请求：
https://atlas.microsoft.com/route/directions?api-version=2025-01-01&subscription-key={Your-Azure-Maps-Subscription-key}
包含在请求正文中：
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [
-122.204171,
47.610173
],
"type": "Point"
},
"properties": {
"pointIndex": 0,
"pointType": "waypoint"
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-122.204171,
47.612440
],
"type": "Point"
},
"properties": {
"pointIndex": 1,
"pointType": "Waypoint"
}
}
]
}
响应字段
下表列出了运行必应地图“计算路线”请求和 Azure Maps 等效请求时，HTTP 响应中可能出现的字段：
| 必应地图字段 | Azure Maps 字段 | DESCRIPTION |
|---|---|---|
| actualStart | 点特征对象 | type=“waypoint”且 inputIndex = 0 的点特征对象定义可路由的起始位置。 |
| actualEnd | 点特征对象 | type=“waypoint”且 inputIndex = last 的点特征对象定义可进行路线规划的结束位置。 |
| alternateVias | alternativeRoutes | Bing Maps 的 alternateVias 标识出单独的路线。 在 Azure Maps 中，备用路由在 alternativeRoutes 下作为新功能集合返回。 |
| compassDegrees | compassDegrees | |
| compassDirection | compassDirection | |
| description | 不支持 | |
| details | properties | 功能对象的属性包含有关操纵的信息。 |
| distanceUnit | 不适用 | Azure Maps 路线方向 API 以米为单位返回距离。 |
| durationUnit | 不适用 | Azure Maps 路线方向 API 返回持续时间（以秒为单位）。 |
| endPathIndices | range | Azure Maps 将路线的特定路段所覆盖的起始索引和结束索引作为范围返回。 |
| endWaypoint | 不支持 | 在 Azure Maps 路线指引 API 的响应中，终点可以通过 type="waypoint" 和 inputIndex=最后一个索引来推导出。 |
| formattedText | formattedText | |
| hints | 不支持 | |
| hintType | 不支持 | |
| 图标类型 | 不支持 | 必应地图计算路线 API 指定表示用户应用程序中旅行模式的图标类型。 例如，如果驾驶路线具有部分渡轮路线，则图标可用于直观地识别路线中的不同旅行模式。 Azure Maps 计算路线 API 不支持 iconType，但旅行模式可以从响应中的 travelMode 属性派生。 |
| instruction | Instruction | |
| isRealTimeTransit | 不支持 | |
| isVia | viaWaypoint | 在 Azure Maps Route Directions API 响应中，via waypoint 将作为“type”:“ViaWaypoint”返回 |
| locationCodes | 不支持 | |
| locationIdentifier | 不支持 | |
| maneuverPoint | maneuverPoint | 在 Azure Maps 中，type=maneuverPoint 表示需要操作的点对象。 在必应地图中，计算路线 API 的 maneuverPoint 采用纬度/经度格式，而在 Azure Maps 中，它采用经度/纬度格式，以 GeoJSON 格式定义。 |
| maneuverType | maneuverType | |
| mode | 不支持 | |
| names | names | |
| realTimeTransitDelay | 不支持 | |
| 道路类型 | 道路类型 | |
| routePathIndex | routePathPoint | |
| routeSubLegs | subLegs | |
| sideOfStreet | sideOfStreet | |
| startPathIndices | range | Azure Maps 将路线的特定路段所覆盖的起始索引和结束索引作为范围返回。 |
| startWaypoint | 不支持 | 在 Azure Maps 路线方向 API 响应中，startWaypoint 可以从 type=“waypoint”派生，inputIndex = 第一个索引 |
| towardsRoadName | towardsRoadName | |
| 交通拥堵 | 交通拥堵 | |
| trafficDataUsed | trafficDataUsed | |
| travelDistance | 距离（米） | |
| travelDuration | 持续时间（秒） | |
| travelDurationTraffic | durationTrafficInSeconds | |
| travelMode | travelMode |
有关 Azure Maps 路线方向 API 响应字段的详细信息，请参阅 “定义”。
响应示例
以下 JSON 示例显示了执行必应地图 计算路线 请求时 HTTP 响应正文中返回的内容：
{
"authenticationResultCode": "ValidCredentials",
"brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png",
"copyright": "Copyright © 2024 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
"resourceSets": [
{
"estimatedTotal": 1,
"resources": [
{
"__type": "Route:http://schemas.microsoft.com/search/local/ws/rest/v1",
"bbox": [
47.610173,
-122.204193,
47.611674,
-122.203012
],
"id": "v70,h570425388,i0,a0,cen-US,dAAAAAAAAAAA1,y0,s1,m1,o1,t4,wfPMbJhrOR0Cq8j0jEY1ewA2~AF2UnBAtW6QAAADgAQAAAAAA0~MTAybmQgQXZlIE5F0~~~~~~~~v12,wkWEVb2TOR0Cq8j0jEY1ewA2~AF2UnBAdU6QAAADgAQAAgD8A0~MTAzcmQgQXZlIE5F0~~~~~~~~v12,k1,pZ3NpLXBvaQ2-VHJ1ZQ2,pWC1GRC1GTElHSFQ1-Z3NpLXBvaQ2,p-,p-,p-",
"distanceUnit": "Kilometer",
"durationUnit": "Second",
"routeLegs": [
{
"actualEnd": {
"type": "Point",
"coordinates": [
47.611674,
-122.203084
]
},
"actualStart": {
"type": "Point",
"coordinates": [
47.610173,
-122.20414
]
},
"alternateVias": [],
"description": "102nd Ave NE, NE 1st St",
"endTime": "/Date(1713305954789-0700)/",
"itineraryItems": [
{
"compassDirection": "north",
"details": [
{
"compassDegrees": 356,
"endPathIndices": [
1
],
"maneuverType": "DepartStart",
"mode": "Driving",
"names": [
"102nd Ave NE"
],
"roadType": "Street",
"startPathIndices": [
0
]
}
],
"exit": "",
"iconType": "Auto",
"instruction": {
"formattedText": null,
"maneuverType": "DepartStart",
"text": "Head north on 102nd Ave NE toward NE 1st Pl"
},
"isRealTimeTransit": false,
"maneuverPoint": {
"type": "Point",
"coordinates": [
47.610173,
-122.20414
]
},
"realTimeTransitDelay": 0,
"sideOfStreet": "Unknown",
"tollZone": "",
"towardsRoadName": "NE 1st Pl",
"transitTerminus": "",
"travelDistance": 0.114,
"travelDuration": 36,
"travelMode": "Driving"
},
{
"compassDirection": "east",
"details": [
{
"compassDegrees": 89,
"endPathIndices": [
4
],
"maneuverType": "TurnRight",
"mode": "Driving",
"names": [
"NE 1st St"
],
"roadType": "Street",
"startPathIndices": [
1
]
}
],
"exit": "",
"iconType": "Auto",
"instruction": {
"formattedText": null,
"maneuverType": "TurnRight",
"text": "Turn right onto NE 1st St"
},
"isRealTimeTransit": false,
"maneuverPoint": {
"type": "Point",
"coordinates": [
47.611206,
-122.204193
]
},
"realTimeTransitDelay": 0,
"sideOfStreet": "Unknown",
"tollZone": "",
"transitTerminus": "",
"travelDistance": 0.106,
"travelDuration": 22,
"travelMode": "Driving"
},
{
"compassDirection": "northwest",
"details": [
{
"compassDegrees": 302,
"endPathIndices": [
5
],
"maneuverType": "TurnLeft",
"mode": "Driving",
"names": [
"103rd Ave NE"
],
"roadType": "Street",
"startPathIndices": [
4
]
}
],
"exit": "",
"iconType": "Auto",
"instruction": {
"formattedText": null,
"maneuverType": "TurnLeft",
"text": "Turn left onto 103rd Ave NE"
},
"isRealTimeTransit": false,
"maneuverPoint": {
"type": "Point",
"coordinates": [
47.611629,
-122.203012
]
},
"realTimeTransitDelay": 0,
"sideOfStreet": "Unknown",
"tollZone": "",
"transitTerminus": "",
"travelDistance": 0.007,
"travelDuration": 21,
"travelMode": "Driving"
},
{
"compassDirection": "northwest",
"details": [
{
"compassDegrees": 302,
"endPathIndices": [
5
],
"maneuverType": "ArriveFinish",
"mode": "Driving",
"names": [
"103rd Ave NE"
],
"roadType": "Street",
"startPathIndices": [
5
]
}
],
"exit": "",
"hints": [
{
"hintType": "PreviousIntersection",
"text": "The last intersection before your destination is NE 2nd St"
}
],
"iconType": "Auto",
"instruction": {
"formattedText": null,
"maneuverType": "ArriveFinish",
"text": "Arrive at 103rd Ave NE"
},
"isRealTimeTransit": false,
"maneuverPoint": {
"type": "Point",
"coordinates": [
47.611674,
-122.203084
]
},
"realTimeTransitDelay": 0,
"sideOfStreet": "Unknown",
"tollZone": "",
"transitTerminus": "",
"travelDistance": 0,
"travelDuration": 0,
"travelMode": "Driving"
}
],
"routeRegion": "WWMX",
"routeSubLegs": [
{
"endWaypoint": {
"type": "Point",
"coordinates": [
47.611674,
-122.203084
],
"description": "103rd Ave NE",
"isVia": false,
"locationIdentifier": "0|93|148|156|16|29|83|164|0|0|0|224|1|0|0|128|63|0|47.611674,-122.203084",
"routePathIndex": 5
},
"startWaypoint": {
"type": "Point",
"coordinates": [
47.610173,
-122.20414
],
"description": "102nd Ave NE",
"isVia": false,
"locationIdentifier": "0|93|148|156|16|45|91|164|0|0|0|224|1|0|0|0|0|0|47.610173,-122.20414",
"routePathIndex": 0
},
"travelDistance": 0.227,
"travelDuration": 80
}
],
"startTime": "/Date(1713305874789-0700)/",
"travelDistance": 0.227,
"travelDuration": 80,
"travelMode": "Driving"
}
],
"trafficCongestion": "None",
"trafficDataUsed": "None",
"travelDistance": 0.227,
"travelDuration": 80,
"travelDurationTraffic": 71,
"travelMode": "Driving"
}
]
}
],
"statusCode": 200,
"statusDescription": "OK",
"traceId": "47969a89fd7bc08f1a922bf92f4a7541|MWH0032B15|0.0.0.0|MWH0031C9B, Leg0-MWH0031C8C"
}
以下 JSON 示例显示了执行 Azure Maps“获取地图图块”请求时，HTTP 响应正文中返回的内容：
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.20414,
47.610173
]
},
"properties": {
"durationInSeconds": 36,
"distanceInMeters": 114.00,
"exitIdentifier": "",
"signs": [],
"instruction": {
"formattedText": "<Action>Head</Action> <CmpsDir>north</CmpsDir> on <RoadName>102nd Ave NE</RoadName> toward <Toward>NE 1st Pl</Toward>",
"maneuverType": "DepartStart",
"text": "Head north on 102nd Ave NE toward NE 1st Pl"
},
"towardsRoadName": "NE 1st Pl",
"routePathPoint": {
"legIndex": 0,
"pointIndex": 0
},
"compassDirection": "north",
"travelMode": "driving",
"steps": [
{
"maneuverType": "DepartStart",
"routePathRange": {
"legIndex": 0,
"range": [
0,
1
]
},
"names": [
"102nd Ave NE"
],
"compassDegrees": 356.00,
"roadType": "Street"
}
],
"type": "ManeuverPoint"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.204193,
47.611206
]
},
"properties": {
"durationInSeconds": 22,
"distanceInMeters": 106.00,
"exitIdentifier": "",
"signs": [],
"instruction": {
"formattedText": "<Action>Turn</Action> <TurnDir>right</TurnDir> onto <RoadName>NE 1st St</RoadName>",
"maneuverType": "TurnRight",
"text": "Turn right onto NE 1st St"
},
"routePathPoint": {
"legIndex": 0,
"pointIndex": 1
},
"compassDirection": "east",
"travelMode": "driving",
"steps": [
{
"maneuverType": "TurnRight",
"routePathRange": {
"legIndex": 0,
"range": [
1,
4
]
},
"names": [
"NE 1st St"
],
"compassDegrees": 89.00,
"roadType": "Street"
}
],
"type": "ManeuverPoint"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.203012,
47.611629
]
},
"properties": {
"durationInSeconds": 21,
"distanceInMeters": 7.00,
"exitIdentifier": "",
"signs": [],
"instruction": {
"formattedText": "<Action>Turn</Action> <TurnDir>left</TurnDir> onto <RoadName>103rd Ave NE</RoadName>",
"maneuverType": "TurnLeft",
"text": "Turn left onto 103rd Ave NE"
},
"routePathPoint": {
"legIndex": 0,
"pointIndex": 4
},
"compassDirection": "northwest",
"travelMode": "driving",
"steps": [
{
"maneuverType": "TurnLeft",
"routePathRange": {
"legIndex": 0,
"range": [
4,
5
]
},
"names": [
"103rd Ave NE"
],
"compassDegrees": 302.00,
"roadType": "Street"
}
],
"type": "ManeuverPoint"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.203084,
47.611674
]
},
"properties": {
"durationInSeconds": 0,
"distanceInMeters": 0.00,
"exitIdentifier": "",
"signs": [],
"instruction": {
"formattedText": "<Action>Arrive</Action> at <WaypointName>103rd Ave NE</WaypointName>",
"maneuverType": "ArriveFinish",
"text": "Arrive at 103rd Ave NE"
},
"routePathPoint": {
"legIndex": 0,
"pointIndex": 5
},
"compassDirection": "northwest",
"travelMode": "driving",
"steps": [
{
"maneuverType": "ArriveFinish",
"routePathRange": {
"legIndex": 0,
"range": [
5,
5
]
},
"names": [
"103rd Ave NE"
],
"compassDegrees": 302.00,
"roadType": "Street"
}
],
"type": "ManeuverPoint"
}
},
{
"type": "Feature",
"geometry": {
"type": "MultiLineString",
"coordinates": []
},
"properties": {
"resourceId": "v70,h570425388,i0,a0,cen-US,dAAAAAAAAAAA1,y0,s1,m1,o1,t0,wfPMbJhrOR0Cq8j0jEY1ewA2~~~~~~~~~~v12,wkWEVb2TOR0Cq8j0jEY1ewA2~~~~~~~~~~v12,k1,qatt:1",
"trafficCongestion": "Mild",
"trafficDataUsed": "None",
"distanceInMeters": 227.00,
"durationInSeconds": 80,
"departureTime": "2024-04-16T22:22:27+00:00",
"arrivalTime": "2024-04-16T22:23:47+00:00",
"type": "RoutePath",
"legs": []
}
}
]
}
事务用法
与必应地图计算路线 API 类似，Azure 地图路由方向 API 为每个 API 请求记录一个计费事务。 有关 Azure Maps 事务的详细信息，请参阅了解 Azure Maps 事务。
其他信息
- Post Directions Batch：用于在单个同步请求中向路由方向 API 发送一批查询。
支持