Route - Post Route Matrix

Interfejs Route Matrix API to żądanie HTTP POST , które umożliwia obliczenie macierzy podsumowań tras dla zestawu tras zdefiniowanych przez lokalizacje początkowe i docelowe przy użyciu żądania synchronizacji. Dla każdego danego źródła usługa oblicza koszt routingu z tego źródła do każdego 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 z punktu początkowego do miejsca docelowego dla tej komórki. Macierze tras można obliczać dla tras samochodowych, pieszych i ciężarówek. Na przykład firma dostarczająca jedzenie ma 20 kierowców i musi znaleźć najbliższego kierowcę, aby odebrać dostawę z restauracji. Aby rozwiązać ten problem użycia, mogą wywołać interfejs API Route Matrix i użyć kosztu podróży do posortowania kierowców według ich rzeczywistej odległości lub czasu podróży z restauracji.

Macierze tras są używane w kilku różnych typach aplikacji, najczęściej do rozwiązywania problemów komiwojażera (TSP) i problemów z wyznaczaniem tras pojazdów (VRP). Dla każdej pary punkt początkowy-docelowy w macierzy zwracany jest czas podróży i odległość. 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 synchronizacji to 2500 (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 2500, możesz chcieć utworzyć żądanie synchroniczne. Maksymalny rozmiar macierzy dla tego interfejsu API wynosi 2500 (liczba źródeł pomnożona przez liczbę miejsc docelowych). Mając na uwadze to ograniczenie, przykładowe możliwe wymiary matrycy to: 50x50, 60x40, 90x20 (nie musi być kwadratowa).

Ograniczenia interfejsu API

Synchroniczne przetwarzanie macierzy najlepiej nadaje się do szybkich, małych macierzy obliczania tras. Aby obliczyć większe macierze i obliczenia ciężkiej trasy, należy użyć asynchronicznego punktu końcowego. Następujące ograniczenie ma zastosowanie do żądań synchronicznych. Jeśli żaden z wierszy w poniższej tabeli nie jest zgodny z parametrami żądania, oznacza to, że żądanie nie spełnia wymagań i nie zostanie przetworzone.

Przykłady:

• Żądanie macierzy 10x20 z traffic=live: To żądanie zostanie przetworzone z limitem pola ograniczenia, ponieważ pasuje do limitu do 200, który obejmuje ograniczenia pola ograniczenia.

• Żądanie macierzy 10x20 z parametrami domyślnymi (traffic=historical): To żądanie zostanie przetworzone bez limitu pola ograniczenia, ponieważ pasuje do limitu do 2500, który nie nakłada ograniczeń pola ograniczenia.

POST https://atlas.microsoft.com/route/matrix?api-version=2025-01-01

Parametry identyfikatora URI

Nagłówek żądania

Media Types: "application/geo+json"

Treść żądania

Media Types: "application/geo+json"

Odpowiedzi

Zabezpieczenia

AADToken

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

Aby zaimplementować scenariusze, zalecamy wyświetlenie koncepcji uwierzytelniania . Podsumowując, ta definicja zabezpieczeń zawiera 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.

Typ: oauth2
Flow: implicit
Adres URL autoryzacji: https://login.microsoftonline.com/common/oauth2/authorize

Zakresy

subscription-key

Jest to klucz wspólny aprowizowany podczas tworzenia zasobów usługi Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsów API REST.

Za pomocą tego klucza każda aplikacja jest autoryzowana do uzyskiwania dostępu do wszystkich interfejsów API REST. Innymi słowy, mogą one być obecnie traktowane jako klucze główne do konta, dla którego są wystawiane.

W przypadku publicznie uwidocznionych aplikacji naszym zaleceniem jest użycie dostępu serwer-serwer interfejsów API REST usługi Azure Maps, w których ten klucz może być bezpiecznie przechowywany.

Typ: apiKey
W: header

SAS Token

Jest to token sygnatury dostępu współdzielonego tworzony na podstawie operacji List SAS na zasobie usługi Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem witryny 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 i 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 zabezpieczony niż klucz wspólny.

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

Typ: apiKey
W: header

Przykłady

Successfully retrieve a route matrix with additional parameters in the body

POST https://atlas.microsoft.com/route/matrix?api-version=2025-01-01

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            9.15049,
            45.458545
          ],
          [
            11.050541,
            45.403337
          ]
        ]
      },
      "properties": {
        "pointType": "origins"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            11.499931,
            48.149853
          ],
          [
            14.538226,
            50.033688
          ]
        ]
      },
      "properties": {
        "pointType": "destinations"
      }
    }
  ],
  "departAt": "2022-12-19T16:39:57+01:00",
  "optimizeRoute": "fastest",
  "traffic": "historical",
  "travelMode": "truck",
  "avoid": [
    "unpavedRoads"
  ]
}

{
  "type": "Feature",
  "geometry": null,
  "properties": {
    "summary": {
      "totalCount": 4,
      "successfulCount": 4
    },
    "matrix": [
      {
        "statusCode": 200,
        "originIndex": 0,
        "destinationIndex": 0,
        "durationTrafficInSeconds": 21007,
        "durationInSeconds": 21007,
        "distanceInMeters": 492466,
        "departureAt": "2022-12-19T16:39:57+01:00",
        "arrivalAt": "2022-12-19T22:30:03+01:00"
      },
      {
        "statusCode": 200,
        "originIndex": 0,
        "destinationIndex": 1,
        "durationTrafficInSeconds": 33623,
        "durationInSeconds": 33623,
        "distanceInMeters": 877028,
        "departureAt": "2022-12-19T16:39:57+01:00",
        "arrivalAt": "2022-12-20T02:00:19+01:00"
      },
      {
        "statusCode": 200,
        "originIndex": 1,
        "destinationIndex": 0,
        "durationTrafficInSeconds": 19520,
        "durationInSeconds": 19520,
        "distanceInMeters": 427769,
        "departureAt": "2022-12-19T16:39:57+01:00",
        "arrivalAt": "2022-12-19T22:05:16+01:00"
      },
      {
        "statusCode": 200,
        "originIndex": 1,
        "destinationIndex": 1,
        "durationTrafficInSeconds": 32070,
        "durationInSeconds": 32070,
        "distanceInMeters": 836080,
        "departureAt": "2022-12-19T16:39:57+01:00",
        "arrivalAt": "2022-12-20T01:34:27+01:00"
      }
    ]
  }
}

Definicje

AdrTunnelRestrictionCodeEnum

Kod ograniczenia tunelu ADR. ADR to europejska umowa dotycząca międzynarodowego przewozu drogowego towarów niebezpiecznych. Kod ograniczenia tunelu ADR służy do określenia, czy pojazd może przejechać przez tunel z ograniczeniami dotyczącymi przewozu towarów niebezpiecznych.

ErrorAdditionalInfo

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

ErrorDetail

Szczegóły błędu.

FeaturesItemTypeEnum

Określa typ GeoJSON. Jedynym obsługiwanym typem obiektu jest Funkcja. Aby uzyskać więcej informacji, zobacz RFC 7946.

FeatureTypeEnum

Określa typ GeoJSON. Jedynym obsługiwanym typem obiektu jest FeatureCollection. Aby uzyskać więcej informacji, zobacz RFC 7946.

GeoJsonMultiPoint

Prawidłowy typ geometrii GeoJSON MultiPoint. Aby uzyskać szczegółowe informacje, zobacz RFC 7946.

InputRouteMatrixFeaturesItem

Określa wejściowe punkty początkowe i docelowe oraz dodatkowe właściwości GeoJSON obiektu elementu MultiPoint. Szczegółowe informacje można znaleźć w dokumencie RFC 7946 .

InputRouteMatrixProperties

Określa obiekt właściwości macierzy wejściowej.

MapsErrorDetail

Szczegóły błędu.

MapsErrorResponse

Typowa odpowiedź na błędy interfejsów API usługi Azure Maps w celu zwrócenia szczegółów błędu dla operacji, które zakończyły się niepowodzeniem.

MapsInnerError

Obiekt zawierający bardziej szczegółowe informacje niż bieżący obiekt o błędzie.

RouteMatrixAsyncResponse

Określa instrukcje jazdy i dodatkowe właściwości dla każdego punktu manewru na odcinku trasy.

RouteMatrixAvoidEnum

Określa ograniczenia, które powinny być uwzględniane przy obliczaniu trasy podczas wyznaczania trasy. Opcja Avoid obsługuje wiele wartości w żądaniu i jest obsługiwana tylko w przypadku trybu jazdy i jazdy ciężarówki.

RouteMatrixFeatureProperties

Właściwości macierzy tras.

RouteMatrixItemResult

Wynik elementu macierzy tras

RouteMatrixOptimizeRouteEnum

Określa parametr, który ma być używany do optymalizacji trasy. Jeśli nie zostanie zdefiniowana, wartość domyślna to "najszybsza", która zwraca trasę w celu zminimalizowania czasu podróży.

Przykład: "optimizeRoute":"najszybszy"

RouteMatrixRequest

Umożliwia ustawienie macierzy tras przedstawiającej czas podróży i odległość dla wszystkich możliwych par na liście punktów początkowych i docelowych. GeoJSON obiekt funkcji i dodatkowe właściwości. Szczegółowe informacje można znaleźć w dokumencie RFC 7946 .

RouteMatrixResponse

Ten obiekt jest zwracany z pomyślnego wywołania.

RouteMatrixSummary

Podsumowanie żądania macierzy tras

RouteMatrixTrafficEnum

Określa, w jaki sposób ruch jest uwzględniany przy obliczaniu tras.

Wartość domyślna: historical

RouteMatrixTravelModeEnum

Określa profil przesuwu, który ma być brany pod uwagę przy obliczaniu macierzy. Jeśli nie zostanie określona, wartość domyślna to "jazda".

Przykład: "travelMode":"jazda"

RouteMatrixTypeEnum

Określa początkowy typ MultiPoint i docelowy typ MultiPoint dla macierzy wejściowej.

RouteMatrixVehicleSpec

Określa atrybuty pojazdu, takie jak wysokość pojazdu, masa, prędkość maksymalna, rodzaj ładunku itp., które należy wziąć pod uwagę przy obliczaniu macierzy trasy. Pomaga to uniknąć niskich prześwitów mostów, ograniczeń drogowych, trudnych skrętów w prawo, aby zapewnić zoptymalizowaną trasę w oparciu o specyfikacje pojazdu. Atrybuty pojazdu są określone we właściwości vehicleSpec.

RouteOperationKindEnum

Rodzaj operacji asynchronicznej

VehicleLoadTypeEnum

Typy ładunków, które mogą być klasyfikowane jako materiały niebezpieczne i ograniczone z niektórych dróg. Dostępne wartości vehicleLoadType to amerykańskie klasy materiałów niebezpiecznych od 1 do 9 oraz klasyfikacje ogólne do użytku w innych krajach. Wartości rozpoczynające się od USHazmat dotyczą routingu w USA, podczas gdy otherHazmat powinny być używane dla wszystkich innych krajów. vehicleLoadType obsługuje wiele wartości w żądaniu.