Route - Get Route Matrix

Referenz

Service:: Maps

API Version:: 1.0

Verwenden Sie , um eine Routenmatrix zu erhalten, die die Reisezeit und die Entfernung für alle möglichen Paare in einer Liste von Ursprüngen und Zielen anzeigt.

Die Get Route Matrix API ist eine HTTP-Anforderung GET , die die Reisezeit und die 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 bereitstellt, konzentriert sich diese API auf die Effizienz, indem sie Ihnen die Kosten (Reisezeit und Entfernung) für das Routing von jedem Ursprung zu jedem Ziel bereitstellt. Weitere Informationen finden Sie unter Bewährte Methoden für Azure Maps Routendienst.

Für jeden bestimmten Ursprung berechnet der Dienst die Kosten für das Routing von diesem Ursprung zu jedem bestimmten Ziel. Der Satz der Ursprünge 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 zum Ziel für diese Zelle. Angenommen, ein Lebensmittellieferunternehmen hat 20 Fahrer und muss den nächstgelegenen Fahrer finden, um die Lieferung im Restaurant abzuholen. Um diesen Anwendungsfall zu lösen, können sie die Matrixroute-API aufrufen.

Für jede Route werden die Fahrzeiten und Entfernungen zurückgegeben. Sie können die berechneten Kosten verwenden, um zu bestimmen, welche detaillierten Routen mithilfe der Routenbeschreibungs-API berechnet werden sollen.

Die maximale Größe einer Matrix für eine asynchrone Anforderung beträgt 700 und für Synchronisierungsanforderungen 100 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele).

Übermitteln einer synchronen Routenmatrixanforderung

Wenn Ihr Szenario synchrone Anforderungen erfordert und die maximale Größe der Matrix kleiner oder gleich 100 ist, sollten Sie eine synchrone Anforderung durchführen. Die maximale Größe einer Matrix für diese API beträgt 100 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele). Unter Berücksichtigung dieser Einschränkung sind Beispiele für mögliche Matrixdimensionen: 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}

Übermitteln einer asynchronen Routenmatrixanforderung

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

Die maximale Größe einer Matrix für diese API beträgt 700 (die Anzahl der Ursprünge multipliziert mit der Anzahl der Ziele). Unter Berücksichtigung dieser Einschränkung sind Beispiele für mögliche Matrixdimensionen: 50x10, 10x10, 28x25. 10x70 (es muss nicht quadratisch sein).

Die asynchronen Antworten werden 14 Tage lang 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}

Dies ist eine typische Abfolge von asynchronen Vorgängen:

Der Client sendet eine GET-Anforderung der Routenmatrix an Azure Maps
Der Server antwortet mit einer der folgenden Aktionen:

HTTP 202 Accepted : Route Matrix-Anforderung wurde akzeptiert.

HTTP Error : Fehler bei der Verarbeitung Ihrer Route Matrix-Anforderung. Dies kann entweder eine 400 ungültige Anforderung oder ein anderer Fehler status Code sein.
Wenn die Matrixroutenanforderung 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 stellt eine GET-Anforderung für die in Schritt 3 abgerufene Download-URL aus, um die Ergebnisse herunterzuladen.

Herunterladen von Synchronisierungsergebnissen

Wenn Sie eine GET-Anforderung für die Routenmatrixsynchronisierungs-API stellen, 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.

Herunterladen von Asynchronen Ergebnissen

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 Adressheader 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 Standortheader bereitgestellte URL gibt die folgenden Antworten zurück, wenn eine GET Anforderung ausgegeben wird.

HTTP 202 Accepted : Matrixanforderung wurde akzeptiert, wird aber noch verarbeitet. Bitte versuchen Sie es in einiger 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 verwendet werden soll. Es stellt eine eindeutige ID für das Azure Maps-Konto dar und kann von der Azure Maps-Verwaltungsebenen-API abgerufen werden. Informationen zur Verwendung Microsoft Entra ID Sicherheit in Azure Maps finden Sie in den folgenden Artikeln.

Antworten

Name	Typ	Beschreibung
200 OK	RouteMatrixResult	Matrixanforderung erfolgreich verarbeitet. Der Antworttext enthält alle Ergebnisse.
202 Accepted		Wird nur für asynchrone Anforderungen unterstützt. Anforderung akzeptiert: Die Anforderung wurde für die Verarbeitung akzeptiert. Verwenden Sie die URL im Location Header, um einen Wiederholungsversuch zu versuchen oder auf die Ergebnisse zuzugreifen. Headers Location: string
Other Status Codes	ErrorResponse	Ein unerwarteter Fehler ist aufgetreten.

Name

Typ

Beschreibung

200 OK

RouteMatrixResult

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

202 Accepted

Wird nur für asynchrone Anforderungen unterstützt. Anforderung akzeptiert: Die Anforderung wurde für die Verarbeitung akzeptiert. Verwenden Sie die URL im Location Header, um einen Wiederholungsversuch zu versuchen oder auf die Ergebnisse zuzugreifen.

Headers

Location: string

Other Status Codes

ErrorResponse

Ein unerwarteter Fehler ist aufgetreten.

Sicherheit

AADToken

Dies sind die Microsoft Entra OAuth 2.0-Flows. In Kombination mit der rollenbasierten Zugriffssteuerung in Azure kann sie verwendet werden, um den Zugriff auf Azure Maps REST-APIs zu steuern. Rollenbasierte Zugriffssteuerungen in Azure werden verwendet, um den Zugriff auf ein oder mehrere Azure Maps Ressourcenkonto oder Unterressourcen festzulegen. Jedem Benutzer, jeder Gruppe oder einem Dienstprinzipal kann zugriff über eine integrierte Rolle oder eine benutzerdefinierte Rolle gewährt werden, die aus einer oder mehreren Berechtigungen für Azure Maps REST-APIs besteht.

Zur Implementierung von Szenarien wird empfohlen, Authentifizierungskonzepte anzuzeigen. Zusammenfassend bietet diese Sicherheitsdefinition eine Lösung zum Modellieren von Anwendungen über Objekte, die die Zugriffssteuerung für bestimmte APIs und Bereiche ermöglichen.

Hinweise

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 Kartenverwaltungs-API abgerufen werden.

ist Authorization URL spezifisch für die öffentliche Azure-Cloud instance. Sovereign Clouds verfügen über eindeutige Autorisierungs-URLs und Microsoft Entra ID Konfigurationen. * Die rollenbasierte Zugriffssteuerung von Azure wird über die Azure-Verwaltungsebene über 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 zu Microsoft Identity Platform finden Sie unter Microsoft Identity Platform Übersicht.

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

Scopes

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

subscription-key

Dies ist ein gemeinsam verwendeter Schlüssel, der bereitgestellt wird, wenn Sie ein Azure Maps-Konto im Azure-Portal oder mithilfe von PowerShell, CLI, Azure SDKs oder REST-API Create.

Mit diesem Schlüssel kann jede Anwendung auf die gesamte REST-API zugreifen. Anders ausgedrückt: Dieser Schlüssel kann als master Schlüssel in dem Konto verwendet werden, in dem er ausgestellt wird.

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

Type: apiKey
In: query

SAS Token

Dies ist ein Shared Access Signature-Token, das aus dem Sas-Listenvorgang auf der Azure Maps-Ressource über die Azure-Verwaltungsebene über Azure-Portal, PowerShell, CLI, Azure SDKs oder REST-APIs erstellt wird.

Mit diesem Token ist jede Anwendung für den Zugriff mit rollenbasierten Azure-Zugriffssteuerungen und einer präzisen Steuerung des Ablaufs, der Rate und der Regionen für das jeweilige Token autorisiert. Anders ausgedrückt: Das SAS-Token kann verwendet werden, um Anwendungen die Steuerung des Zugriffs auf eine sicherere Weise zu ermöglichen als der gemeinsam genutzte Schlüssel.

Für öffentlich verfügbar gemachte Anwendungen wird empfohlen, eine bestimmte Liste der zulässigen Ursprünge in der Ressource "Konto zuordnen " zu konfigurieren, um den Renderingmissbrauch zu begrenzen und das SAS-Token regelmäßig zu erneuern.

Type: apiKey
In: header

Beispiele

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

Definitionen

Name	Beschreibung
ErrorAdditionalInfo	Zusätzliche Informationen zum Ressourcenverwaltungsfehler.
ErrorDetail	Die 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 angegeben werden, werden zwei Arrays mit jeweils drei Elementen verwendet. Der Inhalt jedes Elements hängt von den in der Abfrage bereitgestellten Optionen ab.
RouteMatrixResultResponse	Antwortobjekt der aktuellen Zelle in der Eingabematrix.
RouteMatrixSummary	Summary-Objekt

ErrorAdditionalInfo

Zusätzliche Informationen zum Ressourcenverwaltungsfehler.

Name	Typ	Beschreibung
info	object	Zusätzliche Informationen.
type	string	Typ der zusätzlichen Informationen.

ErrorDetail

Die Fehlerdetails.

Name	Typ	Beschreibung
additionalInfo	ErrorAdditionalInfo[]	Die zusätzlichen Fehlerinformationen.
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 Etappe. Die Zeit wird in UTC angegeben.
batteryConsumptionInkWh	number	Geschätzter Stromverbrauch in Kilowattstunden (kWh) unter Verwendung des Stromverbrauchsmodells. Enthalten, wenn vehicleEngineType auf electric und constantSpeedConsumptionInkWhPerHundredkm festgelegt ist. Der Wert von batteryConsumptionInkWh enthält die rekuperierte elektrische Energie und kann daher negativ sein (was auf die Gewinnung von Energie hinweist). Wenn sowohl maxChargeInkWh als auch currentChargeInkWh angegeben sind, wird die Rekuperation begrenzt, um sicherzustellen, dass der Akkuladestand maxChargeInkWh niemals überschreitet. Wenn weder maxChargeInkWh noch currentChargeInkWh angegeben sind, wird bei der Verbrauchsberechnung von einer uneingeschränkten Rekuperation ausgegangen.
departureTime	string	Die geschätzte Abfahrtszeit für die Route oder Etappe. Die Zeit wird in UTC angegeben.
fuelConsumptionInLiters	number	Geschätzter Kraftstoffverbrauch in Litern unter Verwendung des Verbrennungsverbrauchsmodells. Enthalten, wenn vehicleEngineType auf combustion und constantSpeedConsumptionInLitersPerHundredkm festgelegt ist. Der Wert ist nicht negativ.
historicTrafficTravelTimeInSeconds	integer	Geschätzte Reisezeit, die anhand zeitabhängiger Verlaufsdaten berechnet wird. Nur enthalten, wenn computeTravelTimeFor = all in der Abfrage verwendet wird.
lengthInMeters	integer	Length In Meters-Eigenschaft
liveTrafficIncidentsTravelTimeInSeconds	integer	Geschätzte Reisezeit, die mithilfe von Echtzeitgeschwindigkeitsdaten berechnet wird. Nur enthalten, wenn computeTravelTimeFor = all in der Abfrage verwendet wird.
noTrafficTravelTimeInSeconds	integer	Geschätzte Reisezeit, berechnet, als ob es aufgrund von Verkehrsbedingungen (z. B. Staus) zu keinen Verzögerungen auf der Strecke kommt. Nur enthalten, wenn computeTravelTimeFor = all in der Abfrage verwendet wird.
trafficDelayInSeconds	integer	Geschätzte Verzögerung in Sekunden, die durch die Echtzeitvorfälle gemäß Den Verkehrsinformationen verursacht wird. Bei routen, die in Zukunft mit Abfahrtszeit geplant sind, beträgt die Verspätung immer 0. Um zusätzliche Reisezeiten mithilfe verschiedener Arten von Datenverkehrsinformationen zurückzugeben, muss der Parameter computeTravelTimeFor=all hinzugefügt werden.
travelTimeInSeconds	integer	Geschätzte Reisezeit in Sekunden, die die Verzögerung aufgrund von Echtzeitdatenverkehr enthält. Beachten Sie, dass auch wenn traffic=false travelTimeInSeconds die Verzögerung aufgrund des Datenverkehrs enthält. Wenn DepartAt in der Zukunft liegt, wird die Reisezeit anhand zeitabhängiger historischer 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 angegeben werden, werden zwei Arrays mit jeweils drei Elementen verwendet. Der Inhalt jedes Elements hängt von den in der Abfrage bereitgestellten Optionen ab.

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	Anzahl der erfolgreichen Routen in der Antwort.
totalRoutes	integer	Gesamtzahl der angeforderten Routen. Anzahl der Zellen in der Eingabematrix.

Route - Get Route Matrix

Übermitteln einer synchronen Routenmatrixanforderung

Übermitteln einer asynchronen Routenmatrixanforderung

Herunterladen von Synchronisierungsergebnissen

Herunterladen von Asynchronen Ergebnissen

URI-Parameter

Anforderungsheader

Antworten

Sicherheit

AADToken

Hinweise

Scopes

subscription-key

SAS Token

Beispiele

Successfully retrieve the status for a route matrix request

Sample Request

Sample Response

Definitionen

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Zusätzliche Ressourcen