Route - Get Route Matrix

Odwołanie

Service:: Maps

API Version:: 1.0

Użyj polecenia , aby uzyskać macierz tras pokazującą czas podróży i odległość dla wszystkich możliwych par na liście źródeł i miejsc docelowych.

Interfejs Get Route Matrix API to żądanie HTTP GET , które oblicza czas podróży i odległość dla wszystkich możliwych par na liście źródeł i miejsc docelowych. W przeciwieństwie do interfejsu API Get Route Directions , który udostępnia szczegółowe instrukcje dotyczące trasy, ten interfejs API koncentruje się na wydajności, zapewniając koszt (czas podróży i odległość) routingu z każdego punktu początkowego do każdego miejsca docelowego. Aby uzyskać więcej informacji, zobacz Najlepsze rozwiązania dotyczące usługi Azure Maps Route Service.

Dla każdego danego źródła usługa oblicza koszt routingu od tego źródła do każdego danego miejsca docelowego. Zestaw źródeł i zestaw miejsc docelowych można traktować jako nagłówki kolumn i wierszy tabeli, a każda komórka w tabeli zawiera koszty routingu od źródła do miejsca docelowego dla tej komórki. Załóżmy na przykład, że firma dostarczająca żywność ma 20 kierowców i musi znaleźć najbliższego kierowcę, aby odebrać dostawę z restauracji. Aby rozwiązać ten przypadek użycia, mogą wywołać interfejs API trasy macierzy.

Dla każdej trasy zwracane są czasy podróży i odległości. Za pomocą obliczonych kosztów można określić, które szczegółowe trasy mają być obliczane przy użyciu interfejsu API Route Directions.

Maksymalny rozmiar macierzy dla żądania asynchronicznego wynosi 700 , a dla żądania synchronizacji to 100 (liczba źródeł pomnożona przez liczbę miejsc docelowych).

Przesyłanie synchronicznego żądania macierzy tras

Jeśli scenariusz wymaga żądań synchronicznych, a maksymalny rozmiar macierzy jest mniejszy lub równy 100, możesz wykonać żądanie synchroniczne. Maksymalny rozmiar macierzy dla tego interfejsu API to 100 (liczba źródeł pomnożona przez liczbę miejsc docelowych). Mając to na uwadze, przykłady możliwych wymiarów macierzy to: 10x10, 6x8, 9x8 (nie musi być kwadratowy).

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

Przesyłanie asynchronicznego żądania macierzy tras

Interfejs API asynchroniczny jest odpowiedni do przetwarzania dużych woluminów stosunkowo złożonych żądań routingu. Gdy wysyłasz żądanie przy użyciu żądania asynchronicznego, domyślnie usługa zwraca kod odpowiedzi 202 wraz z adresem URL przekierowania w polu Lokalizacja nagłówka odpowiedzi. Ten adres URL powinien być okresowo sprawdzany do momentu udostępnienia danych odpowiedzi lub informacji o błędzie. Jeśli waitForResults parametr w żądaniu ma wartość true, użytkownik otrzyma odpowiedź 200, jeśli żądanie zostanie zakończone poniżej 120 sekund.

Maksymalny rozmiar macierzy dla tego interfejsu API to 700 (liczba źródeł pomnożona przez liczbę miejsc docelowych). Mając to na uwadze, przykłady możliwych wymiarów macierzy to: 50x10, 10x10, 28x25. 10x70 (nie musi być kwadratowy).

Odpowiedzi asynchroniczne są przechowywane przez 14 dni. Adres URL przekierowania zwraca odpowiedź 404, jeśli zostanie użyta po upływie okresu ważności.

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

Oto typowa sekwencja operacji asynchronicznych:

Klient wysyła żądanie GET macierzy tras do Azure Maps
Serwer odpowie jednym z następujących elementów:

HTTP 202 Accepted — żądanie macierzy tras zostało zaakceptowane.

HTTP Error — wystąpił błąd podczas przetwarzania żądania macierzy tras. Może to być błąd 400 Nieprawidłowe żądanie lub inny kod stanu błędu.
Jeśli żądanie trasy macierzy zostało zaakceptowane pomyślnie, nagłówek Location w odpowiedzi zawiera adres URL umożliwiający pobranie wyników żądania. Ten identyfikator URI stanu wygląda następująco:

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

Klient wystawia żądanie GET w adresie URL pobierania uzyskanym w kroku 3 w celu pobrania wyników

Pobieranie wyników synchronizacji

Po utworzeniu żądania GET dla interfejsu API synchronizacji macierzy tras usługa zwraca kod odpowiedzi 200 dla pomyślnego żądania i tablicy odpowiedzi. Treść odpowiedzi będzie zawierać dane i nie będzie możliwości późniejszego pobrania wyników.

Pobieranie wyników asynchronicznych

Gdy żądanie wysyła 202 Accepted odpowiedź, żądanie jest przetwarzane przy użyciu potoku asynchronicznego. Otrzymasz adres URL, aby sprawdzić postęp żądania asynchronicznego w nagłówku lokalizacji odpowiedzi. Ten identyfikator URI stanu wygląda następująco:

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

Adres URL podany przez nagłówek lokalizacji zwróci następujące odpowiedzi po wysłaniu GET żądania.

HTTP 202 Accepted — żądanie macierzy zostało zaakceptowane, ale nadal jest przetwarzane. Spróbuj ponownie za jakiś czas.

HTTP 200 OK — pomyślnie przetworzone żądanie macierzy. Treść odpowiedzi zawiera wszystkie wyniki.

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

Parametry identyfikatora URI

Nazwa	W	Wymagane	Typ	Opis
format	path	True	string	Identyfikator macierzy otrzymany po pomyślnym zaakceptowaniu żądania trasy macierzy.
api-version	query	True	string	Numer wersji interfejsu API Azure Maps.

Nagłówek żądania

Nazwa	Wymagane	Typ	Opis
x-ms-client-id		string	Określa, które konto jest przeznaczone do użycia w połączeniu z modelem zabezpieczeń Tożsamość Microsoft Entra. Reprezentuje unikatowy identyfikator konta Azure Maps i można go pobrać z interfejsu API konta płaszczyzny zarządzania Azure Maps. Aby użyć zabezpieczeń Tożsamość Microsoft Entra w usłudze Azure Maps, zobacz następujące artykuły, aby uzyskać wskazówki.

Odpowiedzi

Nazwa	Typ	Opis
200 OK	RouteMatrixResult	Pomyślnie przetworzone żądanie macierzy. Treść odpowiedzi zawiera wszystkie wyniki.
202 Accepted		Obsługiwane tylko w przypadku żądania asynchronicznego. Zaakceptowano żądanie: żądanie zostało zaakceptowane do przetwarzania. Użyj adresu URL w nagłówku lokalizacji, aby ponowić próbę lub uzyskać dostęp do wyników. Headers Location: string
Other Status Codes	ErrorResponse	Wystąpił nieoczekiwany błąd.

Nazwa

Typ

Opis

200 OK

RouteMatrixResult

Pomyślnie przetworzone żądanie macierzy. Treść odpowiedzi zawiera wszystkie wyniki.

202 Accepted

Obsługiwane tylko w przypadku żądania asynchronicznego. Zaakceptowano żądanie: żądanie zostało zaakceptowane do przetwarzania. Użyj adresu URL w nagłówku lokalizacji, aby ponowić próbę lub uzyskać dostęp do wyników.

Headers

Location: string

Other Status Codes

ErrorResponse

Wystąpił nieoczekiwany błąd.

Zabezpieczenia

AADToken

Są to przepływy Microsoft Entra OAuth 2.0. Po połączeniu z kontrolą dostępu opartą na rolach platformy Azure może służyć do kontrolowania dostępu do interfejsów API REST Azure Maps. Mechanizmy kontroli dostępu opartej na rolach platformy Azure służą do wyznaczania dostępu do co najmniej jednego Azure Maps konta zasobu lub zasobów podrzędnych. Każdy użytkownik, grupa lub jednostka usługi może mieć dostęp za pośrednictwem wbudowanej roli lub roli niestandardowej składającej się z co najmniej jednego uprawnienia do Azure Maps interfejsów API REST.

Aby zaimplementować scenariusze, zalecamy wyświetlenie pojęć związanych z uwierzytelnianiem. Podsumowując, ta definicja zabezpieczeń stanowi rozwiązanie do modelowania aplikacji za pośrednictwem obiektów, które mogą kontrolować dostęp do określonych interfejsów API i zakresów.

Uwagi

Ta definicja zabezpieczeń wymaga użycia nagłówka x-ms-client-id w celu wskazania, do którego zasobu Azure Maps aplikacja żąda dostępu. Można to uzyskać z poziomu interfejsu API zarządzania usługami Maps.

Element Authorization URL jest specyficzny dla wystąpienia chmury publicznej platformy Azure. Suwerenne chmury mają unikatowe adresy URL autoryzacji i konfiguracje Tożsamość Microsoft Entra. * Kontrola dostępu oparta na rolach platformy Azure jest konfigurowana z poziomu płaszczyzny zarządzania platformy Azure za pośrednictwem Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST. * Użycie zestawu AZURE MAPS Web SDK umożliwia skonfigurowanie aplikacji na podstawie konfiguracji dla wielu przypadków użycia.

Aby uzyskać więcej informacji na temat Platforma tożsamości Microsoft, zobacz omówienie Platforma tożsamości Microsoft.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Nazwa	Opis
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Jest to klucz współużytkowany podczas Twórca konta Azure Maps w Azure Portal lub przy użyciu programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsu API REST.

Za pomocą tego klucza każda aplikacja może uzyskiwać dostęp do wszystkich interfejsów API REST. Innymi słowy, ten klucz może służyć jako klucz główny na koncie, w którym są wystawiane.

W przypadku publicznie uwidocznionych aplikacji zalecamy użycie podejścia do poufnych aplikacji klienckich w celu uzyskania dostępu Azure Maps interfejsów API REST, aby klucz mógł być bezpiecznie przechowywany.

Type: apiKey
In: query

SAS Token

Jest to token sygnatury dostępu współdzielonego tworzony na podstawie operacji list sygnatur dostępu współdzielonego na zasobie Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.

Dzięki temu tokenowi każda aplikacja jest autoryzowana do uzyskiwania dostępu za pomocą kontroli dostępu opartej na rolach platformy Azure oraz szczegółowej kontroli wygaśnięcia, szybkości i regionów użycia dla określonego tokenu. Innymi słowy, token SAS może służyć do umożliwienia aplikacjom kontrolowania dostępu w sposób bardziej bezpieczny niż klucz wspólny.

W przypadku publicznie uwidocznionych aplikacji zalecamy skonfigurowanie określonej listy dozwolonych źródeł w zasobie konta mapy w celu ograniczenia nadużyć renderowania i regularnego odnawiania tokenu SAS.

Type: apiKey
In: header

Przykłady

Successfully retrieve the status for a route matrix request

Sample Request

HTTP

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

Sample Response

Status code:: 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
  }
}

Status code:: 202

Definicje

Nazwa	Opis
ErrorAdditionalInfo	Dodatkowe informacje o błędzie zarządzania zasobami.
ErrorDetail	Szczegóły błędu.
ErrorResponse	Odpowiedź na błąd
RouteLegSummary	Obiekt podsumowania sekcji trasy.
RouteMatrix	Obiekt wyniku macierzy
RouteMatrixResult	Ten obiekt jest zwracany z pomyślnego wywołania macierzy tras. Na przykład jeśli podano 2 źródła i 3 miejsca docelowe, w każdym z nich będzie 2 tablice z 3 elementami. Zawartość każdego elementu zależy od opcji dostępnych w zapytaniu.
RouteMatrixResultResponse	Obiekt odpowiedzi bieżącej komórki w macierzy wejściowej.
RouteMatrixSummary	Obiekt podsumowania

ErrorAdditionalInfo

Dodatkowe informacje o błędzie zarządzania zasobami.

Nazwa	Typ	Opis
info	object	Dodatkowe informacje.
type	string	Dodatkowy typ informacji.

ErrorDetail

Szczegóły błędu.

Nazwa	Typ	Opis
additionalInfo	ErrorAdditionalInfo[]	Dodatkowe informacje o błędzie.
code	string	Kod błędu.
details	ErrorDetail[]	Szczegóły błędu.
message	string	Komunikat o błędzie.
target	string	Element docelowy błędu.

ErrorResponse

Odpowiedź na błąd

Nazwa	Typ	Opis
error	ErrorDetail	Obiekt error.

RouteLegSummary

Obiekt podsumowania sekcji trasy.

Nazwa	Typ	Opis
arrivalTime	string	Szacowany czas przybycia dla trasy lub nogi. Czas jest w formacie UTC.
batteryConsumptionInkWh	number	Szacowane zużycie energii elektrycznej w godzinach kilowatów (kWh) przy użyciu modelu zużycia energii elektrycznej. Uwzględnione, jeśli właściwość vehicleEngineType jest ustawiona na wartość elektryczną i stałąSpeedConsumptionInkWhPerHundredkm jest określona. Wartość batteryConsumptionInkWh obejmuje odzyskaną energię elektryczną i w związku z tym może być ujemna (co wskazuje na uzyskanie energii). Jeśli określono zarówno wartość maxChargeInkWh, jak i currentChargeInkWh, rekonwalescacja zostanie ograniczona w celu zapewnienia, że poziom naładowania baterii nigdy nie przekracza maksymalnej wartości maxChargeInkWh. Jeśli w obliczeniu zużycia nie określono wartości maxChargeInkWh ani currentChargeInkWh, nieskrępowana rekonsuperacja jest zakładana.
departureTime	string	Szacowany czas odlotu dla trasy lub odcinka. Czas jest w formacie UTC.
fuelConsumptionInLiters	number	Szacowane zużycie paliwa w litrach przy użyciu modelu zużycia spalania. Uwzględnione, jeśli parametr vehicleEngineType jest ustawiony na spalanie , a określono wartość constantSpeedConsumptionInLitersPerHundredkm. Wartość będzie nieujemna.
historicTrafficTravelTimeInSeconds	integer	Szacowany czas podróży obliczony przy użyciu danych historycznych zależnych od czasu. Uwzględniane tylko wtedy, gdy parametr computeTravelTimeFor = wszystkie jest używany w zapytaniu.
lengthInMeters	integer	Długość w metrach, właściwość
liveTrafficIncidentsTravelTimeInSeconds	integer	Szacowany czas podróży obliczany przy użyciu danych prędkości w czasie rzeczywistym. Uwzględniane tylko wtedy, gdy parametr computeTravelTimeFor = wszystkie jest używany w zapytaniu.
noTrafficTravelTimeInSeconds	integer	Szacowany czas podróży obliczony tak, jakby na trasie nie wystąpiły żadne opóźnienia z powodu warunków ruchu (np. przeciążenia). Uwzględniane tylko wtedy, gdy parametr computeTravelTimeFor = wszystkie jest używany w zapytaniu.
trafficDelayInSeconds	integer	Szacowane opóźnienie w sekundach spowodowane zdarzeniami w czasie rzeczywistym zgodnie z informacjami o ruchu drogowym. W przypadku tras planowanych z czasem odlotu w przyszłości opóźnienia są zawsze 0. Aby zwrócić dodatkowe czasy podróży przy użyciu różnych typów informacji o ruchu, parametr computeTravelTimeFor =wszystkie należy dodać.
travelTimeInSeconds	integer	Szacowany czas podróży w sekundach właściwości, która obejmuje opóźnienie spowodowane ruchem w czasie rzeczywistym. Należy pamiętać, że nawet wtedy, gdy ruch =false travelTimeInSeconds nadal zawiera opóźnienie spowodowane ruchem. Jeśli funkcja DepartAt jest w przyszłości, czas podróży jest obliczany przy użyciu danych historycznych zależnych od czasu.

RouteMatrix

Obiekt wyniku macierzy

Nazwa	Typ	Opis
response	RouteMatrixResultResponse	Obiekt odpowiedzi bieżącej komórki w macierzy wejściowej.
statusCode	integer	Właściwość StatusCode dla bieżącej komórki w macierzy wejściowej.

RouteMatrixResult

Ten obiekt jest zwracany z pomyślnego wywołania macierzy tras. Na przykład jeśli podano 2 źródła i 3 miejsca docelowe, w każdym z nich będzie 2 tablice z 3 elementami. Zawartość każdego elementu zależy od opcji dostępnych w zapytaniu.

Nazwa	Typ	Opis
formatVersion	string	Właściwość Formatuj wersję
matrix	RouteMatrix[]	Wyniki jako 2-wymiarowa tablica podsumowań tras.
summary	RouteMatrixSummary	Obiekt podsumowania

RouteMatrixResultResponse

Obiekt odpowiedzi bieżącej komórki w macierzy wejściowej.

Nazwa	Typ	Opis
routeSummary	RouteLegSummary	Obiekt podsumowania sekcji trasy.

RouteMatrixSummary

Obiekt podsumowania

Nazwa	Typ	Opis
successfulRoutes	integer	Liczba pomyślnych tras w odpowiedzi.
totalRoutes	integer	Łączna liczba żądanych tras. Liczba komórek w macierzy wejściowej.

Udostępnij za pośrednictwem

Route - Get Route Matrix

Przesyłanie synchronicznego żądania macierzy tras

Przesyłanie asynchronicznego żądania macierzy tras

Pobieranie wyników synchronizacji

Pobieranie wyników asynchronicznych

Parametry identyfikatora URI

Nagłówek żądania

Odpowiedzi

Zabezpieczenia

AADToken

Uwagi

Scopes

subscription-key

SAS Token

Przykłady

Successfully retrieve the status for a route matrix request

Sample Request

Sample Response

Definicje

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Dodatkowe zasoby