Search - Post Search Address Batch

Slouží k odeslání dávky dotazů do rozhraní API adresy Search v jednom asynchronním požadavku.
Rozhraní Post Search Address Batch API je požadavek HTTPPOST, který odesílá dávky dotazů do rozhraní API Search adresy v jednom synchronním voláním rozhraní API. Můžete volat rozhraní API Search Address Batch a spustit buď asynchronně (async), nebo synchronně (synchronizovat). Asynchronní rozhraní API umožňuje volajícímu dávkovat až 10 000 dotazů a synchronizovat rozhraní API až 100 dotazů.

Odeslání synchronní dávkové žádosti

Synchronní rozhraní API se doporučuje pro zjednodušené dávkové požadavky. Když služba obdrží požadavek, zareaguje, jakmile se dávkové položky vypočítají, a nebude možné později načíst výsledky. Synchronní rozhraní API vrátí chybu časového limitu (odpověď 408), pokud požadavek trvá déle než 60 sekund. Počet položek dávky je pro toto rozhraní API omezený na 100 .

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

Odeslání asynchronního dávkového požadavku

Asynchronní rozhraní API je vhodné pro zpracování velkých objemů relativně složitých požadavků na vyhledávání.

• Umožňuje načtení výsledků v samostatném volání (je možné stáhnout více položek).
• Asynchronní rozhraní API je optimalizované z hlediska spolehlivosti a neočekává se, že dojde k vypršení časového limitu.
• Počet položek dávky je pro toto rozhraní API omezený na 10 000 .

Když vytvoříte požadavek pomocí asynchronního požadavku, služba ve výchozím nastavení vrátí kód odpovědi 202 spolu s adresou URL přesměrování v poli Umístění hlavičky odpovědi. Tato adresa URL by měla být pravidelně kontrolována, dokud nebudou k dispozici data odpovědi nebo informace o chybě. Asynchronní odpovědi se ukládají po dobu 14 dnů. Adresa URL pro přesměrování vrátí odpověď 404, pokud se použije po uplynutí doby vypršení platnosti.

Mějte na paměti, že asynchronní dávkové požadavky jsou dlouhotrvající operace. Tady je typická posloupnost operací:

1. Klient odešle žádost Search Address Batch POST do Azure Maps.

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

2. Server odpoví jedním z následujících způsobů:

   HTTP 202 Accepted – Dávkový požadavek byl přijat.

   HTTP Error – Při zpracování požadavku Batch došlo k chybě. Může se jednat o stavový 400 Bad Request kód nebo jakýkoli jiný Error .

3. Pokud byl dávkový požadavek úspěšně přijat, Location hlavička v odpovědi obsahuje adresu URL pro stažení výsledků dávkového požadavku. Tento identifikátor URI stavu vypadá takto:

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

4. Klient vydá na adresu URL pro stažení získanou GET v kroku 3 žádost o stažení výsledků dávky.

Text POST pro žádost Batch

K odeslání dotazů na vyhledávací adresu použijete POST požadavek, ve kterém text požadavku bude obsahovat batchItems pole ve json formátu a hlavička Content-Type bude nastavená na application/json. Tady je ukázkový text požadavku obsahující 5 dotazů na vyhledávací adresu :

{
    "batchItems": [
        {"query": "?query=400 Broad St, Seattle, WA 98109&limit=3"},
        {"query": "?query=One, Microsoft Way, Redmond, WA 98052&limit=3"},
        {"query": "?query=350 5th Ave, New York, NY 10118&limit=1"},
        {"query": "?query=Pike Pl, Seattle, WA 98101&lat=47.610970&lon=-122.342469&radius=1000"},
        {"query": "?query=Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France&limit=1"}
    ]
}

Dotaz na vyhledávací adresu v dávce je pouze částečná adresa URL bez protokolu, základní adresy URL, cesty, verze rozhraní API a klíče předplatného. Může přijmout libovolný z podporovaných parametrů identifikátoru URIvyhledávací adresy. Řetězcové hodnoty v dotazu na vyhledávací adresu musí být správně uvozené (např. znak " by měl být uvozován znakem \ ) a měl by být také správně zakódovaný do adresy URL.

Asynchronní rozhraní API umožňuje volajícímu dávkovat až 10 000 dotazů a synchronizovat rozhraní API až 100 dotazů a dávka by měla obsahovat alespoň 1 dotaz.

Stažení asynchronních dávkových výsledků

Pokud chcete stáhnout výsledky asynchronní dávky, odešlete GET požadavek na koncový bod dávkového stahování. Tuto adresu URL ke stažení můžete získat z Location hlavičky úspěšného POST dávkového požadavku a vypadá takto:

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

Tady je typická posloupnost operací pro stažení výsledků dávky:

1. Klient odešle GET požadavek pomocí adresy URL pro stažení.

2. Server odpoví jedním z následujících způsobů:

   HTTP 202 Accepted – Dávkový požadavek byl přijat, ale stále se zpracovává. Zkuste to prosím znovu za nějakou dobu.

   HTTP 200 OK – Dávkový požadavek se úspěšně zpracoval. Tělo odpovědi obsahuje všechny výsledky dávky.

Model dávkové odpovědi

Vrácený obsah dat je podobný pro asynchronní a synchronizační požadavky. Když se při stahování výsledků asynchronního požadavku dávky dokončí zpracování dávky, tělo odpovědi obsahuje dávkovou odpověď. Tato dávková odpověď obsahuje komponentu summarytotalRequests , která označuje, že byly součástí původního dávkového požadavku, a successfulRequeststj. dotazy, které byly úspěšně provedeny. Dávková odpověď obsahuje batchItems také pole, které obsahuje odpověď pro každý dotaz v dávkovém požadavku. Bude batchItems obsahovat výsledky ve stejném pořadí, v jakém byly původní dotazy odeslány v dávkovém požadavku. Každá položka v souboru batchItems obsahuje statusCode pole a response . Každý response v batchItems má jeden z následujících typů:

• SearchAddressResult – Pokud se dotaz úspěšně dokončil.

• Error – Pokud dotaz selhal. Odpověď bude v tomto případě obsahovat a code .message

Tady je ukázka dávkové odpovědi se 2 úspěšnými a 1 neúspěšnými výsledky:

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "query": "one microsoft way redmond wa 98052"
                },
                "results": [
                    {
                        "position": {
                            "lat": 47.63989,
                            "lon": -122.12509
                        }
                    }
                ]
            }
        },
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "query": "pike pl seattle wa 98101"
                },
                "results": [
                    {
                        "position": {
                            "lat": 47.60963,
                            "lon": -122.34215
                        }
                    }
                ]
            }
        },
        {
            "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/batch/json?api-version=1.0

Parametry identifikátoru URI

Hlavička požadavku

Text požadavku

Odpovědi

Zabezpečení

AADToken

Toto jsou Microsoft Entra toky OAuth 2.0. Při spárování s řízením přístupu na základě role v Azure se dá použít k řízení přístupu k Azure Maps rozhraní REST API. Řízení přístupu na základě role v Azure slouží k určení přístupu k jednomu nebo několika Azure Maps účtu prostředku nebo dílčím prostředkům. Každému uživateli, skupině nebo instančnímu objektu je možné udělit přístup prostřednictvím předdefinované role nebo vlastní role složené z jednoho nebo více oprávnění k Azure Maps rozhraní REST API.

Pokud chcete implementovat scénáře, doporučujeme zobrazit si koncepty ověřování. Souhrnně řečeno, tato definice zabezpečení poskytuje řešení pro modelování aplikací prostřednictvím objektů schopných řízení přístupu pro konkrétní rozhraní API a obory.

Typ: oauth2
Tok: implicit
URL autorizace: https://login.microsoftonline.com/common/oauth2/authorize

Rozsahy

subscription-key

Jedná se o sdílený klíč, který se zřídí při vytvoření účtu Azure Maps v Azure Portal nebo pomocí PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API.

S tímto klíčem může každá aplikace přistupovat ke všem rozhraním REST API. Jinými slovy, tento klíč se dá použít jako hlavní klíč v účtu, ve kterému je vystavený.

U veřejně vystavených aplikací doporučujeme pro přístup k Azure Maps rozhraní REST API použít přístup k důvěrným klientským aplikacím, aby se váš klíč mohl bezpečně uložit.

Typ: apiKey
V: query

SAS Token

Jedná se o token sdíleného přístupového podpisu, který se vytvoří z operace List SAS v Azure Maps prostředku prostřednictvím roviny správy Azure prostřednictvím Azure Portal, PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API.

S tímto tokenem má každá aplikace autorizaci pro přístup pomocí řízení přístupu na základě role v Azure a podrobnou kontrolu vypršení platnosti, četnosti a oblastí použití konkrétního tokenu. Jinými slovy, token SAS je možné použít k tomu, aby aplikace mohly řídit přístup zabezpečeným způsobem než sdílený klíč.

U veřejně vystavených aplikací doporučujeme nakonfigurovat konkrétní seznam povolených zdrojů v prostředku účtu map , aby se omezilo zneužití vykreslování, a pravidelně obnovovat token SAS.

Typ: apiKey
V: header

Příklady

An Address Geocoding Batch API call containing 5 Address Geocoding API queries

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

{
  "batchItems": [
    {
      "query": "?query=400 Broad St, Seattle, WA 98109&limit=3"
    },
    {
      "query": "?query=One, Microsoft Way, Redmond, WA 98052&limit=3"
    },
    {
      "query": "?query=350 5th Ave, New York, NY 10118&limit=1"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 3,
    "totalRequests": 3
  },
  "batchItems": [
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "400 broad st seattle wa 98109",
          "queryType": "NON_NEAR",
          "queryTime": 127,
          "numResults": 3,
          "offset": 0,
          "totalResults": 9,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Point Address",
            "id": "US/PAD/p0/20843845",
            "score": 11.966,
            "address": {
              "streetNumber": "400",
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, South Lake Union, Lower Queen Anne",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "400 Broad Street, Seattle, WA 98109",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.62039,
              "lon": -122.34928
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.62129,
                "lon": -122.35061
              },
              "btmRightPoint": {
                "lat": 47.61949,
                "lon": -122.34795
              }
            },
            "entryPoints": [
              {
                "type": "main",
                "position": {
                  "lat": 47.61982,
                  "lon": -122.34886
                }
              }
            ]
          },
          {
            "type": "Street",
            "id": "US/STR/p0/388442",
            "score": 10.225,
            "address": {
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, South Lake Union",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109",
              "extendedPostalCode": "981094612",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Broad Street, Seattle, WA 98109",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.62001,
              "lon": -122.34843
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.61965,
                "lon": -122.34761
              },
              "btmRightPoint": {
                "lat": 47.62066,
                "lon": -122.349
              }
            }
          },
          {
            "type": "Street",
            "id": "US/STR/p0/388680",
            "score": 10.225,
            "address": {
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, Belltown",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109,98121",
              "extendedPostalCode": "981094991,981211117,981211237,981213206",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Broad Street, Seattle, WA",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.61691,
              "lon": -122.35251
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.61502,
                "lon": -122.35041
              },
              "btmRightPoint": {
                "lat": 47.61857,
                "lon": -122.35484
              }
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "one microsoft way redmond wa 98052",
          "queryType": "NON_NEAR",
          "queryTime": 169,
          "numResults": 2,
          "offset": 0,
          "totalResults": 3292,
          "fuzzyLevel": 2
        },
        "results": [
          {
            "type": "Street",
            "id": "US/STR/p0/1692663",
            "score": 10.225,
            "address": {
              "streetName": "Microsoft Way",
              "municipality": "Redmond",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "countrySubdivisionCode": "WA",
              "postalCode": "98052",
              "extendedPostalCode": "980526399,980528300",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Microsoft Way, Redmond, WA 98052",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.63989,
              "lon": -122.12509
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.63748,
                "lon": -122.12309
              },
              "btmRightPoint": {
                "lat": 47.64223,
                "lon": -122.13061
              }
            }
          },
          {
            "type": "Cross Street",
            "id": "US/XSTR/p1/4779971",
            "score": 8.506,
            "address": {
              "streetName": "Microsoft Way & 157th Avenue Northeast, Microsoft Way",
              "municipality": "Redmond",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "countrySubdivisionCode": "WA",
              "postalCode": "98052",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Microsoft Way & 157th Avenue Northeast, Redmond, WA 98052",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.63962,
              "lon": -122.13061
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.64052,
                "lon": -122.13194
              },
              "btmRightPoint": {
                "lat": 47.63872,
                "lon": -122.12928
              }
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "350 5th ave new york ny 10118",
          "queryType": "NON_NEAR",
          "queryTime": 233,
          "numResults": 1,
          "offset": 0,
          "totalResults": 8032,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Point Address",
            "id": "US/PAD/p0/48052000",
            "score": 14.334,
            "address": {
              "streetNumber": "350",
              "streetName": "5th Avenue",
              "municipalitySubdivision": "New York, Midtown South",
              "municipality": "New York, Manhattan",
              "countrySecondarySubdivision": "New York",
              "countryTertiarySubdivision": "Manhattan",
              "countrySubdivisionCode": "NY",
              "postalCode": "10118",
              "extendedPostalCode": "1011800",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "350 5th Avenue, NYC, NY 10118",
              "countrySubdivisionName": "New York"
            },
            "position": {
              "lat": 40.74817,
              "lon": -73.985
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 40.74907,
                "lon": -73.98619
              },
              "btmRightPoint": {
                "lat": 40.74727,
                "lon": -73.98381
              }
            },
            "entryPoints": [
              {
                "type": "main",
                "position": {
                  "lat": 40.74808,
                  "lon": -73.98482
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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

Definice

Address

Adresa výsledku

AddressRanges

Popisuje rozsah adres na obou stranách ulice pro výsledek hledání. Jsou zahrnuté souřadnice počátečního a koncového umístění rozsahu adres.

BatchRequest

Tento typ představuje text požadavku pro službu Batch.

BatchRequestItem

Objekt žádosti Batch

BoundingBox

Zobrazení, které pokrývá výsledek představovaný souřadnicemi vlevo nahoře a vpravo dole v oblasti zobrazení.

BoundingBoxCompassNotation

Ohraničující rámeček umístění.

Brand

Značka přidružená k poi

Classification

Klasifikace pro vrácené BŽS

ClassificationName

Název klasifikace

DataSources

Volitelný oddíl. Referenční ID pro použití s rozhraním Get Search Polygon API

Entity

Zdroj typu entity ohraničujícího rámečku. Pro reverzní geokódování je to vždy stejné jako pozice.

EntryPoint

Vstupní bod pro vrácené BŽ.

EntryPointType

Typ vstupního bodu. Hodnota může být hlavní nebo vedlejší.

ErrorAdditionalInfo

Další informace o chybě správy prostředků

ErrorDetail

Podrobnosti o chybě

ErrorResponse

Chybová odpověď

GeographicEntityType

Typ entity Zeměpis. K dispozici pouze v případech, kdy byl požadován typ entity a je k dispozici.

Geometry

Informace o geometrickém tvaru výsledku. Je k dispozici pouze v případě, že zadáte == Zeměpis.

JsonFormat

Požadovaný formát odpovědi Podporuje se pouze json formát.

LatLongPairAbbreviated

Umístění vyjádřené jako zeměpisná šířka a délka pomocí krátkých názvů "lat" & "lon".

MatchType

Typy shody pro operaci zpětného vyhledávání adres

OperatingHours

Otevírací doba pro poi (body zájmu)

OperatingHoursTime

Představuje datum a čas.

OperatingHoursTimeRange

Otevřený časový rozsah pro den

PointOfInterest

Podrobnosti o vrácených poi, včetně informací, jako je jméno, telefon, adresa URL a klasifikace.

PointOfInterestCategorySet

Kategorie POI

QueryType

Typ vráceného dotazu: BLÍZKÉ nebo NON_NEAR.

Response

Výsledek dotazu. SearchAddressResult, pokud se dotaz úspěšně dokončil, v opačném případě ErrorResponse.

SearchAddressBatchItem

Položka vrácená voláním služby Batch adresy Search.

SearchAddressBatchProcessResult

Tento objekt se vrátí z úspěšného volání služby Batch adresy Search.

SearchAddressResultItem

Objekt Result pro odpověď rozhraní API Search.

SearchAddressResultType

Jedna z těchto možností:

• POI
• Ulice
• Geografie
• Adresa bodu
• Rozsah adres
• Křížová ulice

SearchSummary

Souhrnný objekt pro odpověď rozhraní API Search.

Summary

Souhrn výsledků žádosti o dávku