Route - Get Route Matrix
Umožňuje získat matici tras zobrazující čas a vzdálenost cesty pro všechny možné páry v seznamu původu a cílů.
Rozhraní API Get Route Matrix
je požadavek HTTP GET
, který vypočítá dobu cesty a vzdálenost pro všechny možné páry v seznamu původu a cílů. Na rozdíl od rozhraní Get Route Directions API, které poskytují podrobné pokyny pro trasy, se toto rozhraní API zaměřuje na efektivitu tím, že poskytuje náklady na směrování (dobu cesty a vzdálenost) 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ý zdroj vypočítá služba náklady na směrování z tohoto zdroje do každého daného cíle. Sadu původů a množiny cílů si můžete 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 dané buňky. Řekněme například, že společnost pro dodávku potravin má 20 řidičů a musí najít nejbližšího řidiče, který má vyzvednout dodávku z restaurace. K vyřešení tohoto případu použití můžou volat rozhraní API pro směrování matice.
Pro každou trasu se vrátí doba jízdy a vzdálenosti. Pomocí vypočítaných nákladů můžete určit, které podrobné trasy se mají vypočítat pomocí rozhraní API Směr trasy.
Maximální velikost matice pro asynchronní požadavek je 700 a pro žádost o synchronizaci je 100 (počet původů vynásobený počtem cílů).
Odeslat synchronní požadavek na 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 dimenzí 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í požadavku na asynchronní matici tras
Asynchronní rozhraní API je vhodné pro zpracování velkých objemů relativně složitých požadavků směrování. Když provedete požadavek pomocí asynchronního požadavku, služba ve výchozím nastavení vrátí kód odpovědi 202 podél adresy URL přesměrování v poli Umístění hlavičky odpovědi. Tato adresa URL by se měla pravidelně kontrolovat, dokud nebudou k dispozici data odpovědí nebo informace o chybě. Pokud je parametr waitForResults
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 24 hodin. Adresa URL pro přesměrování vrátí odpověď 404, pokud se použije po uplynutí doby 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 směrovací matice do Služby Azure Maps.
Server odpoví jedním z následujících způsobů:
HTTP
202 Accepted
– Požadavek matice směrování byl přijat.HTTP
Error
– Při zpracování požadavku Route Matrix došlo k chybě. Může se jednat o chybný požadavek 400 nebo jakýkoli jiný stavový kód chyby.Pokud byl požadavek na maticovou trasu úspěšně přijat, hlavička Umístění 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 pro stažení výsledků.
Stažení výsledků synchronizace
Když provedete požadavek GET pro rozhraní API pro synchronizaci matice směrování, 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é výsledky načíst.
Stažení asynchronních výsledků
Když žádost vydá odpověď 202 Accepted
, požadavek se zpracovává pomocí našeho asynchronního kanálu. Dostanete adresu URL, abyste zkontrolovali průběh 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 vydání GET
požadavku.
HTTP
202 Accepted
– Maticový požadavek byl přijat, ale stále se zpracovává. Zkuste to prosím znovu za nějakou dobu.
HTTP
200 OK
– požadavek matice byl úspěšně zpracován. 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í požadavku na trasu matice. |
api-version
|
query | True |
string |
Číslo verze rozhraní API služby Azure Maps |
Hlavička požadavku
Odpovědi
Name | Typ | Description |
---|---|---|
200 OK |
Maticový požadavek byl úspěšně zpracován. Text odpovědi obsahuje všechny výsledky. |
|
202 Accepted |
Podporuje se pouze pro asynchronní požadavek. Žádost přijata: Žádost byla přijata ke zpracování. K opakování nebo přístupu k výsledkům použijte adresu URL v hlavičce umístění. Hlavičky Location: string |
|
Other Status Codes |
Došlo k neočekávané chybě. |
Zabezpečení
AADToken
Jedná se o Microsoft Entra OAuth 2.0 Flow. Při spárování s přístupu na základě role Azure se dá řídit přístup k rozhraním REST API služby Azure Maps. Řízení přístupu na základě role Azure slouží k určení přístupu k jednomu nebo více úč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 více oprávnění k rozhraním REST API služby Azure Maps.
Pokud chcete implementovat scénáře, doporučujeme zobrazit koncepty ověřování . Stručně ř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 rozsahy.
Poznámky
- Tato definice zabezpečení vyžaduje použití hlavičky
x-ms-client-id
k označení, ke kterému prostředku Azure Maps aplikace žádá o přístup. To lze získat z rozhraní API pro správu Maps.
Authorization URL
je specifická pro instanci veřejného cloudu Azure. Suverénní cloudy mají jedinečné adresy URL autorizace a konfigurace MICROSOFT Entra ID.
* Řízení přístupu na základě role 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í webové sady SDK služby Azure Maps 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 vytvoření účtu Azure Maps na webu Azure Portal nebo pomocí PowerShellu, rozhraní příkazového řádku, sad Azure SDK nebo rozhraní REST API.
Díky tomuto klíči má každá aplikace přístup ke všem rozhraní REST API. Jinými slovy, tento klíč lze použít jako hlavní klíč v účtu, ve který jsou vydány.
U veřejně vystavených aplikací doporučujeme používat důvěrných klientských aplikací přístup k rozhraním REST API služby Azure Maps, aby bylo možné klíč 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 Vypsat SAS v prostředku Azure Maps prostřednictvím roviny správy Azure prostřednictvím webu Azure Portal, PowerShellu, rozhraní příkazového řádku, sad SDK Azure nebo rozhraní REST API.
S tímto tokenem má každá aplikace oprávnění k přístupu pomocí řízení přístupu na základě role Azure a jemně odstupňované řízení vypršení platnosti, rychlosti a oblastí použití pro konkrétní token. Jinými slovy, token SAS lze použít k tomu, aby aplikace mohly řídit přístup bezpečnějším způsobem než sdílený klíč.
U veřejně vystavených aplikací doporučujeme nakonfigurovat konkrétní seznam povolených zdrojů na prostředku účtu Map omezit 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
GET https://atlas.microsoft.com/route/matrix/11111111-2222-3333-4444-555555555555?api-version=1.0
Ukázková odpověď
{
"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
}
}
Definice
Name | Description |
---|---|
Error |
Další informace o chybě správy prostředků |
Error |
Podrobnosti o chybě. |
Error |
Chybová odpověď |
Route |
Souhrnný objekt pro oddíl trasy |
Route |
Objekt výsledku matice |
Route |
Tento objekt se vrátí z úspěšného volání matice směrování. Pokud jsou k dispozici 2 původy a 3 cíle, bude v každém z nich 2 pole se 3 prvky. Obsah jednotlivých prvků závisí na možnostech uvedených v dotazu. |
Route |
Objekt odpovědi aktuální buňky ve vstupní matici |
Route |
Souhrnný objekt |
ErrorAdditionalInfo
Další informace o chybě správy prostředků
Name | Typ | Description |
---|---|---|
info |
object |
Další informace. |
type |
string |
Další typ informací. |
ErrorDetail
Podrobnosti o chybě.
Name | Typ | Description |
---|---|---|
additionalInfo |
Další informace o chybě. |
|
code |
string |
Kód chyby. |
details |
Podrobnosti o chybě. |
|
message |
string |
Chybová zpráva. |
target |
string |
Cíl chyby. |
ErrorResponse
Chybová odpověď
Name | Typ | Description |
---|---|---|
error |
Objekt chyby. |
RouteLegSummary
Souhrnný objekt pro oddíl trasy
Name | Typ | Description |
---|---|---|
arrivalTime |
string |
Odhadovaná doba příjezdu pro trasu nebo nohu. Čas je ve standardu UTC. |
batteryConsumptionInkWh |
number |
Odhadovaná spotřeba elektrické energie v kilowatthodinách (kWh) pomocí modelu elektrické spotřeby. Zahrnuto, pokud je vozidloEngineType nastaveno na elektrické a konstantníSpeedConsumptionInkWhPerHundredkm je zadán. Hodnota baterieConsumptionInkWh zahrnuje recupe jmenovitou elektrickou energii, a proto může být negativní (což označuje získá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 nevyučovaná rekuperace. |
departureTime |
string |
Odhadovaná doba odletu pro trasu nebo nohu. Čas je ve standardu UTC. |
fuelConsumptionInLiters |
number |
Odhadovaná spotřeba paliva v literech pomocí modelu spotřeby spalování. Zahrnuto, pokud je vozidloEngineType nastaveno na spalování a constantSpeedConsumptionInLitersPerHundredkm je zadán. Hodnota bude nezáporná. |
historicTrafficTravelTimeInSeconds |
integer |
Odhadovaná doba jízdy vypočítaná pomocí historických dat historického provozu závislých na čase. Zahrnuté pouze v případě, že se v dotazu používá computeTravelTimeFor = vše. |
lengthInMeters |
integer |
Vlastnost Délka v metrech |
liveTrafficIncidentsTravelTimeInSeconds |
integer |
Odhadovaná doba jízdy vypočítaná pomocí dat o rychlosti v reálném čase Zahrnuté pouze v případě, že se v dotazu používá computeTravelTimeFor = vše. |
noTrafficTravelTimeInSeconds |
integer |
Odhadovaná doba jízdy vypočítaná tak, jako kdyby nedošlo k žádným zpožděním na trase kvůli dopravním podmínkám (např. zahlcení). Zahrnuté pouze v případě, že se v dotazu používá computeTravelTimeFor = vše. |
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 odletu v budoucnu jsou 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 ve vlastnosti sekund, která zahrnuje zpoždění kvůli provozu v reálném čase. Mějte na paměti, že i když traffic=false travelTimeInSeconds stále zahrnuje zpoždění kvůli provozu. Pokud je funkce DepartAt v budoucnu, doba jízdy se vypočítá pomocí historických dat o provozu závislých na čase. |
RouteMatrix
Objekt výsledku matice
Name | Typ | Description |
---|---|---|
response |
Objekt odpovědi aktuální buňky ve vstupní matici |
|
statusCode |
integer |
Vlastnost StatusCode pro aktuální buňku ve vstupní matici |
RouteMatrixResult
Tento objekt se vrátí z úspěšného volání matice směrování. Pokud jsou k dispozici 2 původy a 3 cíle, bude v každém z nich 2 pole se 3 prvky. Obsah jednotlivých prvků závisí na možnostech uvedených v dotazu.
Name | Typ | Description |
---|---|---|
formatVersion |
string |
Vlastnost Format Version |
matrix |
Výsledky jako 2rozměrné pole souhrnů tras |
|
summary |
Souhrnný objekt |
RouteMatrixResultResponse
Objekt odpovědi aktuální buňky ve vstupní matici
Name | Typ | Description |
---|---|---|
routeSummary |
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 |