Route - Post Route Matrix

Die Route Matrix-API ist eine HTTP-POST Anforderung, die die Berechnung einer Matrix von Routenzusammenfassungen für eine Reihe von Routen ermöglicht, die durch Ursprungs- und Zielspeicherorte mithilfe einer Synchronisierungsanforderung definiert sind. Für jeden bestimmten Ursprung berechnet der Dienst die Kosten des Routings von diesem Ursprung an jedes bestimmte Ziel. Die Start- und Zielpunkte können als Spalten- und Zeilenüberschriften einer Tabelle betrachtet werden, und jede Zelle in der Tabelle enthält die Kosten für die Strecke zwischen dem Start- und Zielpunkt für diese Zelle. Routenmatrizen können für Fahr-, Fuß- und Lkw-Routen berechnet werden. Beispielsweise hat ein Lebensmittellieferunternehmen 20 Fahrer und sie müssen den nächstgelegenen Fahrer finden, um die Lieferung aus dem Restaurant zu abholen. Um diesen Anwendungsfall zu lösen, können sie die Route Matrix-API aufrufen und die Reisekosten verwenden, um die Fahrer nach ihrer tatsächlichen Entfernung oder Zeit vom Restaurant zu sortieren.

Route Matrices werden in verschiedenen Arten von Anwendungen verwendet, die am häufigsten zur Lösung des Problems "Traveling Salesman" (TSP) und des Fahrzeugroutingproblems (Vehicle Routing Problem, VRP) verwendet werden. Für jedes Ursprungszielpaar in der Matrix werden die Fahrzeit und die Entfernung zurückgegeben. Mit den berechneten Kosten können Sie ermitteln, welche detaillierten Routen mithilfe der Routenbeschreibungs-API berechnet werden sollen.

Die maximale Größe einer Matrix für die Synchronisierungsanforderung ist 2500 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele).

Synchrone Routenmatrixanforderung übermitteln

Wenn Für Ihr Szenario synchrone Anforderungen erforderlich sind und die maximale Größe der Matrix kleiner oder gleich 2500 ist, sollten Sie synchrone Anforderungen stellen. Die maximale Größe einer Matrix für diese API ist 2500 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele). Bei dieser Einschränkung sind Beispiele für mögliche Matrixabmessungen: 50x50, 60x40, 90x20 (es muss nicht quadratisch sein).

API-Einschränkungen

Die synchrone Verarbeitung der Matrix eignet sich am besten für schnelle, kleine Matrizen der Routenberechnung. Verwenden Sie den asynchronen Endpunkt, um größere Matrizen und schwere Routenberechnungen zu berechnen. Die folgende Einschränkung gilt für die synchronen Anforderungen. Wenn keine der Zeilen in der folgenden Tabelle mit den Parametern der Anforderung übereinstimmt, erfüllt die Anforderung nicht die Anforderungen und wird nicht verarbeitet.

| Maximale Matrixgröße | Maximale Anzahl von Ursprüngen | Maximale Anzahl von Zielen | Zusätzliche Grenzen

|------------------|------------------------|----------------------------|------------| | 100 | 100 | 100 | N/A | | 200 | 200 | 200 | Alle Ursprünge und Ziele sollten in einer achsenausgerichteten 400 km x 400 km großen Begrenzungsbox sein. Andernfalls werden einige Matrixzellen als OUT_OF_REGION aufgelöst. | | 2500 | 1000 | 1000 | - departAt Oder arriveAt muss überhaupt welche sein.
- traffic muss historisch sein.
- travelMode muss entweder Fahren oder Lkw sein
- Keine anderen Parameter können explizit verwendet werden |

Beispiele

• Anforderung von 10x20-Matrix mit traffic=live: Diese Anforderung wird mit einem Begrenzungsfeldgrenzwert verarbeitet, da sie einem Grenzwert von bis zu 200 entspricht, der Begrenzungsfeldeinschränkungen umfasst.

• Anforderung von 10x20-Matrix mit Standardparametern (traffic=historical): Diese Anforderung wird ohne Begrenzung des Feldlimits verarbeitet, da sie einem Grenzwert von bis zu 2500 entspricht, was keine Begrenzungseinschränkungen angibt.

POST {endpoint}/route/matrix?api-version=2025-01-01

URI-Parameter

Anforderungsheader

Media Types: "application/geo+json"

Anforderungstext

Media Types: "application/geo+json"

Antworten

Sicherheit

AadToken

Dies sind die Microsoft Entra OAuth 2.0 Flows. In Kombination mit Azure rollenbasierten Zugriffs Steuerung kann sie verwendet werden, um den Zugriff auf Azure Maps REST-APIs zu steuern. Azure-rollenbasierte Zugriffskontrollen werden verwendet, um den Zugriff auf ein oder mehrere Azure Maps-Ressourcenkonten oder -Unterressourcen zu bestimmen. Jeder Benutzer, jede Gruppe oder jeder Service-Principal kann über eine integrierte Rolle oder eine benutzerdefinierte Rolle erhalten, die aus einer oder mehreren Berechtigungen besteht, REST-APIs zu Azure Maps.\n\nUm Szenarien zu implementieren, empfehlen wir, Authentifizierungskonzepte anzusehen. Zusammenfassend bietet diese Sicherheitsdefinition eine Lösung zur Modellierung von Anwendungen über Objekte, die Zugriff auf spezifische APIs und Scopes ermöglichen.\n\n#### Anmerkungen\n* Diese Sicherheitsdefinition re die Verwendung des x-ms-client-id Headers, um anzuzeigen, auf welche Azure Maps Ressource die Anwendung Zugriff bittet. Dies kann über die Maps Management API erworben werden.\n* \nDas Authorization URL ist spezifisch für die Azure Public Cloud-Instanz. Souveräne Clouds verfügen über einzigartige Autorisierungs-URLs und Microsoft Entra ID-Konfigurationen. \n* \nDie Azure rollenbasierte Zugriffskontrolle wird von der Azure Managementebene über Azure Portal, PowerShell, CLI, Azure SDKs oder REST-APIs konfiguriert.\n* \nNutzung der Azure Maps Web SDK ermöglicht die konfigurationsbasierte Einrichtung einer Anwendung für mehrere Anwendungsfälle.\n* Für weitere Informationen zu Microsoft Identity Platform siehe Microsoft Identity Platform Übersicht.

Typ: oauth2
Ablauf: implicit
Autorisierungs-URL: https://login.microsoftonline.com/common/oauth2/authorize

Bereiche

subscription-key

Dies ist ein gemeinsamer Schlüssel, der bereitgestellt wird, wenn Sie ein Azure Maps Konto im Azure Portal oder mit PowerShell, CLI, Azure SDKs oder REST API erstellen.\n\n Mit diesem Schlüssel kann jede Anwendung auf alle REST-APIs zugreifen. Mit anderen Worten: Dieser Schlüssel kann als Hauptschlüssel in dem Konto verwendet werden, in dem sie ausgegeben werden.\n\n Für öffentlich zugängliche Anwendungen empfehlen wir, den Ansatz confidential Client Applications zu verwenden, um auf Azure Maps REST-APIs zuzugreifen, damit Ihr Schlüssel sicher gespeichert werden kann.

Typ: apiKey
In: header

SAS Token

Dies ist ein Shared-Access-Signaturtoken, das aus der List SAS-Operation auf der Azure Maps Ressource über die Azure Managementebene über Azure Portal, PowerShell, CLI, Azure SDKs oder REST-APIs erstellt wird.\n\n Mit diesem Token ist jede Anwendung autorisiert, mit Azure rollenbasierte Zugriffskontrollen und feine Kontrolle über Ablauf, Rate und Nutzungsregion des jeweiligen Tokens. Mit anderen Worten: Der SAS-Token kann verwendet werden, um Anwendungen die Zugriffskontrolle auf sicherere Weise als der gemeinsame Schlüssel zu ermöglichen.\n\n Für öffentlich zugängliche Anwendungen empfehlen wir, eine spezielle Liste erlaubter Ursprünge auf der Map-Konto-Ressource zu konfigurieren, um Rendering-Missbrauch zu begrenzen, und das SAS-Token regelmäßig zu erneuern.

Typ: apiKey
In: header

Beispiele

Successfully retrieve a route matrix with additional parameters in the body

POST {endpoint}/route/matrix?api-version=2025-01-01

{
  "type": "FeatureCollection",
  "avoid": [
    "unpavedRoads"
  ],
  "departAt": "2022-12-19T16:39:57+01:00",
  "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"
      }
    }
  ],
  "optimizeRoute": "fastest",
  "traffic": "historical",
  "travelMode": "truck"
}

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

Definitionen

AdrTunnelRestrictionCodeEnum

Der ADR-Tunneleinschränkungscode. ADR ist ein europäisches Abkommen über die internationale Beförderung gefährlicher Güter auf der Straße. Der ADR-Tunneleinschränkungscode wird verwendet, um zu bestimmen, ob ein Fahrzeug durch einen Tunnel mit Einschränkungen bei der Beförderung gefährlicher Güter durchfahren darf.

CommonErrorDetail

Das Fehlerdetails.

ErrorAdditionalInfo

Der Ressourcenverwaltungsfehler zusätzliche Informationen.

FeaturesItemTypeEnum

Gibt den GeoJSON Typ an. Der einzige unterstützte Objekttyp ist Feature. Weitere Informationen finden Sie unter RFC 7946.

FeatureTypeEnum

Gibt den GeoJSON Typ an. Der einzige unterstützte Objekttyp ist FeatureCollection. Weitere Informationen finden Sie unter RFC 7946.

GeoJsonMultiPoint

Ein gültiger GeoJSON MultiPoint Geometrietyp. Weitere Informationen finden Sie unter RFC 7946-.

GeoJsonObjectType

Gibt den GeoJSON Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

InputRouteMatrixFeaturesItem

Gibt die Eingabeursprung- und Zielpunkte sowie zusätzliche Eigenschaften für das GeoJSON MultiPoint-Featureobjekt an. Ausführliche Informationen finden Sie unter RFC 7946-.

InputRouteMatrixProperties

Gibt das Eigenschaftenobjekt für die Eingabematrix an.

MapsErrorDetail

Das Fehlerdetails.

MapsErrorResponse

Übliche Fehlerantwort für Azure Maps-APIs zur Rückgabe von Fehlerdetails bei fehlgeschlagenen Operationen.

MapsInnerError

Ein Objekt, das spezifischere Informationen enthält als das aktuelle Objekt über den Fehler.

RouteMatrixAvoidEnum

Gibt Einschränkungen an, die bei der Ermittlung der Route berücksichtigt werden sollen. Vermeiden Sie die Unterstützung mehrerer Werte in einer Anforderung und wird nur für den Fahr- und Lkw-Reisemodus unterstützt.

RouteMatrixFeatureProperties

Route Matrix-Eigenschaften.

RouteMatrixItemResult

Ergebnis des Routingmatrixelements

RouteMatrixOptimizeRouteEnum

Gibt den Parameter an, der zum Optimieren der Route verwendet werden soll. Wenn nicht definiert, ist der Standardwert "schnellste" und gibt die Route zurück, um die Fahrzeit zu minimieren.

Beispiel: "optimizeRoute":"am schnellsten"

RouteMatrixRequest

Dient zum Abrufen einer Routenmatrix, die die Fahrzeit und Entfernung für alle möglichen Paare in einer Liste der Ursprünge und des Ziels anzeigt. GeoJSON Featureobjekt und zusätzliche Eigenschaften. Ausführliche Informationen finden Sie unter RFC 7946-.

RouteMatrixResponse

Dieses Objekt wird von einem erfolgreichen Aufruf zurückgegeben.

RouteMatrixSummary

Zusammenfassung für die Routenmatrixanforderung

RouteMatrixTrafficEnum

Gibt an, wie Datenverkehr für die Berechnung von Routen berücksichtigt wird.

Standardwert: historical

RouteMatrixTravelModeEnum

Gibt das Reiseprofil an, das beim Berechnen der Matrix berücksichtigt werden soll. Wenn nicht angegeben, lautet der Standardwert "Driving".

Beispiel: "travelMode":"driving"

RouteMatrixTypeEnum

Gibt den Ursprung MultiPoint-Typ und den Ziel-MultiPoint-Typ für die Eingabematrix an.

RouteMatrixVehicleSpec

Gibt die Fahrzeugattribute wie Fahrzeughöhe, Gewicht, Höchstgeschwindigkeit, Frachttyp usw. an, die bei der Berechnung der Routenmatrix berücksichtigt werden sollen. Dies trägt dazu bei, niedrige Brückenabstände, Straßeneinschränkungen, schwierige Rechtsdrehungen zu vermeiden, um die optimierte Route basierend auf den Fahrzeugspezifikationen bereitzustellen. Fahrzeugattribute werden innerhalb der Eigenschaft "vehicleSpec" angegeben.

VehicleLoadTypeEnum

Ladungstypen, die als gefährliche Stoffe eingestuft und von einigen Straßen eingeschränkt werden können.