Route - Get Route Matrix

Referenz

Dienst:: Maps

API-Version:: 1.0

Dient zum Abrufen einer Routenmatrix, die die Fahrzeit und Entfernung für alle möglichen Paare in einer Liste von Ursprüngen und Zielen anzeigt.

Die Get Route Matrix-API ist eine HTTP-GET Anforderung, die die Reisezeit und Entfernung für alle möglichen Paare in einer Liste von Ursprüngen und Zielen berechnet. Im Gegensatz zur Get Route Directions API, die detaillierte Routenanweisungen bereitstellen, konzentriert sich diese API auf Effizienz, indem Sie die Kosten (Fahrzeit und Entfernung) des Routings von jedem Ursprung zu jedem Ziel erhalten. Weitere Informationen finden Sie unter Bewährte Methoden für den Azure Maps Route-Dienst.

Für jeden bestimmten Ursprung berechnet der Dienst die Kosten des Routings von diesem Ursprung an jedes bestimmte Ziel. Der Satz von Ursprüngen und der Zielsatz kann als Spalten- und Zeilenüberschriften einer Tabelle betrachtet werden, und jede Zelle in der Tabelle enthält die Kosten für das Routing vom Ursprung an das Ziel für diese Zelle. Angenommen, ein Lebensmittellieferunternehmen hat 20 Fahrer und sie müssen den nächstgelegenen Fahrer finden, um die Lieferung aus dem Restaurant aufzunehmen. Um diesen Anwendungsfall zu lösen, können sie die Matrixrouten-API aufrufen.

Für jede Route werden die Fahrzeiten und Entfernungen 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 700 und für die Synchronisierungsanforderung ist sie 100 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele).

Synchrone Routenmatrixanforderung übermitteln

Wenn Ihr Szenario synchrone Anforderungen erfordert und die maximale Größe der Matrix kleiner oder gleich 100 ist, sollten Sie synchrone Anforderungen stellen. Die maximale Größe einer Matrix für diese API ist 100 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele). Bei dieser Einschränkung sind Beispiele für mögliche Matrixabmessungen: 10x10, 6x8, 9x8 (es muss nicht quadratisch sein).

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

Asynchrone Routenmatrixanforderung übermitteln

Die asynchrone API eignet sich für die Verarbeitung großer Mengen relativ komplexer Routinganforderungen. Wenn Sie eine Anforderung mithilfe einer asynchronen Anforderung vornehmen, gibt der Dienst standardmäßig einen Antwortcode 202 entlang einer Umleitungs-URL im Feld "Speicherort" des Antwortheaders zurück. Diese URL sollte regelmäßig überprüft werden, bis die Antwortdaten oder Fehlerinformationen verfügbar sind. Wenn waitForResults Parameter in der Anforderung auf "true" festgelegt ist, erhält der Benutzer eine Antwort von 200, wenn die Anforderung unter 120 Sekunden abgeschlossen ist.

Die maximale Größe einer Matrix für diese API ist 700 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele). Unter Berücksichtigung dieser Einschränkung sind Beispiele für mögliche Matrixabmessungen: 50x10, 10x10, 28 x 25. 10x70 (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.

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

Hier ist eine typische Abfolge asynchroner Vorgänge:

Client sendet eine Route Matrix GET-Anforderung an Azure Maps
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.
Wenn die Matrixroute-Anforderung erfolgreich akzeptiert wurde, enthält der Location-Header in der Antwort die URL zum Herunterladen der Ergebnisse der Anforderung. Dieser Status-URI sieht wie folgt aus:

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

Der Client gibt eine GET-Anforderung für die download-URL aus, die in Schritt 3 abgerufen wurde, um die Ergebnisse herunterzuladen.

Synchronisierungsergebnisse herunterladen

Wenn Sie eine GET-Anforderung für die Route Matrix-Synchronisierungs-API vornehmen, gibt der Dienst den Antwortcode 200 für eine erfolgreiche Anforderung und ein Antwortarray zurück. Der Antworttext enthält die Daten, und es gibt keine Möglichkeit, die Ergebnisse später abzurufen.

Asynchrone Ergebnisse herunterladen

Wenn eine Anforderung eine 202 Accepted Antwort ausgibt, wird die Anforderung mithilfe unserer asynchronen Pipeline verarbeitet. Sie erhalten eine URL, um den Fortschritt Ihrer asynchronen Anforderung im Speicherortheader der Antwort zu überprüfen. Dieser Status-URI sieht wie folgt aus:

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

Die vom Positionsheader bereitgestellte URL gibt die folgenden Antworten zurück, wenn eine GET Anforderung ausgegeben wird.

HTTP-202 Accepted – Matrixanforderung wurde akzeptiert, wird aber noch verarbeitet. Versuchen Sie es bitte in irgendeiner Zeit erneut.

HTTP-200 OK – Matrixanforderung erfolgreich verarbeitet. Der Antworttext enthält alle Ergebnisse.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
format	path	True	string	Matrix-ID, die empfangen wurde, nachdem die Matrixroute-Anforderung erfolgreich akzeptiert wurde.
api-version	query	True	string	Versionsnummer der Azure Maps-API.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
x-ms-client-id		string	Gibt an, welches Konto in Verbindung mit dem Microsoft Entra ID-Sicherheitsmodell für die Verwendung vorgesehen ist. Sie stellt eine eindeutige ID für das Azure Maps-Konto dar und kann aus der Azure Maps-Verwaltungsebenen-Konto-API abgerufen werden. Informationen zur Verwendung der Sicherheit von Microsoft Entra-ID in Azure Maps finden Sie in den folgenden Artikeln anleitungen.

Antworten

Name	Typ	Beschreibung
200 OK	RouteMatrixResult	Die Matrixanforderung wurde erfolgreich verarbeitet. Der Antworttext enthält alle Ergebnisse.
202 Accepted		Wird nur für asynchrone Anforderung unterstützt. Anforderung angenommen: Die Anforderung wurde zur Verarbeitung akzeptiert. Verwenden Sie die URL im Speicherortheader, um die Ergebnisse erneut zu versuchen oder darauf zuzugreifen. Header Location: string
Other Status Codes	ErrorResponse	Unerwarteter Fehler.

Name

Typ

Beschreibung

200 OK

RouteMatrixResult

Die Matrixanforderung wurde erfolgreich verarbeitet. Der Antworttext enthält alle Ergebnisse.

202 Accepted

Wird nur für asynchrone Anforderung unterstützt. Anforderung angenommen: Die Anforderung wurde zur Verarbeitung akzeptiert. Verwenden Sie die URL im Speicherortheader, um die Ergebnisse erneut zu versuchen oder darauf zuzugreifen.

Header

Location: string

Other Status Codes

ErrorResponse

Unerwarteter Fehler.

Sicherheit

AADToken

Dies sind die Microsoft Entra OAuth 2.0 Flows. Bei Kombination mit rollenbasierten Azure-Zugriff Steuern kann es verwendet werden, um den Zugriff auf Azure Maps-REST-APIs zu steuern. Azure-rollenbasierte Zugriffssteuerungen werden verwendet, um den Zugriff auf ein oder mehrere Azure Maps-Ressourcenkonten oder -Unterressourcen zu bestimmen. Jedem Benutzer, Gruppen- oder Dienstprinzipal kann über eine integrierte Rolle oder eine benutzerdefinierte Rolle, die aus einer oder mehreren Berechtigungen für Azure Maps-REST-APIs besteht, Zugriff gewährt werden.

Um Szenarien zu implementieren, empfehlen wir, Authentifizierungskonzepteanzuzeigen. Zusammenfassend bietet diese Sicherheitsdefinition eine Lösung für die Modellierung von Anwendungen über Objekte, die zugriffsfähig für bestimmte APIs und Bereiche sind.

Notizen

Diese Sicherheitsdefinition erfordert die Verwendung des x-ms-client-id-Headers, um anzugeben, auf welche Azure Maps-Ressource die Anwendung Zugriff anfordert. Dies kann über die Karten-Verwaltungs-APIerworben werden.

Die Authorization URL ist spezifisch für die Öffentliche Azure-Cloudinstanz. Souveräne Clouds verfügen über eindeutige Autorisierungs-URLs und Microsoft Entra-ID-Konfigurationen. * Die rollenbasierte Azure-Zugriffssteuerung wird über die Azure-Verwaltungsebene über das Azure-Portal, PowerShell, CLI, Azure SDKs oder REST-APIs konfiguriert. * Die Verwendung des Azure Maps Web SDK ermöglicht die konfigurationsbasierte Einrichtung einer Anwendung für mehrere Anwendungsfälle.

Weitere Informationen zur Microsoft Identity Platform finden Sie unter Übersicht über die Microsoft Identity Platform.

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

Bereiche

Name	Beschreibung
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Dies ist ein freigegebener Schlüssel, der bereitgestellt wird, wenn Sie Erstellen eines Azure Maps-Kontos im Azure-Portal oder mithilfe von PowerShell, CLI, Azure SDKs oder REST-API.

Mit diesem Schlüssel kann jede Anwendung auf alle REST-API zugreifen. Mit anderen Worten, dieser Schlüssel kann als Hauptschlüssel in dem Konto verwendet werden, in dem sie ausgestellt werden.

Für öffentlich zugängliche Anwendungen empfiehlt es sich, die vertraulichen Clientanwendungen Ansatz für den Zugriff auf Azure Maps-REST-APIs zu verwenden, damit Ihr Schlüssel sicher gespeichert werden kann.

Typ: apiKey
In: query

SAS Token

Dies ist ein Freigegebenes Zugriffssignaturtoken wird aus dem Listen-SAS-Vorgang auf der Azure Maps-Ressource über die Azure-Verwaltungsebene über das Azure-Portal, PowerShell, CLI, Azure SDKs oder REST-APIs erstellt.

Mit diesem Token ist jede Anwendung für den Zugriff mit rollenbasierten Azure-Zugriffssteuerungen und feinkörniger Kontrolle auf den Ablauf, die Rate und die Region(en) der Verwendung für das jeweilige Token autorisiert. Mit anderen Worten, das SAS-Token kann verwendet werden, um Anwendungen das Steuern des Zugriffs auf eine sicherere Weise zu ermöglichen als der freigegebene Schlüssel.

Für öffentlich zugängliche Anwendungen empfiehlt es sich, eine bestimmte Liste der zulässigen Ursprünge auf der Zuordnungskontoressource zu konfigurieren,, um das Rendern von Missbrauch zu begrenzen und das SAS-Token regelmäßig zu erneuern.

Typ: apiKey
In: header

Beispiele

Successfully retrieve the status for a route matrix request

Beispielanforderung

HTTP

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

Beispiel für eine Antwort

Statuscode:: 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
  }
}

Statuscode:: 202

Definitionen

Name	Beschreibung
ErrorAdditionalInfo	Der Ressourcenverwaltungsfehler zusätzliche Informationen.
ErrorDetail	Das Fehlerdetails.
ErrorResponse	Fehlerantwort
RouteLegSummary	Summary-Objekt für den Routenabschnitt.
RouteMatrix	Matrixergebnisobjekt
RouteMatrixResult	Dieses Objekt wird von einem erfolgreichen Route Matrix-Aufruf zurückgegeben. Wenn z. B. 2 Ursprünge und 3 Ziele bereitgestellt werden, gibt es jeweils 2 Arrays mit 3 Elementen. Der Inhalt jedes Elements hängt von den optionen ab, die in der Abfrage bereitgestellt werden.
RouteMatrixResultResponse	Antwortobjekt der aktuellen Zelle in der Eingabematrix.
RouteMatrixSummary	Summary-Objekt

ErrorAdditionalInfo

Der Ressourcenverwaltungsfehler zusätzliche Informationen.

Name	Typ	Beschreibung
info	object	Die zusätzlichen Informationen.
type	string	Der zusätzliche Informationstyp.

ErrorDetail

Das Fehlerdetails.

Name	Typ	Beschreibung
additionalInfo	ErrorAdditionalInfo[]	Die zusätzlichen Informationen des Fehlers.
code	string	Der Fehlercode.
details	ErrorDetail[]	Die Fehlerdetails.
message	string	Die Fehlermeldung.
target	string	Das Fehlerziel.

ErrorResponse

Fehlerantwort

Name	Typ	Beschreibung
error	ErrorDetail	Das Fehlerobjekt.

RouteLegSummary

Summary-Objekt für den Routenabschnitt.

Name	Typ	Beschreibung
arrivalTime	string	Die geschätzte Ankunftszeit für die Route oder den Abschnitt. Die Uhrzeit ist in UTC.
batteryConsumptionInkWh	number	Geschätzter elektrischer Energieverbrauch in Wattstunden (kWh) mit dem Elektroverbrauchsmodell. Enthalten, wenn vehicleEngineType auf elektro- und constantSpeedConsumptionInkWhPerHundredkm festgelegt ist. Der Wert von batteryConsumptionInkWh umfasst die recuperierte elektrische Energie und kann daher negativ sein (was auf energiegewinnende Energie hinweist). Wenn sowohl maxChargeInkWh als auch currentChargeInkWh angegeben werden, wird die Recuperation begrenzt, um sicherzustellen, dass der Akkuladestand niemals maxChargeInkWh überschreitet. Wenn weder maxChargeInkWh noch currentChargeInkWh angegeben werden, wird bei der Verbrauchsberechnung eine nicht eingeschränkte Rekuperation angenommen.
departureTime	string	Die geschätzte Abfahrtszeit für die Route oder den Bein. Die Uhrzeit ist in UTC.
fuelConsumptionInLiters	number	Geschätzter Kraftstoffverbrauch in Litern mit dem Verbrennungsverbrauchsmodell. Enthalten, wenn vehicleEngineType auf Verbrennung und constantSpeedConsumptionInLitersPerHundredkm festgelegt ist. Der Wert ist nicht negativ.
historicTrafficTravelTimeInSeconds	integer	Geschätzte Fahrzeit, die mit zeitabhängigen historischen Verkehrsdaten berechnet wird. Nur enthalten, wenn computeTravelTimeFor = alle in der Abfrage verwendet werden.
lengthInMeters	integer	Length In Meter-Eigenschaft
liveTrafficIncidentsTravelTimeInSeconds	integer	Geschätzte Fahrzeit, die mithilfe von Echtzeitgeschwindigkeitsdaten berechnet wird. Nur enthalten, wenn computeTravelTimeFor = alle in der Abfrage verwendet werden.
noTrafficTravelTimeInSeconds	integer	Geschätzte Fahrzeit, die so berechnet wird, als ob es aufgrund von Verkehrsbedingungen keine Verzögerungen auf der Strecke gibt (z. B. Stau). Nur enthalten, wenn computeTravelTimeFor = alle in der Abfrage verwendet werden.
trafficDelayInSeconds	integer	Geschätzte Verzögerung in Sekunden, die durch den(n) Echtzeitvorfall(n) nach Datenverkehrsinformationen verursacht wird. Bei künftig geplanten Routen mit Abfahrtszeit sind Verzögerungen immer 0. Um zusätzliche Reisezeiten mit unterschiedlichen Arten von Verkehrsinformationen zurückzugeben, muss der Parameter computeTravelTimeFor=all hinzugefügt werden.
travelTimeInSeconds	integer	Geschätzte Fahrzeit in Sekunden, die die Verzögerung aufgrund des Echtzeitdatenverkehrs enthält. Beachten Sie, dass auch wenn datenverkehr=false travelTimeInSeconds die Verzögerung aufgrund des Datenverkehrs noch enthält. Wenn "DepartAt" in Zukunft erfolgt, wird die Fahrzeit mit zeitabhängigen historischen Verkehrsdaten berechnet.

RouteMatrix

Matrixergebnisobjekt

Name	Typ	Beschreibung
response	RouteMatrixResultResponse	Antwortobjekt der aktuellen Zelle in der Eingabematrix.
statusCode	integer	StatusCode-Eigenschaft für die aktuelle Zelle in der Eingabematrix.

RouteMatrixResult

Dieses Objekt wird von einem erfolgreichen Route Matrix-Aufruf zurückgegeben. Wenn z. B. 2 Ursprünge und 3 Ziele bereitgestellt werden, gibt es jeweils 2 Arrays mit 3 Elementen. Der Inhalt jedes Elements hängt von den optionen ab, die in der Abfrage bereitgestellt werden.

Name	Typ	Beschreibung
formatVersion	string	Format Version-Eigenschaft
matrix	RouteMatrix[]	Ergebnisse als zweidimensionales Array von Routenzusammenfassungen.
summary	RouteMatrixSummary	Summary-Objekt

RouteMatrixResultResponse

Antwortobjekt der aktuellen Zelle in der Eingabematrix.

Name	Typ	Beschreibung
routeSummary	RouteLegSummary	Summary-Objekt für den Routenabschnitt.

RouteMatrixSummary

Summary-Objekt

Name	Typ	Beschreibung
successfulRoutes	integer	Die Anzahl der erfolgreichen Routen in der Antwort.
totalRoutes	integer	Gesamtanzahl der angeforderten Routen. Anzahl der Zellen in der Eingabematrix.

Freigeben über

Route - Get Route Matrix

Synchrone Routenmatrixanforderung übermitteln

Asynchrone Routenmatrixanforderung übermitteln

Synchronisierungsergebnisse herunterladen

Asynchrone Ergebnisse herunterladen

URI-Parameter

Anforderungsheader

Antworten

Sicherheit

AADToken

Notizen

Bereiche

subscription-key

SAS Token

Beispiele

Successfully retrieve the status for a route matrix request

Beispielanforderung

Beispiel für eine Antwort

Definitionen

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Zusätzliche Ressourcen