Route - Get Route Matrix

Referencia

Servicio:: Maps

Versión de la API:: 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 API de Get Route Matrix es una solicitud de GET HTTP que calcula el tiempo de desplazamiento y la distancia de todos los pares posibles en una lista de orígenes y destinos. A diferencia de la API Get Route Directions , que proporciona instrucciones de ruta detalladas, esta API se centra en la eficacia 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 de para el servicio route de Azure Maps.

Para cada origen determinado, el servicio calcula el costo de 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 comida 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 una solicitud asincrónica es 700 y para la solicitud de sincronización se 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 debe comprobarse periódicamente hasta que los datos de respuesta o la información de error estén disponibles. Si waitForResults parámetro de la solicitud se establece en true, el usuario obtendrá una respuesta de 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 24 horas. 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 Route Matrix.

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

Cuando se realiza una solicitud GET para Route Matrix Sync API, el servicio devuelve 200 código de respuesta para una solicitud correcta y una matriz de respuestas. 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 respuesta 202 Accepted, 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 solicitud de GET.

HTTP 202 Accepted: se aceptó la solicitud de matriz, 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 aceptó 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 Microsoft Entra. 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 del identificador de Entra de Microsoft en Azure Maps, consulte los siguientes artículos de 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. Encabezados Location: string
Other Status Codes	ErrorResponse	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.

Encabezados

Location: string

Other Status Codes

ErrorResponse

Error inesperado.

Seguridad

AADToken

Estos son los flujos de Microsoft Entra OAuth 2.0. Cuando se empareja con acceso basado en rol de Azure control, 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 a través de un rol integrado o de un rol personalizado compuesto por uno o varios permisos para las API REST de Azure Maps.

Para implementar escenarios, se recomienda ver 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 encabezado x-ms-client-id 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.

El 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 a través de Azure Portal, PowerShell, la CLI, los SDK de Azure o las API REST. * El uso de 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 Creación de 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.

Para las aplicaciones expuestas públicamente, nuestra recomendación es usar las aplicaciones cliente confidenciales enfoque 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 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 tiene autorización para acceder a los controles de acceso basados en rol de Azure y el control específico a la expiración, la tasa y las regiones de uso para el token determinado. Es decir, el token de SAS se puede usar para permitir que las aplicaciones controle 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 cuenta de mapa de limitar el abuso de representación 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

HTTP

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

Respuesta de muestra

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 de 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[]	Detalles del error.
message	string	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 la pierna. La hora está en UTC.
batteryConsumptionInkWh	number	Consumo estimado de energía eléctrica en kilowatt hours (kWh) utilizando el modelo de consumo eléctrico. Se incluye 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 obtención de energía). Si se especifican maxChargeInkWh y currentChargeInkWh, se limitará la recuperación para asegurarse de 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 del consumo.
departureTime	string	Hora estimada de salida para la ruta o la pierna. La hora está en UTC.
fuelConsumptionInLiters	number	Consumo estimado de combustible en litros utilizando el modelo de consumo de combustión. Se incluye si vehicleEngineType se establece en de 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 computeAdvisorTimeFor = todo se usa en la consulta.
lengthInMeters	integer	Length In Meters (propiedad)
liveTrafficIncidentsTravelTimeInSeconds	integer	Tiempo estimado de viaje calculado mediante datos de velocidad en tiempo real. Solo se incluye si computeAdvisorTimeFor = todo se usa en la consulta.
noTrafficTravelTimeInSeconds	integer	Tiempo estimado de viaje calculado como si no hay retrasos en la ruta debido a condiciones de tráfico (por ejemplo, congestión). Solo se incluye si computeAdvisorTimeFor = 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 mediante diferentes tipos de información de tráfico, es necesario agregar el parámetro computeAdvisorTimeFor=all.
travelTimeInSeconds	integer	Tiempo estimado de viaje 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 con 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 para la celda actual de la matriz de entrada.

RouteMatrixResult

Este objeto se devuelve de 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	Propiedad Format Version
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.

Compartir a través de

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

Ámbitos

subscription-key

SAS Token

Ejemplos

Successfully retrieve the status for a route matrix request

Solicitud de ejemplo

Respuesta de muestra

Definiciones

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Recursos adicionales