你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Weather - Get Weather Along Route
使用 获取位置精确、最新预测,包括沿途的天气危险评估和通知。
API Get Weather Along Route
是一个 HTTP GET
请求,它返回超本地 (一公里或更短) 、最新天气、天气危害评估和路线上的通知(描述为一系列路点)。
这包括影响路点或路线的天气危害列表,并且每个航点的聚合危险指数可用于根据对驾驶员的安全程度绘制路线的每个部分。 提交航点时,建议保持在 120 分钟或之后不久可行驶的距离内或接近。 数据每五分钟更新一次。
该服务补充了Azure Maps路由服务,该服务允许你首先请求源和目的地之间的路由,并将其用作沿路线天气终结点的输入。
此外,该服务还支持为遇到天气危险强度增加的航点生成天气通知的方案。 例如,如果预计车辆在到达航点时开始下大雨,则会为该航点生成大雨天气通知,允许最终产品在司机到达该路点之前显示大雨通知。 何时显示航点通知的触发器可以基于,例如,基于 地理围栏或可选择的距离到航点的距离。
该 API 涵盖除格陵兰岛和南极洲以上纬度以外的地球所有区域。
GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query={query}
GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query={query}&language={language}
URI 参数
名称 | 在 | 必需 | 类型 | 说明 |
---|---|---|---|---|
format
|
path | True |
响应的所需格式。 仅支持 |
|
api-version
|
query | True |
string |
Azure Maps API 的版本号。 |
query
|
query | True |
string |
计算路线所依据的坐标,用冒号 (:) 分隔,并按时间顺序输入。 至少需要两个航点。 单个 API 调用最多可以包含 60 个路点。 航点指示位置、ETA 和可选标题:纬度、经度、ETA、标题,其中
建议保持在 120 分钟或之后不久可行驶的距离内或接近。 这样就可以为行程提供更准确的评估,并防止在航点之间捕获孤立的事件。 可以而且应该沿路线更新信息 (特别是对于超过2小时的行程,) 不断拉动新的航点向前移动,同时确保降水类型和强度等内容的预报信息准确,因为风暴随时间的发展和消散。 |
language
|
query |
string |
应返回搜索结果的语言。 应该是受支持的 IETF 语言标记之一,不区分大小写。 当指定语言的数据不适用于特定字段时,将使用默认语言。 有关详细信息,请参阅 支持的语言 。 |
请求头
名称 | 必需 | 类型 | 说明 |
---|---|---|---|
x-ms-client-id |
string |
指定要与Microsoft Entra ID安全模型一起使用的帐户。 它表示Azure Maps帐户的唯一 ID,可以从Azure Maps管理平面帐户 API 检索。 若要在 Azure Maps 中使用Microsoft Entra ID安全性,请参阅以下文章以获取指导。 |
响应
名称 | 类型 | 说明 |
---|---|---|
200 OK |
确定 |
|
Other Status Codes |
发生了意外错误。 |
安全性
AADToken
这些是 OAuth 2.0 流Microsoft Entra。 与 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 标识平台概述。
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
名称 | 说明 |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
这是在Azure 门户或使用 PowerShell、CLI、Azure SDK 或 REST API 创建Azure Maps帐户时预配的共享密钥。
使用此密钥,任何应用程序都可以访问所有 REST API。 换句话说,此密钥可以用作颁发它们的帐户中的主密钥。
对于公开的应用程序,我们建议使用机密客户端应用程序方法来访问Azure Maps REST API,以便安全地存储密钥。
Type:
apiKey
In:
query
SAS Token
这是一个共享访问签名令牌,通过 Azure 管理平面通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 在Azure Maps资源上列出 SAS 操作创建。
使用此令牌,任何应用程序都有权使用 Azure 基于角色的访问控制进行访问,并精细控制特定令牌的过期、速率和区域 () 。 换句话说,SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。
对于公开的应用程序,我们建议在 映射帐户资源 上配置允许的来源的特定列表,以限制呈现滥用,并定期续订 SAS 令牌。
Type:
apiKey
In:
header
示例
Successfully retrieve detailed weather casts along a route described as a sequence of waypoints
Sample Request
GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query=38.907,-77.037,0:38.907,-77.009,10:38.926,-76.928,20:39.033,-76.852,30:39.168,-76.732,40:39.269,-76.634,50:39.287,-76.612,60
Sample Response
{
"summary": {
"iconCode": 35,
"hazards": {
"maxHazardIndex": 0
}
},
"waypoints": [
{
"iconCode": 38,
"shortPhrase": "Mostly cloudy",
"isDayTime": false,
"cloudCover": 70,
"temperature": {
"value": 3.4,
"unit": "C",
"unitType": 17
},
"wind": {
"direction": {
"degrees": 142
},
"speed": {
"value": 2,
"unit": "km/h",
"unitType": 7
}
},
"windGust": {
"speed": {
"value": 3,
"unit": "km/h",
"unitType": 7
}
},
"precipitation": {
"dbz": 0,
"type": "SNOW"
},
"lightningCount": 0,
"sunGlare": {
"calculatedVehicleHeading": 90,
"glareIndex": 0
},
"hazards": {
"maxHazardIndex": 0
},
"notifications": []
},
{
"iconCode": 38,
"shortPhrase": "Mostly cloudy",
"isDayTime": false,
"cloudCover": 65,
"temperature": {
"value": 3.4,
"unit": "C",
"unitType": 17
},
"wind": {
"direction": {
"degrees": 166
},
"speed": {
"value": 1,
"unit": "km/h",
"unitType": 7
}
},
"windGust": {
"speed": {
"value": 2,
"unit": "km/h",
"unitType": 7
}
},
"precipitation": {
"dbz": 0,
"type": "SNOW"
},
"lightningCount": 0,
"sunGlare": {
"calculatedVehicleHeading": 77,
"glareIndex": 0
},
"hazards": {
"maxHazardIndex": 0
},
"notifications": []
},
{
"iconCode": 35,
"shortPhrase": "Partly cloudy",
"isDayTime": false,
"cloudCover": 43,
"temperature": {
"value": 3.2,
"unit": "C",
"unitType": 17
},
"wind": {
"direction": {
"degrees": 163
},
"speed": {
"value": 2,
"unit": "km/h",
"unitType": 7
}
},
"windGust": {
"speed": {
"value": 2,
"unit": "km/h",
"unitType": 7
}
},
"precipitation": {
"dbz": 0,
"type": "SNOW"
},
"lightningCount": 0,
"sunGlare": {
"calculatedVehicleHeading": 44,
"glareIndex": 0
},
"hazards": {
"maxHazardIndex": 0
},
"notifications": []
},
{
"iconCode": 35,
"shortPhrase": "Partly cloudy",
"isDayTime": false,
"cloudCover": 34,
"temperature": {
"value": 1.6,
"unit": "C",
"unitType": 17
},
"wind": {
"direction": {
"degrees": 189
},
"speed": {
"value": 2,
"unit": "km/h",
"unitType": 7
}
},
"windGust": {
"speed": {
"value": 4,
"unit": "km/h",
"unitType": 7
}
},
"precipitation": {
"dbz": 0,
"type": "SNOW"
},
"lightningCount": 0,
"sunGlare": {
"calculatedVehicleHeading": 32,
"glareIndex": 0
},
"hazards": {
"maxHazardIndex": 0
},
"notifications": []
},
{
"iconCode": 38,
"shortPhrase": "Mostly cloudy",
"isDayTime": false,
"cloudCover": 54,
"temperature": {
"value": 0.5,
"unit": "C",
"unitType": 17
},
"wind": {
"direction": {
"degrees": 202
},
"speed": {
"value": 4,
"unit": "km/h",
"unitType": 7
}
},
"windGust": {
"speed": {
"value": 5,
"unit": "km/h",
"unitType": 7
}
},
"precipitation": {
"dbz": 0,
"type": "SNOW"
},
"lightningCount": 0,
"sunGlare": {
"calculatedVehicleHeading": 36,
"glareIndex": 0
},
"hazards": {
"maxHazardIndex": 0
},
"notifications": []
},
{
"iconCode": 35,
"shortPhrase": "Partly cloudy",
"isDayTime": false,
"cloudCover": 46,
"temperature": {
"value": 2.4,
"unit": "C",
"unitType": 17
},
"wind": {
"direction": {
"degrees": 222
},
"speed": {
"value": 4,
"unit": "km/h",
"unitType": 7
}
},
"windGust": {
"speed": {
"value": 5,
"unit": "km/h",
"unitType": 7
}
},
"precipitation": {
"dbz": 0,
"type": "SNOW"
},
"lightningCount": 0,
"sunGlare": {
"calculatedVehicleHeading": 38,
"glareIndex": 0
},
"hazards": {
"maxHazardIndex": 0
},
"notifications": []
},
{
"iconCode": 35,
"shortPhrase": "Partly cloudy",
"isDayTime": false,
"cloudCover": 39,
"temperature": {
"value": 2.3,
"unit": "C",
"unitType": 17
},
"wind": {
"direction": {
"degrees": 231
},
"speed": {
"value": 4,
"unit": "km/h",
"unitType": 7
}
},
"windGust": {
"speed": {
"value": 5,
"unit": "km/h",
"unitType": 7
}
},
"precipitation": {
"dbz": 0,
"type": "SNOW"
},
"lightningCount": 0,
"sunGlare": {
"calculatedVehicleHeading": 43,
"glareIndex": 0
},
"hazards": {
"maxHazardIndex": 0
},
"notifications": []
}
]
}
定义
名称 | 说明 |
---|---|
Error |
资源管理错误附加信息。 |
Error |
错误详细信息。 |
Error |
错误响应 |
Hazard |
|
Hazard |
严重性/危险指数。
|
Icon |
表示显示 的图像的 |
Json |
响应的所需格式。 仅支持 |
Sun |
一个分级,指示太阳对司机的遮蔽程度。 |
Unit |
与显示的单位类型关联的数值 ID 值。 可用于单元翻译。 有关详细信息,请参阅 Azure Maps 中的天气服务。 |
Weather |
沿途天气的降水预报。 |
Weather |
此对象是从成功的“沿路线天气”返回的。 |
Weather |
沿途天气的简短摘要。 |
Weather |
影响旅行的天气危害的说明。 |
Weather |
|
Weather |
与天气相关的给定单位的特定值。 |
Weather |
|
Wind |
返回的风力详细信息,包括速度和方向。 |
Wind |
风向 |
ErrorAdditionalInfo
资源管理错误附加信息。
名称 | 类型 | 说明 |
---|---|---|
info |
object |
其他信息。 |
type |
string |
其他信息类型。 |
ErrorDetail
错误详细信息。
名称 | 类型 | 说明 |
---|---|---|
additionalInfo |
错误附加信息。 |
|
code |
string |
错误代码。 |
details |
错误详细信息。 |
|
message |
string |
错误消息。 |
target |
string |
错误目标。 |
ErrorResponse
错误响应
名称 | 类型 | 说明 |
---|---|---|
error |
错误对象。 |
HazardDetail
名称 | 类型 | 说明 |
---|---|---|
hazardCode |
string |
每种类型的危险 (不可显示) 的唯一标识符:LightRain、 ModerateRain、HeavyRain、LightMix、ModerateMix、HeavyMix、LightSnow、ModerateSnow、HeavySnow、LightIce、ModerateIce、HeavyIce、Hail、LargeHail、SunGlareHigh、Lightning、SevereLightning、WindModerate、WindHigh、WindExtreme、FloodWarning、FlashFloodWarning、TornadoWarning、TsunamiWarning、SevereThunderstormWarning。 |
hazardIndex |
严重性/危险指数。
|
|
shortPhrase |
string |
描述预测条件和降水强度/类型的可显示短语。 |
HazardIndex
严重性/危险指数。
0
- 无危险。1
- 了解情况,请注意。2
- 注意,做好准备。3
- 采取措施。4
- 生命危险,紧急。
名称 | 类型 | 说明 |
---|---|---|
0 |
Integer |
|
1 |
Integer |
|
2 |
Integer |
|
3 |
Integer |
|
4 |
Integer |
IconCode
表示显示 的图像的 iconPhrase
数值。 有关详细信息,请参阅 Azure Maps 中的天气服务。
名称 | 类型 | 说明 |
---|---|---|
1 |
Integer |
|
10 |
Integer |
|
11 |
Integer |
|
12 |
Integer |
|
13 |
Integer |
|
14 |
Integer |
|
15 |
Integer |
|
16 |
Integer |
|
17 |
Integer |
|
18 |
Integer |
|
19 |
Integer |
|
2 |
Integer |
|
20 |
Integer |
|
21 |
Integer |
|
22 |
Integer |
|
23 |
Integer |
|
24 |
Integer |
|
25 |
Integer |
|
26 |
Integer |
|
27 |
Integer |
|
28 |
Integer |
|
29 |
Integer |
|
3 |
Integer |
|
30 |
Integer |
|
31 |
Integer |
|
32 |
Integer |
|
33 |
Integer |
|
34 |
Integer |
|
35 |
Integer |
|
36 |
Integer |
|
37 |
Integer |
|
38 |
Integer |
|
39 |
Integer |
|
4 |
Integer |
|
40 |
Integer |
|
41 |
Integer |
|
42 |
Integer |
|
43 |
Integer |
|
44 |
Integer |
|
5 |
Integer |
|
6 |
Integer |
|
7 |
Integer |
|
8 |
Integer |
|
9 |
Integer |
JsonFormat
响应的所需格式。 仅支持 json
格式。
名称 | 类型 | 说明 |
---|---|---|
json |
string |
SunGlare
一个分级,指示太阳对司机的遮蔽程度。
名称 | 类型 | 说明 |
---|---|---|
calculatedVehicleHeading |
integer |
如果未为航点提供车辆航向值,则服务将根据相邻航点的位置(如果提供)计算航向。 |
glareIndex |
integer |
一个从 0 到 100 的索引,指示司机的太阳眩光强度。 值 50 及更高可被视为一些司机的危险,值 100 表示司机正直接驶入阳光下,大气条件清晰,使太阳的完全强度使驾驶员失明。 |
UnitType
与显示的单位类型关联的数值 ID 值。 可用于单元翻译。 有关详细信息,请参阅 Azure Maps 中的天气服务。
名称 | 类型 | 说明 |
---|---|---|
0 |
Integer |
|
1 |
Integer |
|
10 |
Integer |
|
11 |
Integer |
|
12 |
Integer |
|
13 |
Integer |
|
14 |
Integer |
|
15 |
Integer |
|
16 |
Integer |
|
17 |
Integer |
|
18 |
Integer |
|
19 |
Integer |
|
2 |
Integer |
|
20 |
Integer |
|
21 |
Integer |
|
22 |
Integer |
|
3 |
Integer |
|
31 |
Integer |
|
4 |
Integer |
|
5 |
Integer |
|
6 |
Integer |
|
7 |
Integer |
|
8 |
Integer |
|
9 |
Integer |
WeatherAlongRoutePrecipitation
沿途天气的降水预报。
名称 | 类型 | 说明 |
---|---|---|
dbz |
number |
预测的降水强度(dBZ)相对于 Z) (分贝,从 0.0 到 100.0。 |
type |
string |
降水类型。 如果应发生降水,则其类型为:“RAIN”、“HAIL”、“SNOW”、“ICE”或“MIX”。 |
WeatherAlongRouteResult
此对象是从成功的“沿路线天气”返回的。
名称 | 类型 | 说明 |
---|---|---|
summary |
沿途天气的简短摘要。 |
|
waypoints |
每个航点的数据以请求中指定的相同顺序返回。 |
WeatherAlongRouteSummary
沿途天气的简短摘要。
名称 | 类型 | 说明 |
---|---|---|
hazards |
影响旅行的天气危害的说明。 |
|
iconCode |
表示显示 的图像的 |
WeatherHazards
影响旅行的天气危害的说明。
名称 | 类型 | 说明 |
---|---|---|
hazardDetails |
影响旅行的天气危害的详细信息。 |
|
maxHazardIndex |
严重性/危险指数。
|
WeatherNotification
名称 | 类型 | 说明 |
---|---|---|
hazardCode |
string |
每种类型的危险 (不可显示) 的唯一标识符:LightRain、 ModerateRain、HeavyRain、LightMix、ModerateMix、HeavyMix、LightSnow、ModerateSnow、HeavySnow、LightIce、ModerateIce、HeavyIce、Hail、LargeHail、SunGlareHigh、Lightning、SevereLightning、WindModerate、WindHigh、WindExtreme、FloodWarning、FlashFloodWarning、TornadoWarning、TsunamiWarning、SevereThunderstormWarning。 |
hazardIndex |
严重性/危险指数。
|
|
shortPhrase |
string |
描述预测条件和降水强度/类型的可显示短语。 |
type |
string |
生成的一种通知,用于警告驾驶员危险开始或危险强度增加。 |
WeatherUnit
与天气相关的给定单位的特定值。
名称 | 类型 | 说明 |
---|---|---|
unit |
string |
返回值的单位类型。 |
unitType |
与显示的单位类型关联的数值 ID 值。 可用于单元翻译。 有关详细信息,请参阅 Azure Maps 中的天气服务。 |
|
value |
number |
舍入值。 |
WeatherWaypoint
名称 | 类型 | 说明 |
---|---|---|
cloudCover |
integer |
表示云覆盖率的百分比。 |
hazards |
影响旅行的天气危害的说明。 |
|
iconCode |
表示显示 的图像的 |
|
isDayTime |
boolean |
指示一天中的时间。 True 表示“day”,false 表示“night”。 |
lightningCount |
integer |
在开放范围内估计雷雨强度。 值为 0 表示没有雷雨;值 1 及更高表示有雷雨强度增加。 |
notifications |
天气危险通知列表。 |
|
precipitation |
沿途天气的降水预报。 |
|
shortPhrase |
string |
描述预测条件和降水强度/类型的可显示短语。 |
sunGlare |
一个分级,指示太阳对司机的遮蔽程度。 |
|
temperature |
与天气相关的给定单位的特定值。 |
|
wind |
返回的风力详细信息,包括速度和方向。 |
|
windGust |
返回的风力详细信息,包括速度和方向。 |
WindDetails
返回的风力详细信息,包括速度和方向。
名称 | 类型 | 说明 |
---|---|---|
direction |
风向 |
|
speed |
以指定单位为单位的风速。 |
WindDirection
风向
名称 | 类型 | 说明 |
---|---|---|
degrees |
integer |
方位角风向,从真正北端开始,沿顺时针方向继续。 北为0度,东为90度,南为180度,西为270度。 可能的值 0-359。 |
localizedDescription |
string |
指定语言的方向缩写。 |