Route - Post Route Matrix Async

Die Route Matrix Async-API ist eine HTTP-POST-Anforderung, die die Berechnung einer Matrix von Routenzusammenfassungen für eine Reihe von Routen ermöglicht, die von Ursprungs- und Zielspeicherorten mithilfe einer asynchronen (asynchronen) Anforderung definiert wurden. 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.

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 asynchrone Anforderung ist 50000 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele).

Asynchrone Routenmatrixanforderung übermitteln

Die asynchrone API eignet sich für die Verarbeitung großer Mengen relativ komplexer Routinganforderungen. Wenn Sie eine Anfrage mit asynchroner Anfrage stellen, liefert der Dienst standardmäßig einen 202-Antwortcode zusammen mit einer URL im Feld operation-Location des Antwortheaders mit dem Azure Maps Geography-Endpunkt {geography}.atlas.microsoft.com. Diese URL sollte in regelmäßigen Abständen überprüft werden, bis der Status erfolgreich ist.

Die maximale Größe einer Matrix für diese API ist 500000 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele). Unter Berücksichtigung dieser Einschränkung sind Beispiele für mögliche Matrixabmessungen: 500x100, 100x100, 280x170. 100x50 (es muss nicht quadratisch sein).

Die asynchronen Antworten werden für 24 Stunden gespeichert. Die Umleitungs-URL gibt eine 404-Antwort zurück, wenn sie nach dem Ablaufzeitraum verwendet wird.

POST
https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01&subscription-key={subscription-key}

Hier ist eine typische Abfolge asynchroner Vorgänge:

1. Client sendet eine Route Matrix POST-Anfrage an Azure Maps

2. Der Server antwortet mit einer der folgenden Aktionen:

HTTP-202 Accepted – Route Matrix-Anforderung wurde akzeptiert.

HTTP-Error – Fehler beim Verarbeiten der Route Matrix-Anforderung. Dies kann entweder ein 400 Ungültiger Anforderungscode oder ein anderer Fehlerstatuscode sein.

3. Wenn die Matrixroute-Anforderung erfolgreich akzeptiert wurde, enthält der operation-location Header in der Antwort die URL, um den Status der Anforderung abzurufen. Dieser Status-URI sieht wie folgt aus:

    GET
https://atlas.microsoft.com/route/operations/{id}?api-version=2025-01-01?subscription-key={subscription-key}

4. Der Client gibt eine GET-Anforderung für die in Schritt 3 abgerufene resultUrl aus, um die Ergebnisse abzurufen.

    GET
https://atlas.microsoft.com/route/operations/{id}/result?api-version=2025-01-01?subscription-key={subscription-key}

API-Einschränkungen

Die asynchrone Verarbeitung der Matrix eignet sich am besten für größere Matrizen, die eine hohe Routenberechnung erfordern. Die folgende Einschränkung gilt für die asynchronen 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 Einschränkungen |

|------------------|-----------------------|-----------------------------|-------------------| | 2500 | 1000 | 1000 | 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.  | | 50.000 | 10.000 | 10.000 | - departAt Oder arriveAt muss überhaupt welche sein.
- traffic muss historisch sein.
- optimizeRoute müssen am schnellsten sein.
- travelMode müssen entweder Fahren oder Lkw sein. 
- Es können keine anderen Parameter explizit verwendet werden.  |

POST {endpoint}/route/matrix:async?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

Submit an asynchronous request for matrix

POST {endpoint}/route/matrix:async?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"
}

Operation-Location: https://atlas.microsoft.com/route/operations/bc3f9365-3ee0-4564-aa27-825016325557?api-version=2025-01-01

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.

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.

RouteMatrixAsyncOptimizeRouteEnum

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":"shortest"

RouteMatrixAsyncRequest

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-.

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.

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.