Search - Post Search Address Reverse Batch Sync

Använd för att skicka en batch med frågor till Search-adress-API:et i en enda synkron begäran.
API:et Get Search Address Batch är en HTTP-begäran GET som skickar batchar med frågor till Search-adress-API:et i ett enda synkront API-anrop. Du kan anropa Search Address Reverse Batch API för att köra antingen asynkront (asynkront) eller synkront (synkronisering). Med api:et async kan anroparen batcha upp till 10 000 frågor och synkronisera API:et upp till 100 frågor.

Skicka synkron Batch-begäran

Synkront API rekommenderas för enkla batchbegäranden. När tjänsten tar emot en begäran svarar den så snart batchobjekten beräknas och det finns ingen möjlighet att hämta resultaten senare. Synkront API returnerar ett timeout-fel (ett 408-svar) om begäran tar längre tid än 60 sekunder. Antalet batchobjekt är begränsat till 100 för det här API:et.

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

Skicka asynkron Batch-begäran

Det asynkrona API:et är lämpligt för bearbetning av stora volymer av relativt komplexa sökbegäranden

• Det gör det möjligt att hämta resultat i ett separat anrop (flera nedladdningar är möjliga).
• Det asynkrona API:et är optimerat för tillförlitlighet och förväntas inte överskrida tidsgränsen.
• Antalet batchobjekt är begränsat till 10 000 för det här API:et.

När du gör en begäran med hjälp av en async-begäran returnerar tjänsten som standard en 202-svarskod längs en omdirigerings-URL i fältet Plats i svarshuvudet. Den här URL:en bör kontrolleras regelbundet tills svarsdata eller felinformation är tillgänglig. De asynkrona svaren lagras i 14 dagar. Omdirigerings-URL:en returnerar ett 404-svar om det används efter förfalloperioden.

Observera att en asynkron batchbegäran är en tidskrävande åtgärd. Här är en typisk sekvens med åtgärder:

1. Klienten skickar en Search begäran om omvänd batchadress POST till Azure Maps.

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

2. Servern svarar med något av följande:

   HTTP 202 Accepted – Batch-begäran har accepterats.

   HTTP Error – Det uppstod ett fel vid bearbetning av Batch-begäran. Detta kan antingen vara en 400 Bad Request eller någon annan Error statuskod.

3. Om batchbegäran godkändes Location innehåller rubriken i svaret URL:en för att ladda ned resultatet av batchbegäran. Den här status-URI:n ser ut så här:

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

4. Klienten utfärdar en GET begäran om nedladdnings-URL:en som hämtas i steg 3 för att ladda ned batchresultatet.

POST-brödtext för Batch-begäran

Om du vill skicka omvända sökadressfrågor använder du en POST begäran där begärandetexten innehåller matrisen batchItems i json format och Content-Type rubriken anges till application/json. Här är ett exempel på begärandetext som innehåller 5 omvända sökadressfrågor :

{
    "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"}
    ]
}

En omvänd sökadressfråga i en batch är bara en partiell URL utan protokoll, bas-URL, sökväg, API-version och prenumerationsnyckel. Den kan acceptera någon av de omvända URI-parametrarna för sökadresser som stöds. Strängvärdena i sökadressens omvända fråga måste vara korrekt undantagna (t.ex. " tecken ska vara undantagna med \ ) och det bör också vara korrekt URL-kodat.

Med api:et async kan anroparen batcha upp till 10 000 frågor och synkronisera API:et upp till 100 frågor, och batchen bör innehålla minst 1 fråga.

Ladda ned asynkrona Batch-resultat

Om du vill ladda ned asynkrona batchresultat skickar du en GET begäran till batchnedladdningsslutpunkten. Den här nedladdnings-URL:en kan hämtas från rubriken för Location en lyckad POST batchbegäran och ser ut så här:

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

Här är den typiska sekvensen med åtgärder för att ladda ned batchresultatet:

1. Klienten skickar en GET begäran med hjälp av nedladdnings-URL:en.

2. Servern svarar med något av följande:

   HTTP 202 Accepted – Batch-begäran godkändes men bearbetas fortfarande. Försök igen om en stund.

   HTTP 200 OK – Batch-begäran har bearbetats. Svarstexten innehåller alla batchresultat.

Batch-svarsmodell

Det returnerade datainnehållet liknar asynkronisering och synkroniseringsbegäranden. När du laddar ned resultatet av en asynkron batchbegäran innehåller svarstexten batchsvaret om batchen har slutfört bearbetningen. Det här batchsvaret innehåller en summary komponent som anger totalRequests vilka som ingick i den ursprungliga batchbegäran, dvs successfulRequests. frågor som har körts korrekt. Batchsvaret innehåller också en batchItems matris som innehåller ett svar för varje fråga i batchbegäran. batchItems Innehåller resultatet i exakt samma ordning som de ursprungliga frågorna skickades i batchbegäran. Varje objekt i batchItems innehåller statusCode och response fält. Varje response in batchItems är av någon av följande typer:

• SearchAddressReverseResponse – Om frågan har slutförts.

• Error – Om frågan misslyckades. Svaret innehåller en code och en message i det här fallet.

Här är ett batchsvar med 2 lyckade och 1 misslyckade resultat:

{
    "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/sync/json?api-version=1.0

URI-parametrar

Begärandehuvud

Begärandetext

Svar

Säkerhet

AADToken

Det här är Microsoft Entra OAuth 2.0-flöden. När den är kopplad till rollbaserad åtkomstkontroll i Azure kan den användas för att styra åtkomsten till Azure Maps REST-API:er. Rollbaserade åtkomstkontroller i Azure används för att ange åtkomst till ett eller flera Azure Maps resurskonto eller underresurser. Alla användare, grupper eller tjänstens huvudnamn kan beviljas åtkomst via en inbyggd roll eller en anpassad roll som består av en eller flera behörigheter för att Azure Maps REST-API:er.

För att implementera scenarier rekommenderar vi att du visar autentiseringsbegrepp. Sammanfattningsvis tillhandahåller den här säkerhetsdefinitionen en lösning för modellering av program via objekt som kan ha åtkomstkontroll för specifika API:er och omfång.

Typ: oauth2
Flow: implicit
Auktoriseringswebbadress: https://login.microsoftonline.com/common/oauth2/authorize

Omfattningar

subscription-key

Det här är en delad nyckel som etableras när du skapar ett Azure Maps-konto i Azure Portal eller använder PowerShell, CLI, Azure SDK:er eller REST API.

Med den här nyckeln kan alla program komma åt alla REST-API:et. Med andra ord kan den här nyckeln användas som huvudnyckel i det konto som de har utfärdats i.

För offentligt exponerade program rekommenderar vi att du använder metoden för konfidentiella klientprogram för att komma åt Azure Maps REST-API:er så att din nyckel kan lagras på ett säkert sätt.

Typ: apiKey
I: query

SAS Token

Det här är en signaturtoken för delad åtkomst som skapas från åtgärden Lista SAS på den Azure Maps resursen via Azure-hanteringsplanet via Azure Portal, PowerShell, CLI, Azure SDK:er eller REST-API:er.

Med den här token har alla program behörighet att komma åt med rollbaserade Åtkomstkontroller i Azure och detaljerad kontroll av förfallodatum, frekvens och region för användning för den specifika token. Med andra ord kan SAS-token användas för att tillåta program att styra åtkomsten på ett säkrare sätt än den delade nyckeln.

För offentligt exponerade program rekommenderar vi att du konfigurerar en specifik lista över tillåtna ursprung på map-kontoresursen för att begränsa återgivningsmissbruket och regelbundet förnya SAS-token.

Typ: apiKey
I: header

Exempel

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

POST https://atlas.microsoft.com/search/address/reverse/batch/sync/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"
          }
        ]
      }
    }
  ]
}

{
  "error": {
    "code": "408 Timeout",
    "message": "Timeout: The request took longer to finish than the maximum amount of time defined in the api."
  }
}

Definitioner

Address

Resultatets adress

AddressRanges

Beskriver adressintervallet på båda sidor av gatan för ett sökresultat. Koordinater för start- och slutplatserna för adressintervallet ingår.

BatchRequest

Den här typen representerar begärandetexten för Batch-tjänsten.

BatchRequestItem

Batch-begärandeobjekt

BoundingBox

Det visningsområde som täcker resultatet som representeras av koordinaterna överst till vänster och längst ned till höger i visningsplatsen.

BoundingBoxCompassNotation

Platsens avgränsningsruta.

Brand

Det varumärke som är associerat med POI

Classification

Klassificeringen för den intressepunkt som returneras

ClassificationName

Namn på klassificeringen

DataSources

Valfritt avsnitt. Referens-ID:n för användning med API:et Get Search Polygon.

Entity

Entitetstypkälla för avgränsningsrutan. För omvänd geokodning är detta alltid lika med position.

EntryPoint

Startpunkten för den POI som returneras.

EntryPointType

Typ av startpunkt. Värdet kan vara antingen huvudvärde eller mindre.

ErrorAdditionalInfo

Ytterligare information om resurshanteringsfelet.

ErrorDetail

Felinformationen.

ErrorResponse

Felsvar

GeographicEntityType

Geografientitetstyp. Finns bara när entityType begärdes och är tillgängligt.

Geometry

Information om resultatets geometriska form. Endast tillgänglig om du skriver == Geografi.

JsonFormat

Önskat format för svaret. Endast json format stöds.

LatLongPairAbbreviated

En plats som representeras som latitud och longitud med kortnamnen "lat" & "lon".

MatchType

Matchningstyper för en sökåtgärd med omvänd adress.

OperatingHours

Öppettider för en POI (intressepunkter).

OperatingHoursTime

Representerar ett datum och en tid

OperatingHoursTimeRange

Öppet tidsintervall för en dag

PointOfInterest

Information om den returnerade IP-adressen, inklusive information som namn, telefon, URL-adress och klassificeringar.

PointOfInterestCategorySet

POI-kategori

QueryType

Den typ av fråga som returneras: NÄRLIGGANDE eller NON_NEAR.

Response

Resultatet av frågan. SearchAddressResult om frågan har slutförts, ErrorResponse annars.

ReverseSearchAddressBatchItem

Ett objekt som returneras från tjänstanropet Search Address Reverse Batch.

ReverseSearchAddressBatchProcessResult

Det här objektet returneras från ett lyckat Search anrop till tjänsten Reverse Batch.

SearchAddressResultItem

Resultatobjekt för ett Search API-svar.

SearchAddressResultType

Något av:

• POI
• Gata
• Geografi
• Punktadress
• Adressintervall
• Tvärs över gatan

SearchSummary

Sammanfattningsobjekt för ett Search API-svar.

Summary

Sammanfattning av resultatet för batchbegäran