Search - Post Search Address Reverse Batch

Usare per inviare un batch di query all'API inversa degli indirizzi Search in una singola richiesta asincrona.

L'API Post Search Address Reverse Batch è una richiesta HTTP POST che invia batch di query a Search'API inversa degli indirizzi in una singola chiamata API asincrona. È possibile chiamare Post Search Address Reverse Batch l'API per eseguire in modo asincrono (asincrono) o in modo sincrono (sincronizzazione). L'API asincrona consente al chiamante di eseguire il batch fino a 10.000 query e l'API di sincronizzazione fino a 100 query.

Invia richiesta batch sincrona

L'API sincrona è consigliata per le richieste batch leggere. Quando il servizio riceve una richiesta, risponderà non appena vengono calcolati gli elementi batch e non sarà possibile recuperare i risultati in un secondo momento. L'API sincrona restituirà un errore di timeout (risposta 408) se la richiesta richiede più di 60 secondi. Il numero di elementi batch è limitato a 100 per questa API.

POST https://atlas.microsoft.com/search/address/reverse/batch/sync/json?api-version=1.0&subscription-key={subscription-key}

Invia richiesta batch asincrona

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

• Consente il recupero dei risultati in una chiamata separata (sono possibili più download).
• L'API asincrona è ottimizzata per l'affidabilità e non deve essere eseguita in un timeout.
• Il numero di elementi batch è limitato a 10.000 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 di risposta. Questo URL deve essere controllato periodicamente fino a quando non sono disponibili i dati di risposta o le informazioni sugli errori. Le risposte asincrone vengono archiviate per 14 giorni. 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 batch inverso POST di indirizzi Search a Mappe di Azure.

POST https://atlas.microsoft.com/search/address/reverse/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. Questo potrebbe essere un 400 Bad Request o qualsiasi altro Error codice di stato.

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/search/address/reverse/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

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

CORPO POST per la richiesta batch

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

{
    "batchItems": [
        {"query": "?query=48.858561,2.294911"},
        {"query": "?query=47.639765,-122.127896&radius=5000&limit=2"},
        {"query": "?query=47.621028,-122.348170"},
        {"query": "?query=43.722990,10.396695"},
        {"query": "?query=40.750958,-73.982336"}
    ]
}

Una query inversa dell'indirizzo di ricerca 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 dell'URIinverso degli indirizzi di ricerca supportati. I valori di stringa nella query inversa dell'indirizzo di ricerca devono essere eliminati correttamente (ad esempio " il carattere deve essere escape con \ ) e deve anche essere codificato correttamente con URL.

L'API asincrona consente al chiamante di eseguire il batch fino a 10.000 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 batch asincroni, verrà eseguita una GET richiesta all'endpoint di download batch. Questo URL di download può essere ottenuto dall'intestazione Location di una richiesta batch riuscita POST e ha un aspetto simile al seguente:

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

Ecco la sequenza tipica di operazioni per il download dei risultati batch:

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

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

   HTTP 202 Accepted : richiesta batch accettata ma ancora in fase di elaborazione. Riprovare in qualche momento.

   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 alle richieste asincrone e di sincronizzazione. Quando si scaricano i risultati di una richiesta batch asincrona, se il batch ha completato l'elaborazione, il corpo della risposta contiene la risposta batch. Questa risposta batch contiene un summary componente che indica la totalRequests parte della richiesta batch originale e successfulRequests, ad esempio, le query eseguite correttamente. La risposta batch include anche una matrice che contiene una batchItems risposta per ogni query e ogni query nella richiesta batch. Conterrà batchItems i risultati nello stesso ordine di invio delle query originali nella richiesta batch. Ogni elemento in batchItems contiene statusCode e response campi. Ognuno response di essi batchItems è di uno dei tipi seguenti:

• SearchAddressReverseResponse - Se la query è stata completata correttamente.

• Error - Se la query non è riuscita. La risposta conterrà un code oggetto e in message questo caso.

Ecco un esempio di Risposta batch con esito positivo e 1 risultato negativo :

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "queryTime": 11
                },
                "addresses": [
                    {
                        "address": {
                            "country": "France",
                            "freeformAddress": "Avenue Anatole France, 75007 Paris"
                        },
                        "position": "48.858490,2.294820"
                    }
                ]
            }
        },
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "queryTime": 1
                },
                "addresses": [
                    {
                        "address": {
                            "country": "United States of America",
                            "freeformAddress": "157th Pl NE, Redmond WA 98052"
                        },
                        "position": "47.640470,-122.129430"
                    }
                ]
            }
        },
        {
            "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/search/address/reverse/batch/json?api-version=1.0

Parametri dell'URI

Intestazione della richiesta

Corpo della richiesta

Risposte

Sicurezza

AADToken

Si tratta dei flussi OAuth 2.0 Microsoft Entra. Quando è associato al controllo degli accessi in base al ruolo di Azure, può essere usato per controllare l'accesso alle API REST Mappe di Azure. I controlli di accesso basati sul ruolo di Azure vengono usati per designare l'accesso a uno o più Mappe di Azure account delle risorse o alle sotto-risorse. 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 Mappe di Azure API REST.

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

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 eseguito il provisioning quando si crea un account Mappe di Azure nell'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 delle applicazioni client riservate per accedere alle API REST 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 Elenco firma di accesso condiviso nella risorsa Mappe di Azure tramite il piano di gestione di Azure tramite portale di Azure, PowerShell, interfaccia della riga di comando, SDK di Azure o API REST.

Con questo token, qualsiasi applicazione è autorizzata ad accedere con i controlli di accesso basati sul ruolo di Azure e il controllo granulare alla scadenza, alla frequenza e alle 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

A Reverse Geocoding Batch API call containing 5 Reverse Geocoding API queries

POST https://atlas.microsoft.com/search/address/reverse/batch/json?api-version=1.0

{
  "batchItems": [
    {
      "query": "?query=48.858561,2.294911"
    },
    {
      "query": "?query=47.639765,-122.127896&radius=5000&limit=2"
    },
    {
      "query": "?query=47.621028,-122.348170"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 3,
    "totalRequests": 3
  },
  "batchItems": [
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 8,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "streetNumber": "7",
              "routeNumbers": [],
              "streetName": "Avenue Anatole France",
              "streetNameAndNumber": "7 Avenue Anatole France",
              "countryCode": "FR",
              "countrySubdivisionCode": "Île-de-France",
              "countrySecondarySubdivision": "Paris",
              "municipality": "Paris",
              "postalCode": "75007",
              "municipalitySubdivision": "7ème Arrondissement",
              "country": "France",
              "countryCodeISO3": "FRA",
              "freeformAddress": "7 Avenue Anatole France, Paris, 75007",
              "boundingBox": {
                "northEast": "48.858321,2.295167",
                "southWest": "48.858136,2.295027",
                "entity": "position"
              }
            },
            "position": "48.858231,2.295089"
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 8,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "routeNumbers": [],
              "countryCode": "US",
              "countrySubdivisionCode": "WA",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "municipality": "Redmond",
              "postalCode": "98052",
              "country": "United States",
              "countryCodeISO3": "USA",
              "freeformAddress": "Redmond, WA 98052",
              "boundingBox": {
                "northEast": "47.639765,-122.128661",
                "southWest": "47.639502,-122.129456",
                "entity": "position"
              },
              "countrySubdivisionName": "Washington"
            },
            "position": "47.639687,-122.128677"
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 19,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "streetNumber": "410",
              "routeNumbers": [],
              "streetName": "Thomas Street",
              "streetNameAndNumber": "410 Thomas Street",
              "countryCode": "US",
              "countrySubdivisionCode": "WA",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "municipality": "Seattle",
              "postalCode": "98109",
              "municipalitySubdivision": "Seattle, Lower Queen Anne",
              "country": "United States",
              "countryCodeISO3": "USA",
              "freeformAddress": "410 Thomas Street, Seattle, WA 98109",
              "boundingBox": {
                "northEast": "47.620954,-122.347601",
                "southWest": "47.620944,-122.348498",
                "entity": "position"
              },
              "extendedPostalCode": "981094621",
              "countrySubdivisionName": "Washington"
            },
            "position": "47.620945,-122.348175"
          }
        ]
      }
    }
  ]
}

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

Definizioni

Address

Indirizzo del risultato

AddressRanges

Descrive l'intervallo di indirizzi su entrambi i lati della strada per un risultato di ricerca. Le coordinate per le posizioni iniziali e finali dell'intervallo di indirizzi sono incluse.

BatchRequest

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

BatchRequestItem

Oggetto richiesta batch

BoundingBox

Viewport che copre il risultato rappresentato dalle coordinate in alto a sinistra e in basso a destra del riquadro di visualizzazione.

BoundingBoxCompassNotation

Casella di selezione della posizione.

Brand

Il marchio associato all'entità di ricerca

Classification

Classificazione dell'oggetto POI restituito

ClassificationName

Nome per la classificazione

DataSources

Sezione facoltativa. ID di riferimento da usare con l'API Get Search Polygon.

Entity

Origine del tipo di entità del rettangolo di selezione. Per la geocodatura inversa, questa operazione è sempre uguale alla posizione.

EntryPoint

Punto di ingresso per l'oggetto POI restituito.

EntryPointType

Tipo di punto di ingresso. Il valore può essere principale o secondario.

ErrorAdditionalInfo

Informazioni aggiuntive sulla gestione delle risorse.

ErrorDetail

Dettagli dell'errore.

ErrorResponse

Risposta di errore

GeographicEntityType

Tipo di entità Geography. Presente solo quando entityType è stato richiesto ed è disponibile.

Geometry

Informazioni sulla forma geometrica del risultato. Presente solo se tipo == Geography.

JsonFormat

Formato desiderato della risposta. È supportato solo il formato json.

LatLongPairAbbreviated

Una posizione rappresentata come latitudine e longitudine usando nomi brevi 'lat' & 'lon'.

MatchType

Tipi di corrispondenza per un'operazione di ricerca degli indirizzi inversa.

OperatingHours

Ore di apertura per un punto di interesse (punti di interesse).

OperatingHoursTime

Rappresenta una data e un'ora

OperatingHoursTimeRange

Intervallo di tempo aperto per un giorno

PointOfInterest

Dettagli dell'oggetto POI restituito, incluse informazioni quali il nome, il telefono, l'indirizzo url e le classificazioni.

PointOfInterestCategorySet

Categoria POI

QueryType

Tipo di query restituito: NEARBY o NON_NEAR.

Response

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

ReverseSearchAddressBatchItem

Elemento restituito dalla chiamata al servizio Address Reverse Batch Search.

ReverseSearchAddressBatchProcessResult

Questo oggetto viene restituito da unachiamataa Search chiamata al servizio Batch inverso.

SearchAddressResultItem

Oggetto Result per una risposta API Search.

SearchAddressResultType

Uno dei valori possibili:

• POI
• Indirizzo
• Area geografica
• Punto di interesse
• Intervallo di indirizzi
• Incrocio

SearchSummary

Oggetto Riepilogo per una risposta API Search.

Summary

Riepilogo dei risultati della richiesta batch