Route - Get Route Matrix

Riferimento

Servizio:: Maps

Versione API:: 1.0

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

L'API Get Route Matrix è una richiesta HTTP GET che calcola il tempo di viaggio e la distanza per tutte le coppie possibili in un elenco di origini e destinazioni. A differenza dell 'API Get Route Directions, che fornisce istruzioni dettagliate sulla route, questa API è incentrata sull'efficienza offrendo il costo (tempo di viaggio e distanza) di routing da ogni origine a ogni destinazione. Per altre informazioni, vedere Procedure consigliate per il servizio di route di Mappe di Azure.

Per ogni origine specificata, il servizio calcola il costo del routing da tale origine a ogni destinazione specificata. Il set di origini e il set di destinazioni possono essere considerati come le intestazioni di colonna e riga di una tabella e ogni cella della tabella contiene i costi di routing dall'origine alla destinazione per tale cella. Ad esempio, si supponga che un'azienda di consegna alimentare abbia 20 conducenti e che debbano trovare il conducente più vicino per prendere la consegna dal ristorante. Per risolvere questo caso d'uso, è possibile chiamare l'API Route matrix.

Per ogni itinerario, vengono restituiti i tempi di viaggio e le distanze. È 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 è 700 e per la richiesta di sincronizzazione è 100 (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 100, potrebbe essere necessario effettuare una richiesta sincrona. La dimensione massima di una matrice per questa API è 100 (il numero di origini moltiplicato per il numero di destinazioni). Tenendo presente tale vincolo, alcuni esempi di possibili dimensioni della matrice sono: 10x10, 6x8, 9x8 (non deve essere quadrato).

GET https://atlas.microsoft.com/route/matrix/sync/json?api-version=1.0&subscription-key={subscription-key}

Invia richiesta matrice di route asincrona

L'API asincrona è appropriata per l'elaborazione di grandi volumi di richieste di routing relativamente complesse. Quando si effettua una richiesta usando una richiesta asincrona, per impostazione predefinita il servizio restituisce un codice di risposta 202 lungo un URL di reindirizzamento nel campo Percorso dell'intestazione della risposta. Questo URL deve essere controllato periodicamente fino a quando non sono disponibili i dati di risposta o le informazioni sull'errore. Se waitForResults parametro nella richiesta è impostato su true, l'utente riceverà una risposta 200 se la richiesta viene completata in meno di 120 secondi.

La dimensione massima di una matrice per questa API è 700 (il numero di origini moltiplicato per il numero di destinazioni). Tenendo presente tale vincolo, alcuni esempi di possibili dimensioni della matrice sono: 50x10, 10x10, 28x25. 10x70 (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.

GET https://atlas.microsoft.com/route/matrix/json?api-version=1.0&subscription-key={subscription-key}

Ecco una sequenza tipica di operazioni asincrone:

Il client invia una richiesta GET matrice di route a Mappe di Azure
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.
Se la richiesta di route matrice è stata accettata correttamente, l'intestazione Location nella risposta contiene l'URL per scaricare i risultati della richiesta. Questo URI di stato è simile al seguente:

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}

Il client invia una richiesta GET sull'URL di download ottenuto nel passaggio 3 per scaricare i risultati

Scaricare i risultati della sincronizzazione

Quando si effettua una richiesta GET per l'API di sincronizzazione matrice di route, il servizio restituisce il codice di risposta 200 per la richiesta riuscita e una matrice di risposte. Il corpo della risposta conterrà i dati e non sarà possibile recuperare i risultati in un secondo momento.

Scaricare i risultati asincroni

Quando una richiesta invia una risposta 202 Accepted, la richiesta viene elaborata usando la pipeline asincrona. Verrà assegnato un URL per controllare lo stato di avanzamento della richiesta asincrona nell'intestazione del percorso della risposta. Questo URI di stato è simile al seguente:

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}

L'URL fornito dall'intestazione della posizione restituirà le risposte seguenti quando viene emessa una richiesta di GET.

HTTP 202 Accepted: la richiesta matrice è stata accettata ma è ancora in corso di elaborazione. Riprovare in qualche tempo.

HTTP 200 OK: la richiesta di matrice è stata elaborata correttamente. Il corpo della risposta contiene tutti i risultati.

GET https://atlas.microsoft.com/route/matrix/{format}?api-version=1.0

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
format	path	True	string	ID matrice ricevuto dopo che la richiesta di Route matrice è stata accettata correttamente.
api-version	query	True	string	Numero di versione dell'API mappe di Azure.

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
x-ms-client-id		string	Specifica quale account è destinato all'utilizzo in combinazione con il modello di sicurezza Microsoft Entra ID. Rappresenta un ID univoco per l'account mappe di Azure e può essere recuperato dall'API dell'account del piano di gestione di Mappe di Azure. Per usare la sicurezza di Microsoft Entra ID in Mappe di Azure, vedere gli articoli di seguenti per indicazioni.

Risposte

Nome	Tipo	Descrizione
200 OK	RouteMatrixResult	Richiesta matrice elaborata correttamente. Il corpo della risposta contiene tutti i risultati.
202 Accepted		Supportato solo per la richiesta asincrona. Richiesta accettata: la richiesta è stata accettata per l'elaborazione. Usare l'URL nell'intestazione percorso per riprovare o accedere ai risultati. Intestazioni Location: string
Other Status Codes	ErrorResponse	Si è verificato un errore imprevisto.

Nome

Tipo

Descrizione

200 OK

RouteMatrixResult

Richiesta matrice elaborata correttamente. Il corpo della risposta contiene tutti i risultati.

202 Accepted

Supportato solo per la richiesta asincrona. Richiesta accettata: la richiesta è stata accettata per l'elaborazione. Usare l'URL nell'intestazione percorso per riprovare o accedere ai risultati.

Intestazioni

Location: string

Other Status Codes

ErrorResponse

Si è verificato un errore imprevisto.

Sicurezza

AADToken

Questi sono i flussi di Microsoft Entra OAuth 2.0. Se abbinato a l'accesso in base al ruolo di Azure controllarlo, può essere usato per controllare l'accesso alle API REST di Mappe di Azure. I controlli di accesso in base al ruolo di Azure vengono usati per designare l'accesso a uno o più account di risorse di Mappe di Azure o a risorse secondarie. A qualsiasi utente, gruppo o entità servizio può essere concesso l'accesso tramite un ruolo predefinito o un ruolo personalizzato composto da una o più autorizzazioni per le API REST di Mappe di Azure.

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.

Note

Questa definizione di sicurezza richiede l'uso dell'intestazione x-ms-client-id per indicare a quale risorsa di Mappe di Azure l'applicazione richiede l'accesso. Questa operazione può essere acquisita dall'API di gestione di mappe .

Il Authorization URL è specifico dell'istanza del cloud pubblico di Azure. I cloud sovrani hanno URL di autorizzazione univoci e configurazioni microsoft Entra ID. * Il controllo degli accessi in base al ruolo di Azure viene configurato dal piano di gestione di Azure tramite il portale di Azure, PowerShell, l'interfaccia della riga di comando, gli SDK di Azure o le API REST. * L'utilizzo del Sdk Web di Mappe di Azure consente la configurazione basata sulla configurazione di un'applicazione per più casi d'uso.

Per altre informazioni su Microsoft Identity Platform, vedere panoramica di Microsoft Identity Platform.

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

Ambiti

Nome	Descrizione
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Si tratta di una chiave condivisa di cui viene effettuato il provisioning quando si Creare un account di Mappe di Azure nel portale di Azure o usando PowerShell, l'interfaccia della riga di comando, gli SDK di Azure o l'API REST.

Con questa chiave, qualsiasi applicazione può accedere a tutte le API REST. In altre parole, questa chiave può essere usata come chiave master nell'account in cui vengono rilasciati.

Per le applicazioni esposte pubblicamente, è consigliabile usare l'approccio applicazioni client riservate per accedere alle API REST di Mappe di Azure in modo che la chiave possa essere archiviata in modo sicuro.

Tipo: apiKey
In: query

SAS Token

Si tratta di un token di firma di accesso condiviso creato dall'operazione List SAS nell'risorsa di Mappe di Azure tramite il piano di gestione di Azure tramite il portale di Azure, PowerShell, l'interfaccia della riga di comando, gli SDK di Azure o le API REST.

Con questo token, qualsiasi applicazione è autorizzata ad accedere ai controlli di accesso in base al ruolo di Azure e al controllo granulare per la scadenza, la frequenza e le aree d'uso per il token specifico. 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

Successfully retrieve the status for a route matrix request

Esempio di richiesta

HTTP

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

Risposta di esempio

Codice di stato:: 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
  }
}

Codice di stato:: 202

Definizioni

Nome	Descrizione
ErrorAdditionalInfo	Informazioni aggiuntive sull'errore di gestione delle risorse.
ErrorDetail	Dettagli dell'errore.
ErrorResponse	Risposta di errore
RouteLegSummary	Oggetto riepilogo per la sezione route.
RouteMatrix	Oggetto risultato matrice
RouteMatrixResult	Questo oggetto viene restituito da una chiamata di Route Matrix riuscita. Ad esempio, se vengono fornite 2 origini e 3 destinazioni, ci saranno 2 matrici con 3 elementi in ognuno. Il contenuto di ogni elemento dipende dalle opzioni disponibili nella query.
RouteMatrixResultResponse	Oggetto risposta della cella corrente nella matrice di input.
RouteMatrixSummary	Oggetto Riepilogo

ErrorAdditionalInfo

Informazioni aggiuntive sull'errore di gestione delle risorse.

Nome	Tipo	Descrizione
info	object	Informazioni aggiuntive.
type	string	Tipo di informazioni aggiuntive.

ErrorDetail

Dettagli dell'errore.

Nome	Tipo	Descrizione
additionalInfo	ErrorAdditionalInfo[]	Informazioni aggiuntive sull'errore.
code	string	Codice di errore.
details	ErrorDetail[]	Dettagli dell'errore.
message	string	Messaggio di errore.
target	string	Destinazione dell'errore.

ErrorResponse

Risposta di errore

Nome	Tipo	Descrizione
error	ErrorDetail	Oggetto error.

RouteLegSummary

Oggetto riepilogo per la sezione route.

Nome	Tipo	Descrizione
arrivalTime	string	Ora di arrivo stimata per il percorso o la gamba. L'ora è in formato UTC.
batteryConsumptionInkWh	number	Consumo di energia elettrica stimato in kilowatt ore (kWh) usando il modello a consumo elettrico. Incluso se vehicleEngineType è impostato su electric e constantSpeedConsumptionInkWhPerHundredkm è specificato. Il valore della batteriaConsumptionInkWh include l'energia elettrica recuperata e può quindi essere negativo (che indica l'acquisizione di energia). Se vengono specificati sia maxChargeInkWh che currentChargeInkWh, il recupero verrà limitato per garantire che il livello di carica della batteria non superi mai maxChargeInkWh. Se non si specificano né maxChargeInkWh né currentChargeInkWh, nel calcolo del consumo viene utilizzato il recupero non vincolato.
departureTime	string	Ora di partenza stimata per il percorso o la gamba. L'ora è in formato UTC.
fuelConsumptionInLiters	number	Consumo stimato di carburante in litri utilizzando il modello a consumo di combustione. Incluso se vehicleEngineType è impostato su di combustione e viene specificato constantSpeedConsumptionInLitersPerHundredkm. Il valore sarà non negativo.
historicTrafficTravelTimeInSeconds	integer	Tempo di viaggio stimato calcolato usando dati di traffico cronologici dipendenti dal tempo. Incluso solo se computeDestinazioniTimeFor = tutto viene usato nella query.
lengthInMeters	integer	Proprietà Length In Meters
liveTrafficIncidentsTravelTimeInSeconds	integer	Tempo di viaggio stimato calcolato usando i dati sulla velocità in tempo reale. Incluso solo se computeDestinazioniTimeFor = tutto viene usato nella query.
noTrafficTravelTimeInSeconds	integer	Tempo di viaggio stimato calcolato come se non ci siano ritardi sulla rotta a causa di condizioni del traffico (ad esempio, congestione). Incluso solo se computeDestinazioniTimeFor = tutto viene usato nella query.
trafficDelayInSeconds	integer	Ritardo stimato in secondi causato dagli eventi imprevisti in tempo reale in base alle informazioni sul traffico. Per gli itinerari pianificati con l'orario di partenza in futuro, i ritardi sono sempre 0. Per restituire tempi di viaggio aggiuntivi usando diversi tipi di informazioni sul traffico, è necessario aggiungere il parametro computeTimeFor=all.
travelTimeInSeconds	integer	Tempo di viaggio stimato in secondi proprietà che include il ritardo dovuto al traffico in tempo reale. Si noti che anche quando traffic=false travelTimeInSeconds include ancora il ritardo dovuto al traffico. Se DepartAt è in futuro, il tempo di viaggio viene calcolato usando dati cronologici cronologici dipendenti dal tempo.

RouteMatrix

Oggetto risultato matrice

Nome	Tipo	Descrizione
response	RouteMatrixResultResponse	Oggetto risposta della cella corrente nella matrice di input.
statusCode	integer	Proprietà StatusCode per la cella corrente nella matrice di input.

RouteMatrixResult

Questo oggetto viene restituito da una chiamata di Route Matrix riuscita. Ad esempio, se vengono fornite 2 origini e 3 destinazioni, ci saranno 2 matrici con 3 elementi in ognuno. Il contenuto di ogni elemento dipende dalle opzioni disponibili nella query.

Nome	Tipo	Descrizione
formatVersion	string	Format Version - proprietà
matrix	RouteMatrix[]	Risultati come matrice bidimensionale di riepiloghi di route.
summary	RouteMatrixSummary	Oggetto Riepilogo

RouteMatrixResultResponse

Oggetto risposta della cella corrente nella matrice di input.

Nome	Tipo	Descrizione
routeSummary	RouteLegSummary	Oggetto riepilogo per la sezione route.

RouteMatrixSummary

Oggetto Riepilogo

Nome	Tipo	Descrizione
successfulRoutes	integer	Numero di route riuscite nella risposta.
totalRoutes	integer	Numero totale di route richieste. Numero di celle nella matrice di input.

Condividi tramite

Route - Get Route Matrix

Invia richiesta matrice di route sincrona

Invia richiesta matrice di route asincrona

Scaricare i risultati della sincronizzazione

Scaricare i risultati asincroni

Parametri dell'URI

Intestazione della richiesta

Risposte

Sicurezza

AADToken

Note

Ambiti

subscription-key

SAS Token

Esempio

Successfully retrieve the status for a route matrix request

Esempio di richiesta

Risposta di esempio

Definizioni

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Risorse aggiuntive