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

Route - Post Route Matrix Async

参考

服务:: Maps

API 版本:: 2025-01-01

Route Matrix Async API 是一个 HTTP POST 请求，它允许使用异步（async）请求计算一组由源位置和目标位置定义的路由摘要矩阵。对于每个给定源，服务将计算从该源路由到每个给定目标的成本。可以将源集和目标集视为表的列和行标题，表中每个单元格都包含从源路由到该单元格的目标的成本。路线矩阵可以计算为驾驶、步行和卡车路线。

路线矩阵用于多种不同类型的应用程序，最常用于解决旅行推销员问题（TSP）和车辆路线问题（VRP）。对于矩阵中的每个出发点对，将返回行程时间和距离。可以使用计算成本来确定使用路线方向 API 计算哪些详细路由。

异步请求矩阵的最大大小 50000（原点数乘以目标数）。

提交异步路由矩阵请求

异步 API 适用于处理大量相对复杂的路由请求。使用异步请求发出请求时，默认情况下，服务会在响应标头的 operation-Location 字段中返回 202 响应代码，其中包含 Azure Maps 地理终结点“{geography}.atlas.microsoft.com”。在状态为“成功”之前，应定期检查此 URL。

此 API 的矩阵的最大大小为 50000（原点数乘以目标数）。考虑到该约束，可能的矩阵维度的示例包括：500x100、100x100、280x170。 100x50 （不需要正方形）。

异步响应的存储时间为 24 小时。重定向 URL 返回 404 响应（如果在到期期限后使用）。

POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01&subscription-key={subscription-key}

下面是一系列典型的异步操作：

客户端将路由矩阵 POST 请求发送到 Azure Maps
服务器将使用以下项之一进行响应：

HTTP 202 Accepted - 已接受路由矩阵请求。

HTTP Error - 处理路由矩阵请求时出错。这可能是 400 错误请求或任何其他错误状态代码。
如果成功接受矩阵路由请求，则响应中的 operation-location 标头包含获取请求状态的 URL。此状态 URI 如下所示：

  GET https://atlas.microsoft.com/route/operations/{id}?api-version=2025-01-01?subscription-key={subscription-key}

客户端对步骤 3 中获取的 resultUrl 发出 GET 请求以获取结果

  GET https://atlas.microsoft.com/route/operations/{id}/result?api-version=2025-01-01?subscription-key={subscription-key}

API 限制

矩阵的异步处理最适合需要大量路由计算的大型矩阵。以下限制适用于异步请求。如果下表中没有任何行与请求的参数匹配，则请求不满足要求，并且不会处理。

最大矩阵大小	最大源数	最大目标数	其他限制
2500	1000	1000	所有原点和目的地都应包含在轴对齐的 400 km x 400 公里边界框中。否则，某些矩阵单元格将解析为OUT_OF_REGION。
50,000	10,000	10,000	- `departAt` 或 `arriveAt` 必须是任何。 - `traffic` 必须是历史的。 - `optimizeRoute` 必须最快。 - `travelMode` 必须是驾驶或卡车。 - 不能显式使用其他参数。

POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01

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"

名称	必需	类型	说明
features	True	InputRouteMatrixFeaturesItem[]	作为输入矩阵的 GeoJSON MultiPoint 功能传递的一组源点和目标点。有关 GeoJSON 格式的详细信息，请参阅 RFC 7946。
type	True	FeatureTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。
arriveAt		string	到达目标点的日期和时间，格式为 `dateTime`定义的值。如果未指定时区偏移量，则假定 UTC。 `arriveAt` 参数不能与 `departAt`结合使用。 `arriveAt` 还支持 `any` 值，该值针对时间上下文无关的用例进行定制。 `traffic=live` 参数值不能与 `any`一起使用。默认值：如果未指定 `any`，则为 `arriveAt`。示例：“arriveAt”：“2024-12-01T09：30：00.000-07：00”
avoid		RouteMatrixAvoidEnum[]	指定在确定路由时路由计算应遵循的限制。避免在请求中支持多个值，并且仅支持驾驶和卡车 travelMode。
departAt		string	从原点出发的日期和时间，格式为 `dateTime`定义的值。如果未指定时区偏移量，则假定 UTC。 `departAt` 参数不能与 `arriveAt`结合使用。 `departAt` 还支持： `any` 为与时间上下文无关的用例定制的值。 `traffic=live` 参数值不能与 `any`一起使用。 `now` 值，将出发时间设置为每个单个单元格的处理时间。处理时间可以是提交与其完成之间的任何时间。此模式最适合与 traffic=live 一起使用。默认值：如果未指定 `any`，则为 `departAt`。示例： “departAt”： “2024-12-01T09：30：00.000-07：00”
optimizeRoute		RouteMatrixAsyncOptimizeRouteEnum	指定要用于优化路由的参数。如果未定义，则默认值为“最快”，返回路线以尽量减少行程时间。示例：“optimizeRoute”：“shortest”
traffic		RouteMatrixTrafficEnum	指定如何考虑流量用于计算路由。默认值：`historical`
travelMode		RouteMatrixTravelModeEnum	指定计算矩阵时要考虑的旅行配置文件。如果未指定，则默认值为“driving”。示例：“travelMode”：“driving”
vehicleSpec		RouteMatrixVehicleSpec	指定计算路线矩阵时要考虑的车辆高度、重量、最大速度、货物类型等车辆属性。这有助于避免低桥通关、道路限制、难以右转，以根据车辆规格提供优化的路线。车辆属性在 vehicleSpec 属性中指定。

响应

名称	类型	说明
202 Accepted		已接受标头 Operation-Location: string
Other Status Codes	MapsErrorResponse	发生意外错误。标头 x-ms-error-code: string

名称

类型

说明

202 Accepted

已接受

标头

Operation-Location: string

Other Status Codes

MapsErrorResponse

发生意外错误。

标头

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

示例

Submit an asynchronous request for matrix

示例请求

HTTP

POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            9.15049,
            45.458545
          ],
          [
            11.050541,
            45.403337
          ]
        ]
      },
      "properties": {
        "pointType": "origins"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            11.499931,
            48.149853
          ],
          [
            14.538226,
            50.033688
          ]
        ]
      },
      "properties": {
        "pointType": "destinations"
      }
    }
  ],
  "departAt": "2022-12-19T16:39:57+01:00",
  "optimizeRoute": "fastest",
  "traffic": "historical",
  "travelMode": "truck",
  "avoid": [
    "unpavedRoads"
  ]
}

示例响应

状态代码:: 202

Operation-Location: https://atlas.microsoft.com/route/operations/bc3f9365-3ee0-4564-aa27-825016325557?api-version=2025-01-01

定义

名称	说明
AdrTunnelRestrictionCodeEnum	ADR 隧道限制代码。 ADR是一项欧洲关于道路危险品国际运输的协议。 ADR 隧道限制代码用于确定是否允许车辆通过隧道，并限制危险品的运输。
FeaturesItemTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 Feature。有关详细信息，请参阅 RFC 7946。
FeatureTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。
GeoJsonMultiPoint	有效的 `GeoJSON MultiPoint` 几何图形类型。有关详细信息，请参阅 RFC 7946。
InputRouteMatrixFeaturesItem	指定 `GeoJSON` MultiPoint 功能对象的输入源点和目标点和其他属性。有关详细信息，请参阅 RFC 7946。
InputRouteMatrixProperties	指定输入矩阵的属性对象。
MapsErrorDetail	错误详细信息。
MapsErrorResponse	Azure Maps API 的常见错误响应，以返回失败操作的错误详细信息。
MapsInnerError	包含与当前对象有关错误的更具体信息的对象。
RouteMatrixAsyncOptimizeRouteEnum	指定要用于优化路由的参数。如果未定义，则默认值为“最快”，返回路线以尽量减少行程时间。示例：“optimizeRoute”：“shortest”
RouteMatrixAsyncRequest	用于获取路线矩阵，其中显示了出发地和目的地列表中所有可能对的行程时间和距离。 `GeoJSON` 功能对象和其他属性。有关详细信息，请参阅 RFC 7946。
RouteMatrixAvoidEnum	指定在确定路由时路由计算应遵循的限制。避免在请求中支持多个值，并且仅支持驾驶和卡车 travelMode。
RouteMatrixTrafficEnum	指定如何考虑流量用于计算路由。默认值：`historical`
RouteMatrixTravelModeEnum	指定计算矩阵时要考虑的旅行配置文件。如果未指定，则默认值为“driving”。示例：“travelMode”：“driving”
RouteMatrixTypeEnum	指定输入矩阵的源 MultiPoint 类型和目标 MultiPoint 类型。
RouteMatrixVehicleSpec	指定计算路线矩阵时要考虑的车辆高度、重量、最大速度、货物类型等车辆属性。这有助于避免低桥通关、道路限制、难以右转，以根据车辆规格提供优化的路线。车辆属性在 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` 对象类型。

GeoJsonMultiPoint

Object

有效的 GeoJSON MultiPoint 几何图形类型。有关详细信息，请参阅 RFC 7946。

名称	类型	说明
coordinates	number[] (double)	`GeoJson MultiPoint` 几何图形的坐标。
type	string: MultiPoint	指定 `GeoJSON` 类型。必须是九种有效的 GeoJSON 对象类型之一 - Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

InputRouteMatrixFeaturesItem

Object

指定 GeoJSON MultiPoint 功能对象的输入源点和目标点和其他属性。有关详细信息，请参阅 RFC 7946。

名称	类型	说明
geometry	GeoJsonMultiPoint	有效的 `GeoJSON MultiPoint` 几何图形类型。有关详细信息，请参阅 RFC 7946。
properties	InputRouteMatrixProperties	MultiPoint 特征属性对象，该对象指定输入矩阵的源特征和目标特征。
type	FeaturesItemTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 Feature。有关详细信息，请参阅 RFC 7946。

InputRouteMatrixProperties

Object

指定输入矩阵的属性对象。

名称	类型	说明
pointType	RouteMatrixTypeEnum	指定输入矩阵的源 MultiPoint 类型和目标 MultiPoint 类型。

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	包含与当前对象有关错误的更具体信息的对象。

RouteMatrixAsyncOptimizeRouteEnum

枚举

指定要用于优化路由的参数。如果未定义，则默认值为“最快”，返回路线以尽量减少行程时间。

示例：“optimizeRoute”：“shortest”

值	说明
fastest	查找按行程时间优化路线的最快路线。
shortest	查找按行程距离优化路线的最短路线。

RouteMatrixAsyncRequest

Object

用于获取路线矩阵，其中显示了出发地和目的地列表中所有可能对的行程时间和距离。 GeoJSON 功能对象和其他属性。有关详细信息，请参阅 RFC 7946。

名称	类型	默认值	说明
arriveAt	string		到达目标点的日期和时间，格式为 `dateTime`定义的值。如果未指定时区偏移量，则假定 UTC。 `arriveAt` 参数不能与 `departAt`结合使用。 `arriveAt` 还支持 `any` 值，该值针对时间上下文无关的用例进行定制。 `traffic=live` 参数值不能与 `any`一起使用。默认值：如果未指定 `any`，则为 `arriveAt`。示例：“arriveAt”：“2024-12-01T09：30：00.000-07：00”
avoid	RouteMatrixAvoidEnum[]		指定在确定路由时路由计算应遵循的限制。避免在请求中支持多个值，并且仅支持驾驶和卡车 travelMode。
departAt	string		从原点出发的日期和时间，格式为 `dateTime`定义的值。如果未指定时区偏移量，则假定 UTC。 `departAt` 参数不能与 `arriveAt`结合使用。 `departAt` 还支持： `any` 为与时间上下文无关的用例定制的值。 `traffic=live` 参数值不能与 `any`一起使用。 `now` 值，将出发时间设置为每个单个单元格的处理时间。处理时间可以是提交与其完成之间的任何时间。此模式最适合与 traffic=live 一起使用。默认值：如果未指定 `any`，则为 `departAt`。示例： “departAt”： “2024-12-01T09：30：00.000-07：00”
features	InputRouteMatrixFeaturesItem[]		作为输入矩阵的 GeoJSON MultiPoint 功能传递的一组源点和目标点。有关 GeoJSON 格式的详细信息，请参阅 RFC 7946。
optimizeRoute	RouteMatrixAsyncOptimizeRouteEnum	fastest	指定要用于优化路由的参数。如果未定义，则默认值为“最快”，返回路线以尽量减少行程时间。示例：“optimizeRoute”：“shortest”
traffic	RouteMatrixTrafficEnum	historical	指定如何考虑流量用于计算路由。默认值：`historical`
travelMode	RouteMatrixTravelModeEnum	driving	指定计算矩阵时要考虑的旅行配置文件。如果未指定，则默认值为“driving”。示例：“travelMode”：“driving”
type	FeatureTypeEnum		指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。
vehicleSpec	RouteMatrixVehicleSpec		指定计算路线矩阵时要考虑的车辆高度、重量、最大速度、货物类型等车辆属性。这有助于避免低桥通关、道路限制、难以右转，以根据车辆规格提供优化的路线。车辆属性在 vehicleSpec 属性中指定。

RouteMatrixAvoidEnum

枚举

指定在确定路由时路由计算应遵循的限制。避免在请求中支持多个值，并且仅支持驾驶和卡车 travelMode。

值	说明
tollRoads	避免在路线中使用收费公路。
unpavedRoads	避免路线中未修补的道路。

RouteMatrixTrafficEnum

枚举

指定如何考虑流量用于计算路由。

默认值：historical

值说明

historical

值	说明
historical	路线计算考虑历史行程时间和长期关闭。旅行时段期间的交通堵塞和短期关闭不会影响路线或旅行时间。
live	除了历史旅行时间外，路线计算还考虑在旅行时段内交通堵塞和短期和长期关闭。 `Note`：`traffic=live` 不能与 `arriveAt=any` 和 `departAt=any` 结合使用

路线计算考虑历史行程时间和长期关闭。旅行时段期间的交通堵塞和短期关闭不会影响路线或旅行时间。

live

除了历史旅行时间外，路线计算还考虑在旅行时段内交通堵塞和短期和长期关闭。

Note：traffic=live 不能与 arriveAt=any 和 departAt=any 结合使用

RouteMatrixTravelModeEnum

枚举

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

示例：“travelMode”：“driving”

值	说明
driving	适用于汽车的路由配置文件用于路线矩阵计算。
truck	适用于卡车等商用车辆的路线配置文件用于路线矩阵计算。
walking	返回的路线针对行人进行了优化，包括人行道的使用。

RouteMatrixTypeEnum

枚举

指定输入矩阵的源 MultiPoint 类型和目标 MultiPoint 类型。

值	说明
destinations	在输入矩阵中定义目标位置的 MultiPoint 功能。
origins	在输入矩阵中定义源位置的 MultiPoint 功能。

RouteMatrixVehicleSpec

Object

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

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

VehicleLoadTypeEnum

枚举

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

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