Route - Post Route Matrix Async

L'API Route Matrix Async è una richiesta http POST che consente il calcolo di una matrice di riepiloghi di route per un set di route definite dalle posizioni di origine e di destinazione usando una richiesta asincrona (asincrona). Per ogni origine specificata, il servizio calcola il costo del routing da tale origine a ogni destinazione specificata. Il gruppo di origini e il gruppo di destinazioni possono essere considerati come le intestazioni di colonna e di riga di una tabella e ogni cella della tabella contiene i costi di instradamento dall'origine alla destinazione corrispondente. Le matrici di itinerari possono essere calcolate per guidare, camminare e autocarri.

Le matrici di route vengono usate in diversi tipi di applicazioni, in genere per risolvere il problema TSP (Traveling Salesman Problem) e Il problema di routing dei veicoli . Per ogni coppia di destinazione di origine nella matrice, vengono restituiti il tempo di viaggio e la distanza. È possibile usare i costi calcolati per determinare quali route dettagliate calcolare usando l'API Indicazioni stradali.

La dimensione massima di una matrice per una richiesta asincrona è 50000 (il numero di origini moltiplicato per il numero di destinazioni).

Invia richiesta matrice di route asincrona

L'API asincrona è appropriata per l'elaborazione di grandi volumi di richieste di routing relativamente complesse. Quando effettui una richiesta usando una richiesta asincrona, di default il servizio restituisce un codice risposta 202 lungo un URL nel campo operation-Location dell'intestazione risposta con l'endpoint geografico Azure Maps '{geography}.atlas.microsoft.com. Questo URL deve essere controllato periodicamente fino a quando lo stato non è Succeeded.

La dimensione massima di una matrice per questa API è 50000 (il numero di origini moltiplicato per il numero di destinazioni). Tenendo presente tale vincolo, esempi di possibili dimensioni della matrice sono: 500x100, 100x100, 280x170. 100x50 (non deve essere quadrato).

Le risposte asincrone vengono archiviate per 24 ore. L'URL di reindirizzamento restituisce una risposta 404 se usata dopo il periodo di scadenza.

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

Ecco una sequenza tipica di operazioni asincrone:

1. Il client invia una richiesta POST di Route Matrix ad Azure Maps

2. Il server risponderà con uno dei seguenti elementi:

   Http 202 Accepted - Richiesta matrice di route accettata.

   HTTP Error: si è verificato un errore durante l'elaborazione della richiesta matrice di route. Potrebbe trattarsi di una richiesta non valida 400 o di qualsiasi altro codice di stato errore.

3. Se la richiesta di route matrice è stata accettata correttamente, l'intestazione operation-location nella risposta contiene l'URL per ottenere lo stato della richiesta. Questo URI di stato è simile al seguente:

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

4. Il client invia una richiesta GET sul risultatoUrl ottenuto nel passaggio 3 per ottenere i risultati

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

Limitazioni api

L'elaborazione asincrona della matrice è più adatta per matrici di dimensioni maggiori che richiedono calcoli di route pesanti. La limitazione seguente è applicabile alle richieste asincrone. Se nessuna delle righe nella tabella seguente corrisponde ai parametri della richiesta, la richiesta non soddisfa i requisiti e non verrà elaborata.

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

Parametri dell'URI

Intestazione della richiesta

Media Types: "application/geo+json"

Corpo della richiesta

Media Types: "application/geo+json"

Risposte

Sicurezza

AADToken

Questi sono i flussi Microsoft Entra OAuth 2.0. Quando abbinata al controllo Azure basato su ruolo può essere utilizzata per controllare l'accesso alle API REST di Azure Maps. I controlli di accesso basati su ruoli di Azure sono utilizzati per designare l'accesso a uno o più account o sottorisorse risorse di Azure Maps. Qualsiasi utente, gruppo o principale di servizio può ricevere l'accesso tramite un ruolo integrato o un ruolo personalizzato composto da uno o più permessi alle API REST di Azure Maps.

Per implementare scenari, è consigliabile visualizzare concetti di autenticazione. In sintesi, questa definizione di sicurezza offre una soluzione per la modellazione di applicazioni tramite oggetti in grado di controllare l'accesso su API e ambiti specifici.

Tipo: oauth2
Flow: implicit
URL di autorizzazione: https://login.microsoftonline.com/common/oauth2/authorize

Ambiti

subscription-key

Questa è una chiave condivisa che viene fornita quando si crea una risorsa Azure Maps tramite il piano di gestione Azure tramite Azure portale, PowerShell, CLI, Azure SDKs o API REST.

Con questa chiave, qualsiasi applicazione è autorizzata ad accedere a tutte le API REST. In altre parole, questi possono essere attualmente considerati chiavi master per l'account per cui vengono rilasciati.

Per applicazioni pubblicamente esposte, la nostra raccomandazione è di utilizzare l'accesso server-to-server alle API REST di Azure Maps, dove questa chiave può essere memorizzata in modo sicuro.

Tipo: apiKey
In: header

SAS Token

Questo è un token di firma di accesso condiviso creato dall'operazione List SAS sulla risorsa Azure Maps tramite il piano di gestione Azure tramite Azure portale, PowerShell, CLI, Azure SDKs o API REST.

Con questo token, qualsiasi applicazione è autorizzata ad accedere tramite Azure ai controlli di accesso basati su ruoli e a un controllo fine della scadenza, del tasso e delle regioni di utilizzo per il particolare token. In altre parole, il token di firma di accesso condiviso può essere usato per consentire alle applicazioni di controllare l'accesso in modo più protetto rispetto alla chiave condivisa.

Per le applicazioni esposte pubblicamente, è consigliabile configurare un elenco specifico di origini consentite nella risorsa account mappa per limitare l'abuso di rendering e rinnovare regolarmente il token di firma di accesso condiviso.

Tipo: apiKey
In: header

Esempio

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

Definizioni

AdrTunnelRestrictionCodeEnum

Codice di restrizione del tunnel ADR. L'ADR è un accordo europeo relativo al trasporto internazionale di merci pericolose per strada. Il codice di restrizione del tunnel ADR viene utilizzato per determinare se un veicolo può attraversare un tunnel con restrizioni sul trasporto di merci pericolose.

FeaturesItemTypeEnum

Specifica il tipo di GeoJSON. L'unico tipo di oggetto supportato è Feature. Per altre informazioni, vedere RFC 7946.

FeatureTypeEnum

Specifica il tipo di GeoJSON. L'unico tipo di oggetto supportato è FeatureCollection. Per altre informazioni, vedere RFC 7946.

GeoJsonMultiPoint

Tipo geometry GeoJSON MultiPoint valido. Per informazioni dettagliate, vedere RFC 7946.

InputRouteMatrixFeaturesItem

Specifica l'origine di input e i punti di destinazione e le proprietà aggiuntive per l'oggetto funzionalità multipoint GeoJSON. Per informazioni dettagliate, vedere RFC 7946.

InputRouteMatrixProperties

Specifica l'oggetto proprietà per la matrice di input.

MapsErrorDetail

Dettagli dell'errore.

MapsErrorResponse

Risposta comune all'errore per le API di Azure Maps per restituire dettagli di errore per operazioni fallite.

MapsInnerError

Oggetto contenente informazioni più specifiche dell'oggetto corrente sull'errore.

RouteMatrixAsyncOptimizeRouteEnum

Specifica il parametro da usare per ottimizzare la route. Se non definito, il valore predefinito è "più veloce" che restituisce il percorso per ridurre al minimo il tempo di viaggio.

Esempio: "optimizeRoute":"shortest"

RouteMatrixAsyncRequest

Usare per ottenere una matrice di itinerari che mostra il tempo di viaggio e la distanza per tutte le coppie possibili in un elenco di origini e destinazione. GeoJSON oggetto funzionalità e proprietà aggiuntive. Per informazioni dettagliate, vedere RFC 7946.

RouteMatrixAvoidEnum

Specifica le restrizioni che il calcolo della route deve rispettare quando si determina la route. Evitare supporta più valori in una richiesta ed è supportato solo per la guida e il camion travelMode.

RouteMatrixTrafficEnum

Specifica il modo in cui viene considerato il traffico per le route di calcolo.

Valore predefinito: historical

RouteMatrixTravelModeEnum

Specifica il profilo di viaggio da considerare durante il calcolo della matrice. Se non specificato, il valore predefinito è "driving".

Esempio: "travelMode":"driving"

RouteMatrixTypeEnum

Specifica il tipo MultiPoint di origine e il tipo MultiPoint di destinazione per la matrice di input.

RouteMatrixVehicleSpec

Specifica gli attributi del veicolo, ad esempio altezza del veicolo, peso, velocità massima, tipo di carico e così via, da considerare durante il calcolo della matrice di itinerario. Ciò consente di evitare spazi di ponte bassi, restrizioni stradali, curve a destra difficili per fornire il percorso ottimizzato in base alle specifiche del veicolo. Gli attributi del veicolo vengono specificati all'interno della proprietà vehicleSpec.

VehicleLoadTypeEnum

Tipi di carico che possono essere classificati come materiali pericolosi e limitati da alcune strade. I valori di vehicleLoadType disponibili sono classi Us Hazmat da 1 a 9, oltre a classificazioni generiche da usare in altri paesi. I valori che iniziano con USHazmat sono per l'instradamento degli Stati Uniti, mentre altrihazmat devono essere usati per tutti gli altri paesi. vehicleLoadType supporta più valori in una richiesta.