Route - Get Route Matrix

Reference

Služba:: Maps

Verze rozhraní API:: 1.0

Umožňuje získat matici tras zobrazující dobu cesty a vzdálenost pro všechny možné páry v seznamu původů a cílů.

Rozhraní Get Route Matrix API je požadavek HTTP GET , který vypočítá dobu cesty a vzdálenost pro všechny možné páry v seznamu původů a cílů. Na rozdíl od rozhraní API Pro získání trasy , které poskytuje podrobné pokyny k trase, se toto rozhraní API zaměřuje na efektivitu tím, že poskytuje náklady (čas a vzdálenost cesty) na směrování z každého zdroje do každého cíle. Další informace najdete v tématu Osvědčené postupy pro službu Azure Maps Route.

Pro každý daný zdroj služba vypočítá náklady na směrování z tohoto zdroje do každého daného cíle. Sadu původů a sadu cílů si lze představit jako záhlaví sloupců a řádků tabulky a každá buňka v tabulce obsahuje náklady na směrování ze zdroje do cíle pro danou buňku. Řekněme například, že společnost, která má rozvoz jídla, má 20 řidičů a potřebuje najít nejbližšího řidiče, který si vyzvedne dodávku z restaurace. K vyřešení tohoto případu použití můžou volat rozhraní API směrování matice.

Pro každou trasu se vrátí časy jízdy a vzdálenosti. Vypočítané náklady můžete použít k určení podrobných tras, které se mají vypočítat, pomocí rozhraní API Trasy.

Maximální velikost matice pro asynchronní požadavek je 700 a pro požadavek synchronizace je to 100 (počet původů vynásobený počtem cílů).

Odeslání synchronní žádosti o matici tras

Pokud váš scénář vyžaduje synchronní požadavky a maximální velikost matice je menší nebo rovna 100, možná budete chtít provést synchronní požadavek. Maximální velikost matice pro toto rozhraní API je 100 (počet původů vynásobený počtem cílů). S ohledem na toto omezení jsou příklady možných rozměrů matice: 10x10, 6x8, 9x8 (nemusí být čtvercové).

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

Odeslání asynchronního požadavku matice směrování

Asynchronní rozhraní API je vhodné pro zpracování velkých objemů relativně složitých požadavků směrování. 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 pro 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ě. Pokud waitForResults je parametr v požadavku nastavený na hodnotu true, uživatel obdrží odpověď 200, pokud je požadavek dokončen do 120 sekund.

Maximální velikost matice pro toto rozhraní API je 700 (počet původů vynásobený počtem cílů). S ohledem na toto omezení jsou příklady možných dimenzí matice: 50x10, 10x10, 28x25. 10x70 (nemusí být čtvercové).

Asynchronní odpovědi se ukládají po dobu 14 dnů. Adresa URL přesměrování vrátí odpověď 404, pokud se použije po uplynutí období vypršení platnosti.

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

Tady je typická posloupnost asynchronních operací:

Klient odešle požadavek GET matice tras do Služby Azure Maps.
Server odpoví jedním z následujících způsobů:

HTTP 202 Accepted – Byl přijat požadavek na matici směrování.

HTTP Error – Při zpracování požadavku Matice směrování došlo k chybě. Může se jednat o chybný požadavek 400 nebo jiný stavový kód chyby.
Pokud byl požadavek matice trasy úspěšně přijat, hlavička Location v odpovědi obsahuje adresu URL pro stažení výsledků požadavku. Tento identifikátor URI stavu vypadá takto:

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

Klient vydá požadavek GET na adresu URL pro stažení získanou v kroku 3, aby si stáhl výsledky.

Stáhnout výsledky synchronizace

Když vytvoříte požadavek GET pro rozhraní API pro synchronizaci matice tras, vrátí služba kód odpovědi 200 pro úspěšný požadavek a pole odpovědí. Tělo odpovědi bude obsahovat data a později nebude možné načíst výsledky.

Stáhnout asynchronní výsledky

Když požadavek vydá 202 Accepted odpověď, zpracovává se pomocí našeho asynchronního kanálu. Dostanete adresu URL ke kontrole průběhu asynchronního požadavku v hlavičce umístění odpovědi. Tento identifikátor URI stavu vypadá takto:

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

Adresa URL zadaná hlavičkou umístění vrátí následující odpovědi při GET vystavení požadavku.

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

HTTP 200 OK – Požadavek matice se úspěšně zpracoval. Text odpovědi obsahuje všechny výsledky.

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

Parametry identifikátoru URI

Name	V	Vyžadováno	Typ	Description
format	path	True	string	ID matice bylo přijato po úspěšném přijetí žádosti o trasu matice.
api-version	query	True	string	Číslo verze rozhraní API služby Azure Maps

Hlavička požadavku

Name	Vyžadováno	Typ	Description
x-ms-client-id		string	Určuje, který účet je určený pro použití ve spojení s modelem zabezpečení Microsoft Entra ID. Představuje jedinečné ID účtu Azure Maps a je možné ho načíst z rozhraní API účtu roviny správy Služby Azure Maps. Informace o použití zabezpečení Microsoft Entra ID v Azure Maps najdete v následujících článcích .

Odpovědi

Name	Typ	Description
200 OK	RouteMatrixResult	Požadavek matice byl úspěšně zpracován. Text odpovědi obsahuje všechny výsledky.
202 Accepted		Podporuje se pouze pro asynchronní požadavek. Žádost byla přijata: Žádost byla přijata ke zpracování. K opakování nebo získání přístupu k výsledkům použijte adresu URL v hlavičce umístění. Hlavičky Location: string
Other Status Codes	ErrorResponse	Došlo k neočekávané chybě.

Name

Typ

Description

200 OK

RouteMatrixResult

Požadavek matice byl úspěšně zpracován. Text odpovědi obsahuje všechny výsledky.

202 Accepted

Podporuje se pouze pro asynchronní požadavek. Žádost byla přijata: Žádost byla přijata ke zpracování. K opakování nebo získání přístupu k výsledkům použijte adresu URL v hlavičce umístění.

Hlavičky

Location: string

Other Status Codes

ErrorResponse

Došlo k neočekávané chybě.

Zabezpečení

AADToken

Toto jsou toky Microsoft Entra 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 rozhraním Azure Maps REST API. Řízení přístupu na základě role v Azure slouží k určení přístupu k jednomu nebo několika účtům prostředků nebo dílčím prostředkům Azure Maps. 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 několika oprávnění k rozhraním REST API služby Azure Maps.

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.

Poznámky

Tato definice zabezpečení vyžaduje použití hlavičky x-ms-client-id k označení prostředku Azure Maps, ke kterému aplikace žádá o přístup. Můžete ho získat z rozhraní MAPS MANAGEMENT API.

Je Authorization URL specifický pro instanci veřejného cloudu Azure. Suverénní cloudy mají jedinečné autorizační adresy URL a konfigurace Microsoft Entra ID. * Řízení přístupu na základě role v Azure se konfiguruje z roviny správy Azure prostřednictvím webu Azure Portal, PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API. * Použití sady Azure Maps Web SDK umožňuje nastavení aplikace na základě konfigurace pro více případů použití.

Další informace o platformě Microsoft Identity Platform najdete v tématu Přehled platformy Microsoft Identity Platform.

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

Rozsahy

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

subscription-key

Jedná se o sdílený klíč, který se zřídí při vytváření účtu Azure Maps na webu 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 rozhraním Rest API služby Azure Maps 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 prostředku Azure Maps prostřednictvím roviny správy 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

Successfully retrieve the status for a route matrix request

Ukázkový požadavek

HTTP

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

Ukázková odpověď

Stavový kó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
  }
}

Stavový kód:: 202

Definice

Name	Description
ErrorAdditionalInfo	Další informace o chybě správy prostředků
ErrorDetail	Podrobnosti o chybě
ErrorResponse	Chybová odpověď
RouteLegSummary	Souhrnný objekt pro oddíl trasy.
RouteMatrix	Objekt výsledku matice
RouteMatrixResult	Tento objekt je vrácen z úspěšného volání Matice směrování. Pokud jsou například k dispozici 2 počátky a 3 cíle, budou v každém z nich 2 pole se 3 prvky. Obsah jednotlivých elementů závisí na možnostech zadaných v dotazu.
RouteMatrixResultResponse	Objekt odpovědi aktuální buňky ve vstupní matici.
RouteMatrixSummary	Souhrnný objekt

ErrorAdditionalInfo

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

Name	Typ	Description
info	object	Další informace.
type	string	Typ další informace.

ErrorDetail

Podrobnosti o chybě

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Další informace o chybě.
code	string	Kód chyby
details	ErrorDetail[]	Podrobnosti o chybě.
message	string	Chybová zpráva
target	string	Cíl chyby.

ErrorResponse

Chybová odpověď

Name	Typ	Description
error	ErrorDetail	Objekt chyby.

RouteLegSummary

Souhrnný objekt pro oddíl trasy.

Name	Typ	Description
arrivalTime	string	Odhadovaný čas příjezdu na trasu nebo úsek. Čas je ve standardu UTC.
batteryConsumptionInkWh	number	Odhadovaná spotřeba elektrické energie v kilowatthodinách (kWh) s využitím modelu elektrické spotřeby Zahrnuje, pokud je vlastnost vehicleEngineType nastavená na elektrický a je zadána konstantaSpeedConsumptionInkWhPerHundredkm. Hodnota batteryConsumptionInkWh zahrnuje recuperated elektrickou energii, a proto může být negativní (což značí získávání energie). Pokud jsou zadány hodnoty maxChargeInkWh i currentChargeInkWh, bude rekuperace omezena, aby se zajistilo, že úroveň nabití baterie nikdy nepřekročí maxChargeInkWh. Pokud není zadána hodnota maxChargeInkWh ani currentChargeInkWh, předpokládá se ve výpočtu spotřeby neomezená rekuperace.
departureTime	string	Odhadovaný čas odjezdu trasy nebo úseku. Čas je ve standardu UTC.
fuelConsumptionInLiters	number	Odhadovaná spotřeba paliva v litrech pomocí modelu spotřeby spalování. Zahrnuje, pokud je vlastnost vehicleEngineType nastavená na spalování a je zadána konstantaSpeedConsumptionInLitersPerHundredkm. Hodnota nebude záporná.
historicTrafficTravelTimeInSeconds	integer	Odhadovaná doba trvání cesty vypočítaná na základě historických dopravních dat závislých na čase Zahrne se jenom v případě, že se v dotazu použije computeTravelTimeFor = all.
lengthInMeters	integer	Vlastnost Length In Meters
liveTrafficIncidentsTravelTimeInSeconds	integer	Odhadovaná doba trvání cesty vypočítaná pomocí dat o rychlosti v reálném čase Zahrne se jenom v případě, že se v dotazu použije computeTravelTimeFor = all.
noTrafficTravelTimeInSeconds	integer	Odhadovaná doba trvání cesty vypočítaná, jako by na trase nedošlo k žádnému zpoždění kvůli dopravním podmínkám (např. zahlcení). Zahrne se jenom v případě, že se v dotazu použije computeTravelTimeFor = all.
trafficDelayInSeconds	integer	Odhadované zpoždění v sekundách způsobené incidenty v reálném čase podle informací o provozu U tras plánovaných s časem odjezdu v budoucnu je zpoždění vždy 0. Pokud chcete vrátit další doby cesty pomocí různých typů informací o provozu, je potřeba přidat parametr computeTravelTimeFor=all.
travelTimeInSeconds	integer	Odhadovaná doba trvání cesty v sekundách, která zahrnuje zpoždění způsobené provozem v reálném čase. Mějte na paměti, že i když traffic=false travelTimeInSeconds stále zahrnuje zpoždění způsobené provozem. Pokud je DepartAt v budoucnosti, doba trvání cesty se počítá na základě historických dopravních dat závislých na čase.

RouteMatrix

Objekt výsledku matice

Name	Typ	Description
response	RouteMatrixResultResponse	Objekt odpovědi aktuální buňky ve vstupní matici.
statusCode	integer	StatusCode Vlastnost pro aktuální buňku ve vstupní matici.

RouteMatrixResult

Tento objekt je vrácen z úspěšného volání Matice směrování. Pokud jsou například k dispozici 2 počátky a 3 cíle, budou v každém z nich 2 pole se 3 prvky. Obsah jednotlivých elementů závisí na možnostech zadaných v dotazu.

Name	Typ	Description
formatVersion	string	Vlastnost Formát verze
matrix	RouteMatrix[]	Výsledky jako 2rozměrné pole souhrnů tras.
summary	RouteMatrixSummary	Souhrnný objekt

RouteMatrixResultResponse

Objekt odpovědi aktuální buňky ve vstupní matici.

Name	Typ	Description
routeSummary	RouteLegSummary	Souhrnný objekt pro oddíl trasy.

RouteMatrixSummary

Souhrnný objekt

Name	Typ	Description
successfulRoutes	integer	Počet úspěšných tras v odpovědi
totalRoutes	integer	Celkový počet požadovaných tras Počet buněk ve vstupní matici

Sdílet prostřednictvím

Route - Get Route Matrix

Odeslání synchronní žádosti o matici tras

Odeslání asynchronního požadavku matice směrování

Stáhnout výsledky synchronizace

Stáhnout asynchronní výsledky

Parametry identifikátoru URI

Hlavička požadavku

Odpovědi

Zabezpečení

AADToken

Poznámky

Rozsahy

subscription-key

SAS Token

Příklady

Successfully retrieve the status for a route matrix request

Ukázkový požadavek

Ukázková odpověď

Definice

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Další materiály