Route - Get Route Matrix

Referencia

Service:: Maps

API Version:: 1.0

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 obtener más información, consulte Procedimientos recomendados para Azure Maps servicio Route.

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 matriz de rutas para 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 Microsoft Entra ID. 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 Microsoft Entra ID seguridad en Azure Maps consulte los siguientes artículos para obtener instrucciones.

Respuestas

Nombre	Tipo	Description
200 OK	RouteMatrixResult	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. Headers Location: string
Other Status Codes	ErrorResponse	Se ha producido un error inesperado.

Nombre

Tipo

Description

200 OK

RouteMatrixResult

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.

Headers

Location: string

Other Status Codes

ErrorResponse

Se ha producido un error inesperado.

Seguridad

AADToken

Estos son los Microsoft Entra flujos de OAuth 2.0. Cuando se empareja con el control de acceso basado en rol de Azure, se puede usar para controlar el acceso a Azure Maps API REST. Los controles de acceso basados en roles de Azure se usan para designar el acceso a una o varias Azure Maps cuenta de recursos o subrecursos. Se puede conceder acceso a cualquier usuario, grupo o entidad de servicio a través de un rol integrado o un rol personalizado compuesto por uno o varios permisos para Azure Maps API REST.

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 Azure Maps la aplicación solicita acceso. 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 Microsoft Entra ID. * El control de acceso basado en rol de Azure se configura desde el plano de administración de Azure a través de Azure Portal, PowerShell, CLI, SDK de Azure o 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 Plataforma de identidad de Microsoft, consulte introducción a Plataforma de identidad de Microsoft.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Nombre	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Se trata de una clave compartida que se aprovisiona al Create una cuenta de Azure Maps en el 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 Azure Maps API REST para que la clave se pueda almacenar de forma segura.

Type: apiKey
In: query

SAS Token

Se crea un token de firma de acceso compartido a partir de la operación List SAS en el recurso de Azure Maps a través del plano de administración de Azure 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.

Type: apiKey
In: header

Ejemplos

Successfully retrieve the status for a route matrix request

Sample Request

HTTP

GET https://atlas.microsoft.com/route/matrix/11111111-2222-3333-4444-555555555555?api-version=1.0

Sample Response

Status code:: 200

{
  "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
  }
}

Status code:: 202

Definiciones

Nombre	Description
ErrorAdditionalInfo	Información adicional sobre el error de administración de recursos.
ErrorDetail	Detalle del error.
ErrorResponse	Respuesta de error
RouteLegSummary	Objeto de resumen para la sección de ruta.
RouteMatrix	Objeto de resultado de matriz
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.
RouteMatrixResultResponse	Objeto response de la celda actual de la matriz de entrada.
RouteMatrixSummary	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	ErrorAdditionalInfo[]	Información adicional del error.
code	string	Código de error.
details	ErrorDetail[]	Los detalles del error.
message	string	El mensaje de error.
target	string	Destino del error.

ErrorResponse

Respuesta de error

Nombre	Tipo	Description
error	ErrorDetail	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	RouteMatrixResultResponse	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	RouteMatrix[]	Resultados como una matriz dimensional 2 de resúmenes de ruta.
summary	RouteMatrixSummary	Summary (objeto)

RouteMatrixResultResponse

Objeto response de la celda actual de la matriz de entrada.

Nombre	Tipo	Description
routeSummary	RouteLegSummary	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.

Share via

Route - Get Route Matrix

Enviar solicitud de matriz de ruta sincrónica

Enviar solicitud de matriz de ruta asincrónica

Descargar resultados de sincronización

Descargar resultados asincrónicos

Parámetros de identificador URI

Encabezado de la solicitud

Respuestas

Seguridad

AADToken

Notas

Scopes

subscription-key

SAS Token

Ejemplos

Successfully retrieve the status for a route matrix request

Sample Request

Sample Response

Definiciones

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Recursos adicionales