Route - Post Route Matrix

L'API Route Matrix è 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 di sincronizzazione. 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. Ad esempio, una società di consegna alimentare ha 20 conducenti e devono trovare il conducente più vicino per prendere la consegna dal ristorante. Per risolvere questo caso d'uso, è possibile chiamare l'API Matrice di route e usare il costo di viaggio per ordinare i conducenti in base alla distanza o al tempo di viaggio effettivo dal ristorante.

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 la richiesta di sincronizzazione è 2500 (il numero di origini moltiplicato per il numero di destinazioni).

Invia richiesta matrice di route sincrona

Se lo scenario richiede richieste sincrone e la dimensione massima della matrice è minore o uguale a 2500, potrebbe essere necessario effettuare una richiesta sincrona. La dimensione massima di una matrice per questa API è 2500 (il numero di origini moltiplicato per il numero di destinazioni). Tenendo presente questo vincolo, alcuni esempi di possibili dimensioni della matrice sono: 50x50, 60x40, 90x20 (non è necessario essere quadrati).

Limitazioni api

L'elaborazione sincrona della matrice è più adatta per le matrici veloci e piccole di calcolo della route. Per calcolare matrici più grandi e calcoli di route pesanti, usare l'endpoint asincrono. La limitazione seguente è applicabile alle richieste sincrone. Se nessuna delle righe nella tabella seguente corrisponde ai parametri della richiesta, la richiesta non soddisfa i requisiti e non verrà elaborata.

| Dimensione massima della matrice | Numero massimo di origini | Numero massimo di destinazioni | Limiti aggiuntivi

|------------------|------------------------|----------------------------|------------| | 100 | 100 | 100 | N/A | | 200 | 200 | 200 | Tutte le origini e destinazioni dovrebbero essere contenute in una scatola di delimitazione allineata con asse di 400 km x 400 km. In caso contrario, alcune celle della matrice verranno risolte come OUT_OF_REGION. | | 2500 | 1000 | 1000 | - departAt o arriveAt deve esserci qualcuno.
- traffic deve essere cronologico.
- travelMode deve essere guidata o camion
- Nessun altro parametro può essere usato esplicitamente |

Esempi:

• Richiesta di matrice 10x20 con traffic=live: questa richiesta verrà elaborata con un limite di rettangolo delimitatore, in quanto corrisponde a un limite massimo di 200, che include restrizioni del rettangolo di selezione.

• Richiesta di matrice 10x20 con parametri predefiniti (traffic=historical): questa richiesta verrà elaborata senza un limite di rettangolo delimitatore, in quanto corrisponde a un limite massimo di 2500, che non impone restrizioni del rettangolo di selezione.

POST {endpoint}/route/matrix?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 Mappe di Azure. I controlli di accesso basati su ruoli di Azure sono utilizzati per designare l'accesso a uno o più account o sottorisorse risorse di Mappe di Azure. 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 per Mappe di Azure API REST.\n\nPer implementare scenari, consigliamo di consultare i concetti di autenticazione . In sintesi, questa definizione di sicurezza fornisce una soluzione per modellare l'applicazione tramite oggetti in grado di controllo degli accessi su API e ambiti specifici.\n\n#### Note\n* Questa definizione di sicurezza richiede l'uso dell'intestazione x-ms-client-id per indicare a quale Mappe di Azure risorsa l'applicazione richiede accesso. Questo può essere acquisito dall'API di gestione Maps.\n* \nIl Authorization URL è specifico per l'istanza Azure cloud pubblico. I cloud sovrani hanno URL di autorizzazione unici e configurazioni Microsoft Entra ID. \n* \nIl controllo accessibile basato sul ruolo Azure viene configurato dal piano di gestione Azure tramite Azure portale, PowerShell, CLI, Azure SDK o API REST.\n* \nUtilizzo del Mappe di Azure Web SDK consente la configurazione di un'applicazione basata sulla configurazione per molteplici casi d'uso.\n* Per maggiori informazioni su Microsoft Identity Platform, vedi Microsoft Identity Platform panoramica.

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 Crea un account Mappe di Azure nel portale Azure o utilizzando PowerShell, CLI, Azure SDK o API REST.\n\n Con questa chiave, qualsiasi applicazione può accedere a tutte le API REST. In altre parole, questa chiave può essere utilizzata come chiave master nell'account in cui vengono rilasciate.\n\n Per applicazioni pubblicamente esposte, la nostra raccomandazione è di utilizzare l'approccio confidential per accedere alle API REST Mappe di Azure modo che la tua chiave possa essere memorizzata in modo sicuro.

Tipo: apiKey
In: header

SAS Token

Questo token di firma di accesso condiviso viene creato dall'operazione List SAS sulla risorsa Mappe di Azure tramite il piano di gestione Azure tramite portale Azure, PowerShell, CLI, Azure SDK o API REST.\n\n Con questo token, qualsiasi applicazione è autorizzata ad accedere con Azure Controlli di accesso basati su ruoli e controllo sottile sulla scadenza, la velocità e la regione/i di utilizzo per il token specifico. In altre parole, il Token SAS può essere utilizzato per permettere alle applicazioni di controllare l'accesso in modo più sicuro rispetto alla chiave condivisa.\n\n Per applicazioni pubblicamente esposte, la nostra raccomandazione è di configurare una lista specifica di origini consentite sulla risorsa dell'account Map per limitare l'abuso di rendering e rinnovare regolarmente il token SAS.

Tipo: apiKey
In: header

Esempio

Successfully retrieve a route matrix with additional parameters in the body

POST {endpoint}/route/matrix?api-version=2025-01-01

{
  "type": "FeatureCollection",
  "avoid": [
    "unpavedRoads"
  ],
  "departAt": "2022-12-19T16:39:57+01:00",
  "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"
      }
    }
  ],
  "optimizeRoute": "fastest",
  "traffic": "historical",
  "travelMode": "truck"
}

{
  "type": "Feature",
  "geometry": null,
  "properties": {
    "matrix": [
      {
        "arrivalAt": "2022-12-19T22:30:03+01:00",
        "departureAt": "2022-12-19T16:39:57+01:00",
        "destinationIndex": 0,
        "distanceInMeters": 492466,
        "durationInSeconds": 21007,
        "durationTrafficInSeconds": 21007,
        "originIndex": 0,
        "statusCode": 200
      },
      {
        "arrivalAt": "2022-12-20T02:00:19+01:00",
        "departureAt": "2022-12-19T16:39:57+01:00",
        "destinationIndex": 1,
        "distanceInMeters": 877028,
        "durationInSeconds": 33623,
        "durationTrafficInSeconds": 33623,
        "originIndex": 0,
        "statusCode": 200
      },
      {
        "arrivalAt": "2022-12-19T22:05:16+01:00",
        "departureAt": "2022-12-19T16:39:57+01:00",
        "destinationIndex": 0,
        "distanceInMeters": 427769,
        "durationInSeconds": 19520,
        "durationTrafficInSeconds": 19520,
        "originIndex": 1,
        "statusCode": 200
      },
      {
        "arrivalAt": "2022-12-20T01:34:27+01:00",
        "departureAt": "2022-12-19T16:39:57+01:00",
        "destinationIndex": 1,
        "distanceInMeters": 836080,
        "durationInSeconds": 32070,
        "durationTrafficInSeconds": 32070,
        "originIndex": 1,
        "statusCode": 200
      }
    ],
    "summary": {
      "successfulCount": 4,
      "totalCount": 4
    }
  }
}

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.

CommonErrorDetail

Dettagli dell'errore.

ErrorAdditionalInfo

Informazioni aggiuntive sull'errore di gestione delle risorse.

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.

GeoJsonObjectType

Specifica il tipo di GeoJSON. Deve essere uno dei nove tipi di oggetto GeoJSON validi: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature e FeatureCollection.

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 Mappe di Azure per restituire dettagli di errore per operazioni fallite.

MapsInnerError

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

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.

RouteMatrixFeatureProperties

Proprietà della matrice di route.

RouteMatrixItemResult

Risultato dell'elemento Matrice di route

RouteMatrixOptimizeRouteEnum

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":"fastest"

RouteMatrixRequest

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.

RouteMatrixResponse

Questo oggetto viene restituito da una chiamata riuscita.

RouteMatrixSummary

Riepilogo per la richiesta della matrice di route

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.