Route - Get Route Matrix
Use para obtener una matriz de rutas que muestre el tiempo de viaje y la distancia de todos los pares posibles en una lista de orígenes y destinos.
La Get Route Matrix
API es una solicitud HTTP GET
que calcula el tiempo de viaje y la distancia de todos los pares posibles en una lista de orígenes y destinos. A diferencia de Get Route Directions API, que proporciona instrucciones de ruta detalladas, esta API se centra en la eficiencia al proporcionarle el costo (tiempo de viaje y distancia) del enrutamiento desde cada origen a cada destino. Para más información, consulte Procedimientos recomendados para el servicio Route de Azure Maps.
Para cada origen determinado, el servicio calcula el costo del enrutamiento desde ese origen a cada destino determinado. El conjunto de orígenes y el conjunto de destinos se pueden considerar como los encabezados de columna y fila de una tabla y cada celda de la tabla contiene los costos de enrutamiento desde el origen hasta el destino de esa celda. Por ejemplo, supongamos que una empresa de entrega de alimentos tiene 20 conductores y necesitan encontrar el conductor más cercano para recoger la entrega del restaurante. Para resolver este caso de uso, pueden llamar a Matrix Route API.
Para cada ruta, se devuelven los tiempos de viaje y las distancias. Puede usar los costos calculados para determinar qué rutas detalladas se van a calcular mediante Route Directions API.
El tamaño máximo de una matriz para la solicitud asincrónica es 700 y para la solicitud de sincronización es 100 (el número de orígenes multiplicado por el número de destinos).
Enviar solicitud de matriz de ruta sincrónica
Si el escenario requiere solicitudes sincrónicas y el tamaño máximo de la matriz es menor o igual que 100, es posible que desee realizar una solicitud sincrónica. El tamaño máximo de una matriz para esta API es 100 (el número de orígenes multiplicado por el número de destinos). Teniendo en cuenta esa restricción, algunos ejemplos de posibles dimensiones de matriz son: 10x10, 6x8, 9x8 (no es necesario que sea cuadrado).
GET https://atlas.microsoft.com/route/matrix/sync/json?api-version=1.0&subscription-key={subscription-key}
Enviar solicitud de matriz de ruta asincrónica
La API asincrónica es adecuada para procesar grandes volúmenes de solicitudes de enrutamiento relativamente complejas. Cuando se realiza una solicitud mediante una solicitud asincrónica, el servicio devuelve de forma predeterminada un código de respuesta 202 a lo largo de una dirección URL de redireccionamiento en el campo Ubicación del encabezado de respuesta. Esta dirección URL se debe comprobar periódicamente hasta que los datos de respuesta o la información de error estén disponibles. Si waitForResults
el parámetro de la solicitud se establece en true, el usuario obtendrá una respuesta 200 si la solicitud ha finalizado en menos de 120 segundos.
El tamaño máximo de una matriz para esta API es 700 (el número de orígenes multiplicado por el número de destinos). Teniendo en cuenta esa restricción, los ejemplos de posibles dimensiones de matriz son: 50x10, 10x10, 28x25. 10x70 (no es necesario que sea cuadrado).
Las respuestas asincrónicas se almacenan durante 14 días. La dirección URL de redireccionamiento devuelve una respuesta 404 si se usa después del período de expiración.
GET https://atlas.microsoft.com/route/matrix/json?api-version=1.0&subscription-key={subscription-key}
Esta es una secuencia típica de operaciones asincrónicas:
El cliente envía una solicitud GET de Route Matrix a Azure Maps
El servidor responderá con uno de los siguientes elementos:
HTTP
202 Accepted
: se ha aceptado la solicitud de matriz de rutas.HTTP
Error
: se produjo un error al procesar la solicitud route matrix. Puede ser una solicitud incorrecta 400 o cualquier otro código de estado de error.Si la solicitud de ruta de matriz se aceptó correctamente, el encabezado Location de la respuesta contiene la dirección URL para descargar los resultados de la solicitud. Este URI de estado es similar al siguiente:
GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}
- El cliente emite una solicitud GET en la dirección URL de descarga obtenida en el paso 3 para descargar los resultados
Descargar resultados de sincronización
Al realizar una solicitud GET para Route Matrix Sync API, el servicio devuelve el código de respuesta 200 para una solicitud correcta y una matriz de respuesta. El cuerpo de la respuesta contendrá los datos y no habrá posibilidad de recuperar los resultados más adelante.
Descargar resultados asincrónicos
Cuando una solicitud emite una 202 Accepted
respuesta, la solicitud se procesa mediante nuestra canalización asincrónica. Se le proporcionará una dirección URL para comprobar el progreso de la solicitud asincrónica en el encabezado de ubicación de la respuesta. Este URI de estado es similar al siguiente:
GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}
La dirección URL proporcionada por el encabezado de ubicación devolverá las siguientes respuestas cuando se emita una GET
solicitud.
HTTP
202 Accepted
: se aceptó la solicitud matrix, pero todavía se está procesando. Inténtelo de nuevo en algún momento.
HTTP
200 OK
: solicitud de matriz procesada correctamente. El cuerpo de la respuesta contiene todos los resultados.
GET https://atlas.microsoft.com/route/matrix/{format}?api-version=1.0
Parámetros de identificador URI
Nombre | En | Requerido | Tipo | Description |
---|---|---|---|---|
format
|
path | True |
string |
Id. de matriz recibido después de que la solicitud de ruta de matriz se haya aceptado correctamente. |
api-version
|
query | True |
string |
Número de versión de la API de Azure Maps. |
Encabezado de la solicitud
Nombre | Requerido | Tipo | Description |
---|---|---|---|
x-ms-client-id |
string |
Especifica qué cuenta está pensada para su uso junto con el modelo de seguridad de Id. de Entra de Microsoft. Representa un identificador único para la cuenta de Azure Maps y se puede recuperar de la API de cuenta del plano de administración de Azure Maps. Para usar la seguridad de id. de Entra de Microsoft en Azure Maps, consulte los siguientes artículos para obtener instrucciones. |
Respuestas
Nombre | Tipo | Description |
---|---|---|
200 OK |
Solicitud de matriz procesada correctamente. El cuerpo de la respuesta contiene todos los resultados. |
|
202 Accepted |
Solo se admite para la solicitud asincrónica. Solicitud aceptada: la solicitud se ha aceptado para su procesamiento. Use la dirección URL en el encabezado de ubicación para reintentar o acceder a los resultados. Encabezados Location: string |
|
Other Status Codes |
Se ha producido un error inesperado. |
Seguridad
AADToken
Estos son los flujos de Microsoft Entra OAuth 2.0 . Cuando se empareja con el control de acceso basado en rol de Azure , se puede usar para controlar el acceso a las API REST de Azure Maps. Los controles de acceso basados en roles de Azure se usan para designar el acceso a una o varias cuentas de recursos o subrecursos de Azure Maps. Se puede conceder acceso a cualquier usuario, grupo o entidad de servicio mediante un rol integrado o un rol personalizado compuesto por uno o varios permisos para las API REST de Azure Maps.
Para implementar escenarios, se recomienda ver los conceptos de autenticación. En resumen, esta definición de seguridad proporciona una solución para modelar aplicaciones a través de objetos capaces de controlar el acceso en determinadas API y ámbitos.
Notas
- Esta definición de seguridad requiere el uso del
x-ms-client-id
encabezado para indicar a qué recurso de Azure Maps solicita acceso la aplicación. Esto se puede adquirir desde la API de administración de Maps.
Authorization URL
es específico de la instancia de nube pública de Azure. Las nubes soberanas tienen direcciones URL de autorización únicas y configuraciones de id. de Microsoft Entra.
* El control de acceso basado en rol de Azure se configura desde el plano de administración de Azure mediante Azure Portal, PowerShell, la CLI, los SDK de Azure o las API REST.
* El uso del SDK web de Azure Maps permite la configuración basada en la configuración de una aplicación para varios casos de uso.
- Para obtener más información sobre la plataforma de identidad de Microsoft, consulte Introducción a la plataforma de identidad de Microsoft.
Tipo:
oauth2
Flujo:
implicit
Dirección URL de autorización:
https://login.microsoftonline.com/common/oauth2/authorize
Ámbitos
Nombre | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Se trata de una clave compartida que se aprovisiona al crear una cuenta de Azure Maps en Azure Portal o mediante PowerShell, la CLI, los SDK de Azure o la API REST.
Con esta clave, cualquier aplicación puede acceder a todas las API REST. En otras palabras, esta clave se puede usar como clave maestra en la cuenta en la que se emiten.
En el caso de las aplicaciones expuestas públicamente, nuestra recomendación es usar el enfoque de aplicaciones cliente confidenciales para acceder a las API REST de Azure Maps para que la clave se pueda almacenar de forma segura.
Tipo:
apiKey
En:
query
SAS Token
Se trata de un token de firma de acceso compartido que se crea a partir de la operación List SAS en el recurso de Azure Maps a través de Azure Portal, PowerShell, CLI, SDK de Azure o API REST.
Con este token, cualquier aplicación está autorizada para acceder a los controles de acceso basado en rol de Azure y el control específico a la expiración, la tasa y las regiones de uso para el token determinado. En otras palabras, el token de SAS se puede usar para permitir que las aplicaciones controlen el acceso de forma más segura que la clave compartida.
En el caso de las aplicaciones expuestas públicamente, nuestra recomendación es configurar una lista específica de orígenes permitidos en el recurso de la cuenta de asignación para limitar la representación del abuso y renovar periódicamente el token de SAS.
Tipo:
apiKey
En:
header
Ejemplos
Successfully retrieve the status for a route matrix request
Solicitud de ejemplo
GET https://atlas.microsoft.com/route/matrix/11111111-2222-3333-4444-555555555555?api-version=1.0
Respuesta de muestra
{
"formatVersion": "0.0.1",
"matrix": [
[
{
"statusCode": 200,
"response": {
"routeSummary": {
"lengthInMeters": 495,
"travelTimeInSeconds": 134,
"trafficDelayInSeconds": 0,
"departureTime": "2018-07-27T22:55:29+00:00",
"arrivalTime": "2018-07-27T22:57:43+00:00"
}
}
},
{
"statusCode": 200,
"response": {
"routeSummary": {
"lengthInMeters": 647651,
"travelTimeInSeconds": 26835,
"trafficDelayInSeconds": 489,
"departureTime": "2018-07-27T22:55:29+00:00",
"arrivalTime": "2018-07-28T06:22:44+00:00"
}
}
}
],
[
{
"statusCode": 200,
"response": {
"routeSummary": {
"lengthInMeters": 338,
"travelTimeInSeconds": 104,
"trafficDelayInSeconds": 0,
"departureTime": "2018-07-27T22:55:29+00:00",
"arrivalTime": "2018-07-27T22:57:13+00:00"
}
}
},
{
"statusCode": 200,
"response": {
"routeSummary": {
"lengthInMeters": 647494,
"travelTimeInSeconds": 26763,
"trafficDelayInSeconds": 469,
"departureTime": "2018-07-27T22:55:29+00:00",
"arrivalTime": "2018-07-28T06:21:32+00:00"
}
}
}
]
],
"summary": {
"successfulRoutes": 4,
"totalRoutes": 4
}
}
Definiciones
Nombre | Description |
---|---|
Error |
Información adicional sobre el error de administración de recursos. |
Error |
Detalle del error. |
Error |
Respuesta de error |
Route |
Objeto de resumen para la sección de ruta. |
Route |
Objeto de resultado de matriz |
Route |
Este objeto se devuelve desde una llamada a Route Matrix correcta. Por ejemplo, si se proporcionan 2 orígenes y 3 destinos, habrá 2 matrices con 3 elementos en cada uno. El contenido de cada elemento depende de las opciones proporcionadas en la consulta. |
Route |
Objeto response de la celda actual de la matriz de entrada. |
Route |
Summary (objeto) |
ErrorAdditionalInfo
Información adicional sobre el error de administración de recursos.
Nombre | Tipo | Description |
---|---|---|
info |
object |
Información adicional. |
type |
string |
Tipo de información adicional. |
ErrorDetail
Detalle del error.
Nombre | Tipo | Description |
---|---|---|
additionalInfo |
Información adicional del error. |
|
code |
string |
Código de error. |
details |
Los detalles del error. |
|
message |
string |
El mensaje de error. |
target |
string |
Destino del error. |
ErrorResponse
Respuesta de error
Nombre | Tipo | Description |
---|---|---|
error |
Objeto de error. |
RouteLegSummary
Objeto de resumen para la sección de ruta.
Nombre | Tipo | Description |
---|---|---|
arrivalTime |
string |
Hora estimada de llegada para la ruta o pierna. La hora es UTC. |
batteryConsumptionInkWh |
number |
Consumo estimado de energía eléctrica en horas de kilowatt (kWh) mediante el modelo de consumo eléctrico. Incluido si vehicleEngineType se establece en electric y constantSpeedConsumptionInkWhPerHundredkm se especifica. El valor de batteryConsumptionInkWh incluye la energía eléctrica recuperada y, por tanto, puede ser negativo (lo que indica la ganancia de energía). Si se especifican maxChargeInkWh y currentChargeInkWh, la recuperación se limitará para garantizar que el nivel de carga de la batería nunca supere maxChargeInkWh. Si no se especifican maxChargeInkWh ni currentChargeInkWh, se asume la recuperación sin restricciones en el cálculo de consumo. |
departureTime |
string |
Hora estimada de salida para la ruta o la pierna. La hora es UTC. |
fuelConsumptionInLiters |
number |
Consumo estimado de combustible en litros con el modelo de consumo de combustión. Incluido si vehicleEngineType se establece en combustión y se especifica constantSpeedConsumptionInLitersPerHundredkm. El valor no será negativo. |
historicTrafficTravelTimeInSeconds |
integer |
Tiempo estimado de viaje calculado mediante datos de tráfico histórico dependientes del tiempo. Solo se incluye si compute TravelTimeFor = todo se usa en la consulta. |
lengthInMeters |
integer |
Length In Meters (propiedad) |
liveTrafficIncidentsTravelTimeInSeconds |
integer |
Tiempo de viaje estimado calculado mediante datos de velocidad en tiempo real. Solo se incluye si compute TravelTimeFor = todo se usa en la consulta. |
noTrafficTravelTimeInSeconds |
integer |
Tiempo estimado de viaje calculado como si no haya retrasos en la ruta debido a condiciones de tráfico (por ejemplo, congestión). Solo se incluye si compute TravelTimeFor = todo se usa en la consulta. |
trafficDelayInSeconds |
integer |
Retraso estimado en segundos causado por los incidentes en tiempo real según la información de tráfico. En el caso de las rutas planeadas con la hora de salida en el futuro, los retrasos siempre son 0. Para devolver tiempos de desplazamiento adicionales con diferentes tipos de información de tráfico, es necesario agregar el parámetro compute TravelTimeFor=all. |
travelTimeInSeconds |
integer |
Tiempo de viaje estimado en segundos propiedad que incluye el retraso debido al tráfico en tiempo real. Tenga en cuenta que incluso cuando traffic=false travelTimeInSeconds todavía incluye el retraso debido al tráfico. Si DepartAt está en el futuro, el tiempo de viaje se calcula mediante datos de tráfico histórico dependientes del tiempo. |
RouteMatrix
Objeto de resultado de matriz
Nombre | Tipo | Description |
---|---|---|
response |
Objeto response de la celda actual de la matriz de entrada. |
|
statusCode |
integer |
Propiedad StatusCode de la celda actual de la matriz de entrada. |
RouteMatrixResult
Este objeto se devuelve desde una llamada a Route Matrix correcta. Por ejemplo, si se proporcionan 2 orígenes y 3 destinos, habrá 2 matrices con 3 elementos en cada uno. El contenido de cada elemento depende de las opciones proporcionadas en la consulta.
Nombre | Tipo | Description |
---|---|---|
formatVersion |
string |
Format Version (propiedad) |
matrix |
Resultados como una matriz dimensional 2 de resúmenes de ruta. |
|
summary |
Summary (objeto) |
RouteMatrixResultResponse
Objeto response de la celda actual de la matriz de entrada.
Nombre | Tipo | Description |
---|---|---|
routeSummary |
Objeto de resumen para la sección de ruta. |
RouteMatrixSummary
Summary (objeto)
Nombre | Tipo | Description |
---|---|---|
successfulRoutes |
integer |
Número de rutas correctas en la respuesta. |
totalRoutes |
integer |
Número total de rutas solicitadas. Número de celdas de la matriz de entrada. |