Route - Post Route Matrix Async

La API de Route Matrix Async es una solicitud http POST que permite el cálculo de una matriz de resúmenes de ruta para un conjunto de rutas definidas por ubicaciones de origen y destino mediante una solicitud asincrónica (asincrónica). 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. Las matrices de ruta se pueden calcular para conducir, caminar y rutas de camión.

Las matrices de ruta se usan en varios tipos diferentes de aplicaciones, normalmente para resolver el problema del vendedor de viajes (TSP) y el problema de enrutamiento de vehículos (VRP). Para cada par de origen-destino de la matriz, se devuelve el tiempo de viaje y la distancia. 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 50000 (el número de orígenes multiplicado por el número de destinos).

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 en el campo operation-Location del encabezado de respuesta con el punto de conexión de geografía de Azure Maps '{geography}.atlas.microsoft.com. Esta dirección URL debe comprobarse periódicamente hasta que el estado sea Correcto.

El tamaño máximo de una matriz para esta API es 50000 (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: 500x100, 100x100, 280x170. 100x50 (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.

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

Esta es una secuencia típica de operaciones asincrónicas:

1. El cliente envía una solicitud POST de matriz de rutas a Azure Maps

2. 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.

3. Si la solicitud de ruta de matriz se aceptó correctamente, el encabezado operation-location de la respuesta contiene la dirección URL para obtener el estado de la solicitud. Este URI de estado es similar al siguiente:

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

4. El cliente emite una solicitud GET en el resultUrl obtenido en el paso 3 para obtener los resultados

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

Limitaciones de api

El procesamiento asincrónico de matriz es más adecuado para matrices más grandes que requieren cálculo de rutas pesadas. La siguiente limitación es aplicable a las solicitudes asincrónicas. Si ninguna de las filas de la tabla siguiente coincide con los parámetros de la solicitud, la solicitud no cumple los requisitos y no se procesará.

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

Parámetros de identificador URI

Encabezado de la solicitud

Media Types: "application/geo+json"

Cuerpo de la solicitud

Media Types: "application/geo+json"

Respuestas

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.

Tipo: oauth2
Flujo: implicit
Dirección URL de autorización: https://login.microsoftonline.com/common/oauth2/authorize

Ámbitos

subscription-key

Se trata de una clave compartida que se aprovisiona al crear una 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 esta clave, cualquier aplicación está autorizada para acceder a todas las API REST. En otras palabras, estos se pueden tratar actualmente como claves maestras para la cuenta para la que se emiten.

Para las aplicaciones expuestas públicamente, nuestra recomendación es usar el acceso de servidor a servidor de las API REST de Azure Maps donde esta clave se puede almacenar de forma segura.

Tipo: apiKey
En: header

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

Submit an asynchronous request for matrix

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

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

Definiciones

AdrTunnelRestrictionCodeEnum

Código de restricción del túnel ADR. ADR es un acuerdo europeo relativo al transporte internacional de mercancías peligrosas por carretera. El código de restricción del túnel ADR se utiliza para determinar si se permite que un vehículo pase a través de un túnel con restricciones sobre el transporte de mercancías peligrosas.

FeaturesItemTypeEnum

Especifica el tipo de GeoJSON. El único tipo de objeto admitido es Feature. Para obtener más información, vea RFC 7946.

FeatureTypeEnum

Especifica el tipo de GeoJSON. El único tipo de objeto admitido es FeatureCollection. Para obtener más información, vea RFC 7946.

GeoJsonMultiPoint

Un tipo de geometría GeoJSON MultiPoint válido. Consulte RFC 7946 para obtener más información.

InputRouteMatrixFeaturesItem

Especifica los puntos de origen y destino de entrada y propiedades adicionales para el objeto de característica de GeoJSON MultiPoint. Consulte RFC 7946 para obtener más información.

InputRouteMatrixProperties

Especifica el objeto properties de la matriz de entrada.

MapsErrorDetail

Detalle del error.

MapsErrorResponse

Respuesta de error común para las API de Azure Maps para devolver los detalles de error de las operaciones con errores.

MapsInnerError

Objeto que contiene información más específica que el objeto actual sobre el error.

RouteMatrixAsyncOptimizeRouteEnum

Especifica el parámetro que se va a usar para optimizar la ruta. Si no se define, el valor predeterminado es "más rápido" que devuelve la ruta para minimizar el tiempo de viaje.

Ejemplo: "optimizeRoute":"shortest"

RouteMatrixAsyncRequest

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 destino. GeoJSON objeto de característica y propiedades adicionales. Consulte RFC 7946 para obtener más información.

RouteMatrixAvoidEnum

Especifica las restricciones que debe respetar el cálculo de la ruta al determinar la ruta. Evite admitir varios valores en una solicitud y solo se admite para la conducción y el travelMode del camión.

RouteMatrixTrafficEnum

Especifica cómo se considera el tráfico para las rutas informáticas.

Valor predeterminado: historical

RouteMatrixTravelModeEnum

Especifica el perfil de viaje que se debe tener en cuenta al calcular la matriz. Si no se especifica, el valor predeterminado es "driving".

Ejemplo: "travelMode":"driving"

RouteMatrixTypeEnum

Especifica el tipo multipoint de origen y el tipo multipoint de destino para la matriz de entrada.

RouteMatrixVehicleSpec

Especifica los atributos del vehículo, como la altura del vehículo, el peso, la velocidad máxima, el tipo de carga, etc. que se deben tener en cuenta al calcular la matriz de rutas. Esto ayuda a evitar bajas distancias de puente, restricciones de carretera, giros difíciles a la derecha para proporcionar la ruta optimizada en función de las especificaciones del vehículo. Los atributos del vehículo se especifican dentro de la propiedad vehicleSpec.

VehicleLoadTypeEnum

Tipos de carga que se pueden clasificar como materiales peligrosos y restringidos de algunas carreteras. Los valores de vehicleLoadType disponibles son clases hazmat de EE. UU. de 1 a 9, además de clasificaciones genéricas para su uso en otros países. Los valores que comienzan con USHazmat son para el enrutamiento de EE. UU., mientras que otroshazmat deben usarse para todos los demás países. vehicleLoadType admite varios valores en una solicitud.