Search - Post Search Address Batch

A használatával lekérdezések kötegét küldheti el a Keresés Address API-nak egyetlen aszinkron kérésben.
Az Post Search Address Batch API egy HTTP-kérésPOST, amely lekérdezések kötegeit küldi Keresés Address API-nak egyetlen szinkron API-hívásban. Meghívhatja Keresés Address Batch API-t aszinkron (aszinkron) vagy szinkron (szinkronizálási) futtatáshoz. Az aszinkron API lehetővé teszi, hogy a hívó legfeljebb 10 000 lekérdezést kötenek össze, és akár 100 lekérdezést szinkronizáljon az API-val.

Szinkron batch-kérelem elküldése

A szinkron API használata egyszerű kötegelt kérésekhez ajánlott. Amikor a szolgáltatás kérést kap, a batch-elemek kiszámítása után azonnal válaszol, és később nem lesz lehetőség az eredmények lekérésére. A szinkron API időtúllépési hibát (408-ra adott válasz) ad vissza, ha a kérés 60 másodpercnél tovább tart. Ehhez az API-hoz a kötegelemek száma 100-ra van korlátozva.

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

Aszinkron Batch-kérelem elküldése

Az aszinkron API alkalmas nagy mennyiségű, viszonylag összetett keresési kérés feldolgozására

• Lehetővé teszi az eredmények lekérését egy külön hívásban (több letöltés is lehetséges).
• Az aszinkron API megbízhatóságra van optimalizálva, és várhatóan nem fog időtúllépésbe ütközni.
• Ehhez az API-hoz a kötegelemek száma legfeljebb 10 000 lehet.

Ha aszinkron kéréssel küld kérést, a szolgáltatás alapértelmezés szerint egy 202-s válaszkódot ad vissza egy átirányítási URL-cím mentén a válaszfejléc Hely mezőjében. Ezt az URL-címet rendszeres időközönként ellenőrizni kell, amíg a válaszadatok vagy a hibaadatok nem érhetők el. Az aszinkron válaszok tárolása 14 napig történik. Az átirányítási URL-cím 404-et ad vissza, ha a lejárati idő után használják.

Vegye figyelembe, hogy az aszinkron kötegelt kérés hosszú ideig futó művelet. Íme egy tipikus műveletsor:

1. Az ügyfél Keresés Cím Batch-kérést POST küld a Azure Maps.

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

2. A kiszolgáló az alábbiak egyikével válaszol:

   HTTP 202 Accepted – A Batch-kérelem el lett fogadva.

   HTTP Error – Hiba történt a Batch-kérelem feldolgozása során. Ez lehet egy 400 Bad Request vagy bármely más Error állapotkód.

3. Ha a kötegkérelmet sikeresen elfogadták, a Location válasz fejléce tartalmazza a kötegelt kérelem eredményeinek letöltésére vonatkozó URL-címet. Az állapot URI-ja a következőképpen néz ki:

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

4. Az ügyfél kérést GET küld a 3. lépésben beszerzett letöltési URL-címre a kötegelt eredmények letöltéséhez.

POST törzs a Batch-kérelemhez

A keresési cím lekérdezéseinek elküldéséhez olyan kérést POST kell használnia, amelyben a kérelem törzse json formátumban fogja tartalmazni a batchItems tömböt, a fejléc pedig értékre Content-Typeapplication/jsonlesz állítva. Íme egy mintakérés törzse, amely 5 keresési címlekérdezést tartalmaz:

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

A kötegekben található keresési cím lekérdezések csak részleges URL-címek a protokoll, az alap URL-cím, az elérési út, az api-verzió és az előfizetési kulcs nélkül . A támogatott keresési címekURI-paramétereinek bármelyikét elfogadhatja. A keresési cím lekérdezésében szereplő sztringértékeket megfelelően kell feloldani (például a " karaktert a \ karakterrel kell feloldani), és megfelelő URL-kódolásúnak kell lennie.

Az aszinkron API lehetővé teszi, hogy a hívó legfeljebb 10 000 lekérdezést kötenek össze, és legfeljebb 100 lekérdezést szinkronizáljon az API-val, és a kötegnek legalább 1 lekérdezést kell tartalmaznia.

Aszinkron Batch-eredmények letöltése

Az aszinkron kötegeredmények letöltéséhez kérést GET küld a kötegletöltési végpontnak. Ez a Locationletöltési URL-cím lekérhető egy sikeres POST kötegelt kérelem fejlécéből, és a következőképpen néz ki:

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

A kötegeredmények letöltésének tipikus műveletsorai a következők:

1. Az ügyfél kérést GET küld a letöltési URL-cím használatával.

2. A kiszolgáló az alábbiak egyikével válaszol:

   HTTP 202 Accepted – A Batch-kérést elfogadták, de még folyamatban van a feldolgozás. Próbálkozzon újra egy ideig.

   HTTP 200 OK – A Batch-kérelem feldolgozása sikerült. A válasz törzse tartalmazza az összes kötegelt eredményt.

Batch-válaszmodell

A visszaadott adattartalom hasonló az aszinkron és szinkronizálási kérelmekhez. Az aszinkron kötegkérelem eredményeinek letöltésekor, ha a köteg feldolgozása befejeződött, a válasz törzse tartalmazza a kötegelt választ. Ez a kötegelt válasz tartalmaz egy summary összetevőt, amely azt jelzi, hogy az totalRequests eredeti kötegkérelm successfulRequestsrészét képezte, azaz a sikeresen végrehajtott lekérdezéseket. A batch-válasz egy batchItems tömböt is tartalmaz, amely a batch-kérelem minden egyes lekérdezésére választ tartalmaz. A batchItems pontosan ugyanabban a sorrendben tartalmazza az eredményeket, mint az eredeti lekérdezéseket a kötegelt kérelemben. Minden elem tartalmaz batchItemsstatusCode és response mezőket. Mindegyik response a batchItems következő típusok egyikét tartalmazza:

• SearchAddressResult – Ha a lekérdezés sikeresen befejeződött.

• Error – Ha a lekérdezés sikertelen volt. A válasz ebben az esetben egy code és egy message elemet fog tartalmazni.

Íme egy minta Batch-válasz 2 sikeres és 1 sikertelen eredménnyel:

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

URI-paraméterek

Kérelem fejléce

Kérelem törzse

Válaszok

Biztonság

AADToken

Ezek a Microsoft Entra OAuth 2.0-folyamatok. Az Azure-beli szerepköralapú hozzáférés-vezérléssel párosítva Azure Maps REST API-khoz való hozzáférés vezérlésére használható. Az Azure szerepköralapú hozzáférés-vezérlése egy vagy több Azure Maps erőforrásfiókhoz vagy alerőforráshoz való hozzáférés kijelölésére szolgál. Bármely felhasználó, csoport vagy szolgáltatásnév hozzáférést kaphat egy beépített szerepkörrel vagy egy vagy több rest API-Azure Maps ra vonatkozó engedélyből álló egyéni szerepkörrel.

A forgatókönyvek implementálásához javasoljuk, hogy tekintse meg a hitelesítési fogalmakat. Összefoglalva, ez a biztonsági definíció megoldást nyújt az alkalmazás(ok) adott API-k és hatókörök hozzáférés-vezérlésére képes objektumokon keresztüli modellezésére.

Típus: oauth2
Folyamat: implicit
Engedélyezési URL: https://login.microsoftonline.com/common/oauth2/authorize

Hatókörök

subscription-key

Ez egy megosztott kulcs, amely akkor lesz kiépítve, ha Azure Maps fiókot hoz létre a Azure Portal vagy PowerShell, CLI, Azure SDK vagy REST API használatával.

Ezzel a kulccsal bármely alkalmazás hozzáférhet az összes REST API-hoz. Más szóval ez a kulcs használható főkulcsként abban a fiókban, amelyben ki vannak adva.

Nyilvánosan közzétett alkalmazások esetén javasoljuk, hogy a bizalmas ügyfélalkalmazások megközelítését használja Azure Maps REST API-k eléréséhez, hogy a kulcs biztonságosan tárolható legyen.

Típus: apiKey
In: query

SAS Token

Ez egy közös hozzáférésű jogosultságkód-jogkivonat a listázási SAS műveletből jön létre az Azure Maps erőforráson keresztül az Azure felügyeleti síkján keresztül Azure Portal, PowerShell, CLI, Azure SDK-k vagy REST API-k használatával.

Ezzel a jogkivonattal minden alkalmazás jogosult hozzáférni az Azure szerepköralapú hozzáférés-vezérlőihez, valamint az adott jogkivonathoz használt lejárati időhöz, sebességhez és régióhoz. Más szóval az SAS-jogkivonattal az alkalmazások a megosztott kulcsnál biztonságosabb módon szabályozhatják a hozzáférést.

Nyilvánosan közzétett alkalmazások esetében javasoljuk, hogy konfiguráljon egy adott listát az engedélyezett forrásokról a térképfiók-erőforráson a leképezési visszaélések korlátozásához és az SAS-jogkivonat rendszeres megújításához.

Típus: apiKey
In: header

Példák

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.

Definíciók

Address

Az eredmény címe

AddressRanges

Az utca mindkét oldalán található címtartományt ismerteti a keresési eredményhez. A címtartomány kezdő és záró helyének koordinátáit tartalmazza.

BatchRequest

Ez a típus a Batch szolgáltatás kérelemtörzsét jelöli.

BatchRequestItem

Batch-kérelemobjektum

BoundingBox

A nézetport bal felső és jobb alsó koordinátái által képviselt eredményt lefedő nézetport.

BoundingBoxCompassNotation

A hely határolókerete.

Brand

A POI-hoz társított márka

Classification

A visszaadott POI besorolása

ClassificationName

A besorolás neve

DataSources

Nem kötelező szakasz. Referenciaazonosítók a Get Keresés Polygon API-hoz.

Entity

A határolókeret entitástípus-forrása. Fordított geokódolás esetén ez mindig egyenlő a pozícióval.

EntryPoint

A visszaadott POI belépési pontja.

EntryPointType

A belépési pont típusa. Az érték lehet fő vagy alérték.

ErrorAdditionalInfo

Az erőforrás-kezelési hiba további információi.

ErrorDetail

A hiba részletei.

ErrorResponse

Hibaválasz

GeographicEntityType

Földrajzi entitás típusa. Csak akkor jelenik meg, ha az entityType kérése megtörtént, és elérhető.

Geometry

Információ az eredmény geometriai alakjáról. Csak akkor jelenik meg, ha a típus == Földrajzi hely.

JsonFormat

A válasz kívánt formátuma. Csak json a formátum támogatott.

LatLongPairAbbreviated

Földrajzi szélességként és hosszúságként jelölt hely, "lat" rövid nevek használatával & "lon".

MatchType

A fordított címkeresési művelet egyezésének típusai.

OperatingHours

A POI nyitvatartási ideje (érdekes pontok).

OperatingHoursTime

Dátumot és időpontot jelöl

OperatingHoursTimeRange

Nyitott időtartomány egy napra

PointOfInterest

A visszaadott POI részletei, beleértve az olyan információkat, mint a név, a telefon, az URL-cím és a besorolások.

PointOfInterestCategorySet

POI-kategória

QueryType

A visszaadott lekérdezés típusa: KÖZELI vagy NON_NEAR.

Response

A lekérdezés eredménye. SearchAddressResult ha a lekérdezés sikeresen befejeződött, az ErrorResponse egyéb módon.

SearchAddressBatchItem

Az Keresés Address Batch szolgáltatáshívásából visszaadott elem.

SearchAddressBatchProcessResult

Ezt az objektumot egy sikeres Keresés Batch-szolgáltatáshívás adja vissza.

SearchAddressResultItem

Eredményobjektum egy Keresés API-válaszhoz.

SearchAddressResultType

Az alábbiak egyike:

• POI
• Utca
• Földrajzi hely
• Pont címe
• Címtartomány
• Kereszt utca

SearchSummary

Egy Keresés API-válasz összefoglaló objektuma.

Summary

A kötegelt kérelem eredményeinek összegzése