Route - Get Route Matrix

Referencia

Szolgáltatás:: Maps

API-verzió:: 1.0

Egy útvonalmátrix lekérésére használható, amely az összes lehetséges pár utazási idejét és távolságát mutatja a forrás- és úti célok listájában.

Megjegyzés

Azure Maps Route 1-es szolgáltatás kivonási

Az Azure Maps Route v1 szolgáltatás elavult, és 28.31-én megszűnik. A szolgáltatáskimaradások elkerülése érdekében a Route v1 szolgáltatás minden hívását frissíteni kell, hogy Route v2025-01-01 szolgáltatást használhassa 2028. 03. 31-ig. További információ: Migrate Azure Maps Route 1.0 API-k.

A Get Route Matrix API egy HTTP-GET-kérés, amely kiszámítja az összes lehetséges pár utazási idejét és távolságát a forrás- és úti célok listájában. A Útvonaltervek lekérése API-val ellentétben, amely részletes útvonalutasításokat biztosít, ez az API a hatékonyságra összpontosít azáltal, hogy az útválasztás költségeit (utazási idejét és távolságát) az egyes forrásoktól minden célig biztosítja. További információ: Ajánlott eljárások az Azure Maps Route szolgáltatáshoz.

A szolgáltatás minden adott forrás esetében kiszámítja az adott forrástól az adott célhelyig történő útválasztás költségét. A forráskészletet és a célhelykészletet úgy lehet elképzelni, mint egy tábla oszlop- és sorfejléceit, és a táblázat minden cellái tartalmazzák az adott cella forrásától a célhelyig történő útválasztás költségeit. Tegyük fel például, hogy egy ételkézbesítési vállalatnak 20 sofőrje van, és meg kell találniuk a legközelebbi sofőrt, aki felveszi a szállítást az étteremből. A használati eset megoldásához meghívhatják a Matrix Route API-t.

Minden útvonal esetében a rendszer visszaadja az utazási időket és a távolságokat. A kiszámított költségek alapján meghatározhatja, hogy mely részletes útvonalakat számítsa ki a Route Directions API használatával.

Az aszinkron kérelmek mátrixának maximális mérete 700, szinkronizálási kérelem esetén pedig 100 (a források száma és a célhelyek száma).

Szinkron útvonalmátrix-kérelem elküldése

Ha a forgatókönyv szinkron kéréseket igényel, és a mátrix maximális mérete kisebb vagy egyenlő 100-nál, érdemes lehet szinkron kérést küldeni. Az API-hoz tartozó mátrix maximális mérete 100 (a források száma és a célhelyek számának szorzata). Ezt a kényszert szem előtt tartva a lehetséges mátrixdimenziók például a következők: 10x10, 6x8, 9x8 (nem kell négyzetnek lennie).

GET https://atlas.microsoft.com/route/matrix/sync/json?api-version=1.0&subscription-key={subscription-key}

Aszinkron útvonalmátrix-kérelem küldése

Az Aszinkron API alkalmas a viszonylag összetett útválasztási kérések nagy mennyiségének feldolgozására. 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. Ha waitForResults kérelem paramétere igaz, a felhasználó 200 választ kap, ha a kérés 120 másodperc alatt befejeződött.

Az API-hoz tartozó mátrix maximális mérete 700 (a források száma és a célhelyek számának szorzata). Ezt a kényszert szem előtt tartva a lehetséges mátrixdimenziók például a következők: 50x10, 10x10, 28x25. 10x70 (nem kell négyzet).

Az aszinkron válaszok tárolása 24 órán keresztül történik . Az átirányítási URL 404-választ ad vissza, ha a lejárati idő után használják.

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

Az aszinkron műveletek jellemző sorrendje a következő:

Az ügyfél útválasztási mátrix GET kérést küld az Azure Mapsnek
A kiszolgáló a következők egyikével válaszol:

HTTP 202 Accepted – Az útvonalmátrix kérése elfogadva.

HTTP Error – Hiba történt az útvonalmátrix-kérelem feldolgozása során. Ez lehet egy 400-ás hibás kérés vagy bármely más hibaállapot-kód.
Ha a mátrixútvonal-kérést sikeresen elfogadták, a válasz Hely fejléce tartalmazza a kérelem eredményeinek letöltéséhez használt URL-címet. Az állapot URI-ja a következőhöz hasonlóan néz ki:

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}

Az ügyfél get kérést ad ki a 3. lépésben beszerzett letöltési URL-címre az eredmények letöltéséhez

Szinkronizálási eredmények letöltése

Amikor GET kérést küld a Route Matrix Sync API-hoz, a szolgáltatás 200 válaszkódot ad vissza a sikeres kéréshez és egy választömbhöz. A válasz törzse tartalmazni fogja az adatokat, és később nem lesz lehetőség az eredmények lekérésére.

Aszinkron eredmények letöltése

Amikor egy kérés 202 Accepted választ ad ki, a kérés feldolgozása az aszinkron folyamatunkkal történik. Egy URL-címet kap, amely ellenőrzi az aszinkron kérés előrehaladását a válasz helyfejlécében. Az állapot URI-ja a következőhöz hasonlóan néz ki:

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}

A hely fejléce által megadott URL-cím a következő válaszokat adja vissza GET kérés kiadásakor.

HTTP 202 Accepted – A mátrixkérelem elfogadva, de még folyamatban van. Próbálkozzon újra egy ideig.

HTTP 200 OK – A mátrixkérés feldolgozása sikeresen megtörtént. A válasz törzse tartalmazza az összes eredményt.

GET https://atlas.microsoft.com/route/matrix/{format}?api-version=1.0

URI-paraméterek

Name	In	Kötelező	Típus	Description
format	path	True	string	A mátrixútvonal-kérelem sikeres elfogadása után kapott mátrixazonosító.
api-version	query	True	string	Az Azure Maps API verziószáma.

Kérelem fejléce

Name	Kötelező	Típus	Description
x-ms-client-id		string	Megadja, hogy melyik fiók legyen a Microsoft Entra ID biztonsági modellel együtt használva. Az Azure Maps-fiók egyedi azonosítóját jelöli, amely az Azure Maps felügyeleti sík fiók API-jából kérhető le. A Microsoft Entra ID-biztonság Azure Mapsben való használatához az alábbi cikkeket útmutatásért.

Válaszok

Name	Típus	Description
200 OK	RouteMatrixResult	A mátrixkérés feldolgozása sikeresen megtörtént. A válasz törzse tartalmazza az összes eredményt.
202 Accepted		Csak aszinkron kérés esetén támogatott. Kérelem elfogadva: A kérelem feldolgozásra lett elfogadva. Az eredmények újrapróbálkozásához vagy eléréséhez használja a Helyfejléc URL-címét. Fejlécek Location: string
Other Status Codes	ErrorResponse	Váratlan hiba történt.

Name

Típus

Description

200 OK

RouteMatrixResult

A mátrixkérés feldolgozása sikeresen megtörtént. A válasz törzse tartalmazza az összes eredményt.

202 Accepted

Csak aszinkron kérés esetén támogatott. Kérelem elfogadva: A kérelem feldolgozásra lett elfogadva. Az eredmények újrapróbálkozásához vagy eléréséhez használja a Helyfejléc URL-címét.

Fejlécek

Location: string

Other Status Codes

ErrorResponse

Váratlan hiba történt.

Biztonság

AADToken

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

Forgatókönyvek implementálásához javasoljuk, hogy tekintse meg hitelesítési fogalmakat. Összefoglalva, ez a biztonsági definíció megoldást kínál az alkalmazások modellezésére olyan objektumokon keresztül, amelyek hozzáférés-vezérlésre képesek adott API-kon és hatókörökön.

Jegyzetek

Ez a biztonsági definíciós megköveteli, hogy a x-ms-client-id fejléc használatával jelezze, hogy melyik Azure Maps-erőforráshoz kér hozzáférést az alkalmazás. Ez a Maps felügyeleti API-érhető el.

A Authorization URL az Azure nyilvános felhőpéldányára jellemző. A szuverén felhők egyedi engedélyezési URL-címekkel és Microsoft Entra-azonosító konfigurációkkal rendelkeznek. * Az Azure szerepköralapú hozzáférés-vezérlés a Azure felügyeleti síkjáról van konfigurálva, az Azure Portalon, a PowerShellen, a parancssori felületen, az Azure SDK-kon vagy REST API-kon keresztül. * Az Azure Maps Web SDK használata lehetővé teszi egy alkalmazás konfigurációalapú beállítását több használati esethez.

További információ a Microsoft identitásplatformról: Microsoft Identitásplatform áttekintése.

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

Hatókörök

Name	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Ez egy megosztott kulcs, amely akkor lesz kiépítve, ha Azure Maps-fiók létrehozása az Azure Portalon, 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.

A nyilvánosan közzétett alkalmazások esetében javasoljuk, hogy használja a bizalmas ügyfélalkalmazásokat, megközelítést az 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 a Azure Maps-erőforráson az Azure felügyeleti síkon keresztül az Azure Portalon, a PowerShellen, a parancssori felületen, az Azure SDK-kon vagy a REST API-kon keresztül.

Ezzel a jogkivonattal minden alkalmazás jogosult az Azure szerepköralapú hozzáférés-vezérlőivel való hozzáférésre, valamint az adott jogkivonat lejáratának, sebességének és régióinak részletes szabályozására. Más szóval az SAS-jogkivonat segítségével az alkalmazások biztonságosabban szabályozhatják a hozzáférést, mint a megosztott kulcs.

A nyilvánosan közzétett alkalmazások esetében javasoljuk, hogy konfigurálja a -fiók erőforrás- engedélyezett forrásainak listáját a renderelési visszaélések korlátozása és az SAS-jogkivonat rendszeres megújítása érdekében.

Típus: apiKey
In: header

Példák

Successfully retrieve the status for a route matrix request

Mintakérelem

HTTP

GET https://atlas.microsoft.com/route/matrix/11111111-2222-3333-4444-555555555555?api-version=1.0

Mintaválasz

Állapotkód:: 200

{
  "formatVersion": "0.0.1",
  "matrix": [
    [
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 495,
            "travelTimeInSeconds": 134,
            "trafficDelayInSeconds": 0,
            "departureTime": "2018-07-27T22:55:29+00:00",
            "arrivalTime": "2018-07-27T22:57:43+00:00"
          }
        }
      },
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 647651,
            "travelTimeInSeconds": 26835,
            "trafficDelayInSeconds": 489,
            "departureTime": "2018-07-27T22:55:29+00:00",
            "arrivalTime": "2018-07-28T06:22:44+00:00"
          }
        }
      }
    ],
    [
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 338,
            "travelTimeInSeconds": 104,
            "trafficDelayInSeconds": 0,
            "departureTime": "2018-07-27T22:55:29+00:00",
            "arrivalTime": "2018-07-27T22:57:13+00:00"
          }
        }
      },
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 647494,
            "travelTimeInSeconds": 26763,
            "trafficDelayInSeconds": 469,
            "departureTime": "2018-07-27T22:55:29+00:00",
            "arrivalTime": "2018-07-28T06:21:32+00:00"
          }
        }
      }
    ]
  ],
  "summary": {
    "successfulRoutes": 4,
    "totalRoutes": 4
  }
}

Állapotkód:: 202

Definíciók

Name	Description
ErrorAdditionalInfo	Az erőforrás-kezelési hiba további információi.
ErrorDetail	A hiba részletei.
ErrorResponse	Hibaválasz
RouteLegSummary	Az útvonalszakasz összefoglaló objektuma.
RouteMatrix	Mátrix eredményobjektuma
RouteMatrixResult	Ezt az objektumot egy sikeres útvonalmátrix-hívás adja vissza. Ha például 2 forrást és 3 célhelyet adnak meg, akkor 2 tömb lesz, amelyekben 3 elem található. Az egyes elemek tartalma a lekérdezésben megadott beállításoktól függ.
RouteMatrixResultResponse	Az aktuális cella válaszobjektuma a bemeneti mátrixban.
RouteMatrixSummary	Összegző objektum

ErrorAdditionalInfo

Objektum

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

Name	Típus	Description
info	object	A további információk.
type	string	A további információtípus.

ErrorDetail

Objektum

A hiba részletei.

Name	Típus	Description
additionalInfo	ErrorAdditionalInfo[]	A hiba további információi.
code	string	A hibakód.
details	ErrorDetail[]	A hiba részletei.
message	string	A hibaüzenet.
target	string	A hibacél.

ErrorResponse

Objektum

Hibaválasz

Name	Típus	Description
error	ErrorDetail	A hibaobjektum.

RouteLegSummary

Objektum

Az útvonalszakasz összefoglaló objektuma.

Name	Típus	Description
arrivalTime	string (date-time)	Az útvonal vagy a láb becsült érkezési ideje. Az idő UTC-ben van.
batteryConsumptionInkWh	number (double)	Becsült elektromos energiafogyasztás kilowattóra (kWh) alatt az elektromos fogyasztási modell használatával. Tartalmazza, ha a vehicleEngineType elektromos és constantSpeedConsumptionInkWhPerHundredkm értékre van állítva. Az batteryConsumptionInkWh értéke magában foglalja a visszaszerelt elektromos energiát, ezért negatív lehet (ami az energianövekedést jelzi). Ha a maxChargeInkWh és a currentChargeInkWh is meg van adva, a rendszer leképezi az újrafeltöltést, hogy az akkumulátor töltöttségi szintje soha ne haladja meg a maxChargeInkWh értéket. Ha sem a maxChargeInkWh, sem a currentChargeInkWh nincs megadva, akkor a rendszer nem konvenciókon alapuló újrafelvételt feltételez a felhasználás kiszámításában.
departureTime	string (date-time)	Az útvonal vagy a láb becsült indulási ideje. Az idő UTC-ben van.
fuelConsumptionInLiters	number (double)	Becsült üzemanyag-fogyasztás literben az égési fogyasztási modell használatával. Tartalmazza, ha a vehicleEngineType égési van beállítva, és konstansSpeedConsumptionInLitersPerHundredkm van megadva. Az érték nem lesz negatív.
historicTrafficTravelTimeInSeconds	integer	Az időfüggő korábbi forgalmi adatok alapján kiszámított becsült utazási idő. Csak akkor tartalmazza, ha a computeTravelTimeFor = az összeset használja a lekérdezésben.
lengthInMeters	integer	Hossz a Meters tulajdonságban
liveTrafficIncidentsTravelTimeInSeconds	integer	Valós idejű sebességadatokkal kiszámított becsült utazási idő. Csak akkor tartalmazza, ha a computeTravelTimeFor = az összeset használja a lekérdezésben.
noTrafficTravelTimeInSeconds	integer	Becsült utazási idő úgy számítva, mintha a forgalmi körülmények (pl. torlódás) miatt nem történnek késések az útvonalon. Csak akkor tartalmazza, ha a computeTravelTimeFor = az összeset használja a lekérdezésben.
trafficDelayInSeconds	integer	A valós idejű incidens(ek) által okozott becsült késés másodpercben a forgalmi információk alapján. A jövőben indulási idővel tervezett útvonalak esetében a késés mindig 0. Ha több utazási időt szeretne visszaadni különböző típusú forgalmi adatok használatával, a computeTravelTimeFor=összes paramétert hozzá kell adni.
travelTimeInSeconds	integer	Becsült utazási idő másodpercben tulajdonság, amely magában foglalja a késés miatt valós idejű forgalom. Vegye figyelembe, hogy még akkor is, ha a traffic=false travelTimeInSeconds továbbra is tartalmazza a forgalom miatti késést. Ha a DepartAt a jövőben lesz, az utazási idő az időfüggő korábbi forgalmi adatok alapján lesz kiszámítva.

RouteMatrix

Objektum

Mátrix eredményobjektuma

Name	Típus	Description
response	RouteMatrixResultResponse	Az aktuális cella válaszobjektuma a bemeneti mátrixban.
statusCode	integer	A bemeneti mátrix aktuális cellájának StatusCode tulajdonsága.

RouteMatrixResult

Objektum

Ezt az objektumot egy sikeres útvonalmátrix-hívás adja vissza. Ha például 2 forrást és 3 célhelyet adnak meg, akkor 2 tömb lesz, amelyekben 3 elem található. Az egyes elemek tartalma a lekérdezésben megadott beállításoktól függ.

Name	Típus	Description
formatVersion	string	Verzió formázása tulajdonság
matrix	RouteMatrix[]	Az eredmények útvonal-összefoglalók 2 dimenziós tömbjeként szolgálnak.
summary	RouteMatrixSummary	Összegző objektum

RouteMatrixResultResponse

Objektum

Az aktuális cella válaszobjektuma a bemeneti mátrixban.

Name	Típus	Description
routeSummary	RouteLegSummary	Az útvonalszakasz összefoglaló objektuma.

RouteMatrixSummary

Objektum

Összegző objektum

Name	Típus	Description
successfulRoutes	integer	A válaszban szereplő sikeres útvonalak száma.
totalRoutes	integer	A kért útvonalak teljes száma. A bemeneti mátrix celláinak száma.

Megosztás a következőn keresztül:

Route - Get Route Matrix

Szinkron útvonalmátrix-kérelem elküldése

Aszinkron útvonalmátrix-kérelem küldése

Szinkronizálási eredmények letöltése

Aszinkron eredmények letöltése

URI-paraméterek

Kérelem fejléce

Válaszok

Biztonság

AADToken

Jegyzetek

Hatókörök

subscription-key

SAS Token

Példák

Successfully retrieve the status for a route matrix request

Mintakérelem

Mintaválasz

Definíciók

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary