Route - Post Route Directions Batch

Usare per inviare un batch di query all'API Get Route Directions in una singola richiesta asincrona.

L'API Post Route Directions Batch è una richiesta di POST HTTP che invia batch di query all'API Get Route Directions usando una singola richiesta asincrona. È possibile chiamare Route Directions Batch API per l'esecuzione asincrona (asincrona) o in modo sincrono (sincronizzazione). L'API asincrona consente al chiamante di eseguire il batch fino a 700 query e l'API di sincronizzazione fino a 100 query. Per chiamare l'API Post Route Directions Batch in una richiesta sincrona, vedere Post Route Directions Batch Sync.

Inviare una richiesta batch asincrona

L'API asincrona è appropriata per l'elaborazione di grandi volumi di richieste di route relativamente complesse

• Consente il recupero dei risultati in una chiamata separata (sono possibili più download).
• L'API asincrona è ottimizzata per l'affidabilità e non dovrebbe verificarsi un timeout.
• Il numero di elementi batch è limitato a 700 per questa API.

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. Le risposte asincrone vengono archiviate per 24 ore. L'URL di reindirizzamento restituisce una risposta 404 se usata dopo il periodo di scadenza.

Si noti che la richiesta batch asincrona è un'operazione a esecuzione prolungata. Ecco una sequenza tipica di operazioni:

1. Il client invia una richiesta di route Directions Batch POST a Mappe di Azure.

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

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

   HTTP 202 Accepted: la richiesta batch è stata accettata.

   HTTP Error: si è verificato un errore durante l'elaborazione della richiesta batch. Può trattarsi di un 400 Bad Request o di qualsiasi altro codice di stato Error.

3. Se la richiesta batch è stata accettata correttamente, l'intestazione Location nella risposta contiene l'URL per scaricare i risultati della richiesta batch. Questo URI di stato è simile al seguente:

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

4. Il client invia una richiesta di GET nell'URL di download ottenuto nel passaggio 3 per scaricare i risultati del batch.

Corpo POST per la richiesta batch

Per inviare le indicazioni stradali query si userà una richiesta di POST in cui il corpo della richiesta conterrà la matrice batchItems in formato json e l'intestazione Content-Type verrà impostata su application/json. Ecco un corpo di richiesta di esempio contenente 3 indicazioni stradali query:

{
    "batchItems": [
        { "query": "?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false" },
        { "query": "?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest" },
        { "query": "?query=48.923159,-122.557362:32.621279,-116.840362" }
    ]
}

Una route directions query in un batch è solo un URL parziale senza il protocollo, l'URL di base, il percorso, la versione api e la chiave di sottoscrizione. Può accettare uno dei parametri URIsupportati indicazioni stradali. I valori stringa nella indicazioni stradali query devono essere preceduti da un carattere di escape corretto (ad esempio, " il carattere deve essere preceduto da un carattere di escape con \ ) e deve anche essere codificato correttamente con URL.

L'API asincrona consente al chiamante di eseguire il batch fino a 700 query e l'API di sincronizzazione fino a 100 query e il batch deve contenere almeno 1 query.

Scaricare i risultati batch asincroni

Per scaricare i risultati del batch asincrono, verrà inviata una richiesta di GET all'endpoint di download batch. Questo 'URL di download può essere ottenuto dall'intestazione Location di una richiesta batch di POST riuscita e ha un aspetto simile al seguente:

https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

Ecco la sequenza tipica di operazioni per scaricare i risultati del batch:

1. Il client invia una richiesta di GET usando l'URL di download .

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

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

   Http 200 OK: richiesta batch elaborata correttamente. Il corpo della risposta contiene tutti i risultati del batch.

Modello di risposta batch

Il contenuto dei dati restituito è simile per le richieste asincrone e di sincronizzazione. Quando si scaricano i risultati di una richiesta batch asincrona, se il batch ha terminato l'elaborazione, il corpo della risposta contiene la risposta batch. Questa risposta batch contiene un componente summary che indica il totalRequests che fanno parte della richiesta batch originale e successfulRequestsad esempio le query eseguite correttamente. La risposta batch include anche una matrice di batchItems che contiene una risposta per ogni query e ogni query nella richiesta batch. Il batchItems conterrà i risultati nello stesso ordine in cui le query originali sono state inviate nella richiesta batch. Ogni elemento in batchItems contiene campi statusCode e response. Ogni response in batchItems è di uno dei tipi seguenti:

• RouteDirections: se la query è stata completata correttamente.

• Error: se la query non è riuscita. La risposta conterrà un code e un message in questo caso.

Di seguito è riportato un esempio di risposta batch con 1 riuscito e 1 risultato non riuscito:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

POST https://atlas.microsoft.com/route/directions/batch/json?api-version=1.0

Parametri dell'URI

Intestazione della richiesta

Corpo della richiesta

Risposte

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

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 submit a route direction batch request

POST https://atlas.microsoft.com/route/directions/batch/json?api-version=1.0

{
  "batchItems": [
    {
      "query": "?query=47.639987,-122.128384:47.621252,-122.184408:47.596437,-122.332000&routeType=fastest&travelMode=car&maxAlternatives=99"
    },
    {
      "query": "?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false"
    },
    {
      "query": "?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest"
    }
  ]
}

{
  "batchItems": [
    {
      "statusCode": 400,
      "response": {
        "error": {
          "code": "400 BadRequest",
          "message": "maxAlternatives parameter value should be between 0 and 5 inclusive"
        }
      }
    },
    {
      "statusCode": 200,
      "response": {
        "formatVersion": "0.0.12",
        "routes": [
          {
            "summary": {
              "lengthInMeters": 1754,
              "travelTimeInSeconds": 386,
              "trafficDelayInSeconds": 0,
              "departureTime": "2019-06-21T22:56:23+00:00",
              "arrivalTime": "2019-06-21T23:02:49+00:00"
            },
            "legs": [
              {
                "summary": {
                  "lengthInMeters": 1754,
                  "travelTimeInSeconds": 386,
                  "trafficDelayInSeconds": 0,
                  "departureTime": "2019-06-21T22:56:23+00:00",
                  "arrivalTime": "2019-06-21T23:02:49+00:00"
                },
                "points": [
                  {
                    "latitude": 47.62094,
                    "longitude": -122.34892
                  },
                  {
                    "latitude": 47.62094,
                    "longitude": -122.3485
                  },
                  {
                    "latitude": 47.62095,
                    "longitude": -122.3476
                  },
                  {
                    "latitude": 47.60995,
                    "longitude": -122.34174
                  },
                  {
                    "latitude": 47.61011,
                    "longitude": -122.342
                  }
                ]
              }
            ],
            "sections": [
              {
                "startPointIndex": 0,
                "endPointIndex": 44,
                "sectionType": "TRAVEL_MODE",
                "travelMode": "bicycle"
              }
            ]
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "formatVersion": "0.0.12",
        "routes": [
          {
            "summary": {
              "lengthInMeters": 1772,
              "travelTimeInSeconds": 1276,
              "trafficDelayInSeconds": 0,
              "departureTime": "2019-06-21T22:56:23+00:00",
              "arrivalTime": "2019-06-21T23:17:38+00:00"
            },
            "legs": [
              {
                "summary": {
                  "lengthInMeters": 1772,
                  "travelTimeInSeconds": 1276,
                  "trafficDelayInSeconds": 0,
                  "departureTime": "2019-06-21T22:56:23+00:00",
                  "arrivalTime": "2019-06-21T23:17:38+00:00"
                },
                "points": [
                  {
                    "latitude": 40.75982,
                    "longitude": -73.98493
                  },
                  {
                    "latitude": 40.7601,
                    "longitude": -73.98483
                  },
                  {
                    "latitude": 40.75984,
                    "longitude": -73.98417
                  },
                  {
                    "latitude": 40.76047,
                    "longitude": -73.9837
                  },
                  {
                    "latitude": 40.77095,
                    "longitude": -73.9736
                  },
                  {
                    "latitude": 40.77114,
                    "longitude": -73.97356
                  }
                ]
              }
            ],
            "sections": [
              {
                "startPointIndex": 0,
                "endPointIndex": 47,
                "sectionType": "TRAVEL_MODE",
                "travelMode": "pedestrian"
              }
            ]
          }
        ]
      }
    }
  ],
  "summary": {
    "successfulRequests": 2,
    "totalRequests": 3
  }
}

operation-Location: URL to download the results of the long-running batch request.

Definizioni

BatchRequest

Questo tipo rappresenta il corpo della richiesta per il servizio Batch.

BatchRequestItem

Oggetto richiesta batch

DelayMagnitude

La grandezza del ritardo causato dall'incidente. Questi valori corrispondono ai valori del campo di risposta ty dell'API Get Traffic Incident Detail.

DrivingSide

Indica la guida a sinistra o a destra al punto della manovra.

EffectiveSetting

Parametro o dati effettivi usati quando si chiama questa API di route.

ErrorAdditionalInfo

Informazioni aggiuntive sull'errore di gestione delle risorse.

ErrorDetail

Dettagli dell'errore.

ErrorResponse

Risposta di errore

GuidanceInstructionType

Tipo di istruzione, ad esempio turno o modifica della forma stradale.

GuidanceManeuver

Codice che identifica la manovra.

JsonFormat

Formato desiderato della risposta. È supportato solo json formato.

JunctionType

Tipo di giunzione in cui si svolge la manovra. Per le rotatorie più grandi, vengono generate due istruzioni separate per entrare e lasciare la rotatoria.

LatLongPair

Posizione rappresentata come latitudine e longitudine.

Response

Risultato della query. RouteDirections se la query è stata completata correttamente, ErrorResponse in caso contrario.

<optimizedWaypoints>
<waypoint providedIndex="0" optimizedIndex="1"/>
<waypoint providedIndex="1" optimizedIndex="2"/>
<waypoint providedIndex="2" optimizedIndex="0"/>
</optimizedWaypoints>

ResponseSectionType

Tipi di sezione della risposta di route segnalata

ResponseTravelMode

Modalità di viaggio per il percorso calcolato. Il valore verrà impostato su other se la modalità richiesta di trasporto non è possibile in questa sezione

Route

RouteDirectionsBatchItem

Elemento restituito dalla chiamata al servizio Route Directions Batch.

RouteDirectionsBatchResult

Questo oggetto viene restituito da una chiamata al servizio Route Directions Batch riuscita.

RouteGuidance

Contiene elementi correlati alle linee guida. Questo campo è presente solo quando sono state richieste indicazioni ed è disponibile.

RouteInstruction

Un set di attributi che descrivono una manovra, ad esempio "Gira a destra", "Mantieni a sinistra", "Prendi il traghetto", "Prendi l'autostrada", "Arriva".

10. Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam
11. Follow Einsteinweg/A10/E22 towards Ring Amsterdam

Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam
then follow Einsteinweg/A10/E22 towards Ring Amsterdam.

RouteInstructionGroup

Raggruppa una sequenza di elementi di istruzione correlati tra loro. L'intervallo di sequenze è vincolato con firstInstructionIndex e lastInstructionIndex. Quando vengono richiesti messaggi di testo leggibili per indicazioni (instructionType=text o tagged), il gruppo di istruzioni ha un messaggio di riepilogo restituito quando disponibile.

RouteLeg

Descrizione di una parte di un itinerario, costituito da un elenco di punti. Ogni punto di percorso aggiuntivo fornito nella richiesta comporterà una gamba aggiuntiva nel percorso restituito.

RouteLegSummary

Oggetto riepilogo per la sezione route.

RouteOptimizedWaypoint

Oggetto punto di ottimizzazione.

RouteReport

Segnala le impostazioni effettive usate nella chiamata corrente.

RouteSection

Le sezioni route contengono informazioni aggiuntive sulle parti di un itinerario. Ogni sezione contiene almeno gli elementi startPointIndex, endPointIndexe sectionType.

RouteSectionTec

Dettagli dell'evento di traffico, usando le definizioni nello standard TPEG2-TPEG2. Può contenere effectCode e genera elementi.

RouteSectionTecCause

Causa dell'evento di traffico. Può contenere elementi mainCauseCode e subCauseCode. Può essere usato per definire iconografia e descrizioni.

RouteSummary

Oggetto Riepilogo

SimpleCategory

Tipo di evento imprevisto. Attualmente può essere JAM, ROAD_WORK, ROAD_CLOSURE o OTHER. Per informazioni dettagliate, vedere "tec".

Summary

Riepilogo dei risultati per la richiesta batch