Route - Get Route Matrix

Başvuru

Service:: Maps

API Version:: 1.0

Çıkış noktaları ve hedefler listesindeki tüm olası çiftlerin seyahat süresini ve mesafesini gösteren bir rota matrisi almak için kullanın.

Get Route Matrix API, çıkış noktaları ve hedefler listesindeki tüm olası çiftler için seyahat süresini ve uzaklığı hesaplayan bir HTTP GET isteğidir. Ayrıntılı yol yönergeleri sağlayan Yol Tariflerini Alma API'sinden farklı olarak, bu API size her çıkış noktasından her hedefe yönlendirmenin maliyetini (seyahat süresi ve mesafe) vererek verimliliğe odaklanır. Daha fazla bilgi için bkz. Azure Haritalar Yönlendirme hizmeti için en iyi yöntemler.

Hizmet, belirli her kaynak için, bu kaynaktan verilen her hedefe yönlendirmenin maliyetini hesaplar. Kaynak kümesi ve hedef kümesi, bir tablonun sütun ve satır üst bilgileri olarak düşünülebilir ve tablodaki her hücre, o hücre için kaynaktan hedefe yönlendirme maliyetlerini içerir. Örneğin, bir gıda teslimat şirketinin 20 sürücüsü olduğunu ve teslimatı restorandan almak için en yakın sürücüyü bulması gerektiğini varsayalım. Bu kullanım örneğini çözmek için Matrix Route API'sini çağırabilir.

Her rota için seyahat süreleri ve mesafeler döndürülür. Yol Tarifleri API'sini kullanarak hesaplanması gereken ayrıntılı yolları belirlemek için hesaplanan maliyetleri kullanabilirsiniz.

Zaman uyumsuz istek matrisinin boyut üst sınırı 700 , eşitleme isteği için ise 100'dür (kaynak sayısı hedef sayısıyla çarpılır).

Zaman Uyumlu Yönlendirme Matrisi İsteği Gönderme

Senaryonuz zaman uyumlu istekler gerektiriyorsa ve matrisin boyut üst sınırı 100'den küçük veya buna eşitse, zaman uyumlu istekte bulunmak isteyebilirsiniz. Bu API için matrisin en büyük boyutu 100'dür (kaynak sayısı hedef sayısıyla çarpılır). Bu kısıtlama göz önünde bulundurularak olası matris boyutlarına örnekler şunlardır: 10x10, 6x8, 9x8 (kare olması gerekmez).

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

Zaman Uyumsuz Yol Matrisi İsteği Gönderme

Zaman Uyumsuz API, görece karmaşık yönlendirme isteklerinin büyük hacimlerini işlemek için uygundur. Zaman uyumsuz istek kullanarak istekte bulunduğunuzda, hizmet varsayılan olarak yanıt üst bilgisinin Konum alanındaki yeniden yönlendirme URL'si boyunca bir 202 yanıt kodu döndürür. Yanıt verileri veya hata bilgileri kullanılabilir olana kadar bu URL düzenli aralıklarla denetlenmelidir. İstekteki parametre true olarak ayarlanırsa waitForResults , istek 120 saniyenin altında biterse kullanıcı 200 yanıt alır.

Bu API için matrisin en büyük boyutu 700'dür (kaynak sayısı hedef sayısıyla çarpılır). Bu kısıtlama göz önünde bulundurularak olası matris boyutlarına örnekler şunlardır: 50x10, 10x10, 28x25. 10x70 (kare olması gerekmez).

Zaman uyumsuz yanıtlar 14 gün boyunca depolanır. Yeniden yönlendirme URL'si, süre sonundan sonra kullanılırsa bir 404 yanıtı döndürür.

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

Zaman uyumsuz işlemlerin tipik bir dizisi aşağıda verilmiştir:

İstemci, Azure Haritalar'a bir Yönlendirme Matrisi GET isteği gönderir
Sunucu aşağıdakilerden biriyle yanıt verir:

HTTP 202 Accepted - Yol Matrisi isteği kabul edildi.

HTTP Error - Yol Matrisi isteğiniz işlenirken bir hata oluştu. Bu 400 Hatalı İstek veya başka bir Hata durum kodu olabilir.
Matris Yolu isteği başarıyla kabul edildiyse, yanıttaki Konum üst bilgisi isteğin sonuçlarını indirmek için URL'yi içerir. Bu durum URI'sı aşağıdaki gibi görünür:

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

İstemci, sonuçları indirmek için 3. Adımda alınan indirme URL'sinde bir GET isteği gönderir

Eşitleme Sonuçlarını İndir

Route Matrix Sync API'sine bir GET isteği gönderdiğinizde, hizmet başarılı istek için 200 yanıt kodu ve bir yanıt dizisi döndürür. Yanıt gövdesi verileri içerir ve sonuçları daha sonra alma imkanı olmayacaktır.

Zaman Uyumsuz Sonuçları İndir

bir istek yanıt 202 Accepted verdiği zaman, istek zaman uyumsuz işlem hattımız kullanılarak işlenir. Yanıtın konum üst bilgisinde zaman uyumsuz isteğinizin ilerleme durumunu denetlemek için size bir URL verilir. Bu durum URI'sı aşağıdaki gibi görünür:

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

Konum üst bilgisi tarafından sağlanan URL, bir GET istek verildiğinde aşağıdaki yanıtları döndürür.

HTTP 202 Accepted - Matris isteği kabul edildi ancak hala işleniyor. Lütfen bir süre sonra yeniden deneyin.

HTTP 200 OK - Matris isteği başarıyla işlendi. Yanıt gövdesi tüm sonuçları içerir.

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

URI Parametreleri

Name	İçinde	Gerekli	Tür	Description
format	path	True	string	Matris Yolu isteği başarıyla kabul edildikten sonra alınan matris kimliği.
api-version	query	True	string	Azure Haritalar API'sinin sürüm numarası.

İstek Başlığı

Name	Gerekli	Tür	Description
x-ms-client-id		string	Hangi hesabın Microsoft Entra ID güvenlik modeliyle birlikte kullanıma yönelik olduğunu belirtir. Azure Haritalar hesabı için benzersiz bir kimliği temsil eder ve Azure Haritalar yönetim düzlemi Hesap API'sinden alınabilir. Azure Haritalar'de Microsoft Entra ID güvenliği kullanmak için rehberlik için aşağıdaki makalelere bakın.

Yanıtlar

Name	Tür	Description
200 OK	RouteMatrixResult	Matris isteği başarıyla işlendi. Yanıt gövdesi tüm sonuçları içerir.
202 Accepted		Yalnızca zaman uyumsuz istek için desteklenir. İstek Kabul Edildi: İstek işlenmek üzere kabul edildi. Sonuçları yeniden denemek veya sonuçlara erişmek için lütfen Konum Üst Bilgisindeki URL'yi kullanın. Headers Location: string
Other Status Codes	ErrorResponse	Beklenmeyen bir hata oluştu.

Name

Tür

Description

200 OK

RouteMatrixResult

Matris isteği başarıyla işlendi. Yanıt gövdesi tüm sonuçları içerir.

202 Accepted

Yalnızca zaman uyumsuz istek için desteklenir. İstek Kabul Edildi: İstek işlenmek üzere kabul edildi. Sonuçları yeniden denemek veya sonuçlara erişmek için lütfen Konum Üst Bilgisindeki URL'yi kullanın.

Headers

Location: string

Other Status Codes

ErrorResponse

Beklenmeyen bir hata oluştu.

Güvenlik

AADToken

Bunlar Microsoft Entra OAuth 2.0 Akışlarıdır. Azure rol tabanlı erişim denetimiyle eşleştirildiğinde, Azure Haritalar REST API'lerine erişimi denetlemek için kullanılabilir. Azure rol tabanlı erişim denetimleri, bir veya daha fazla Azure Haritalar kaynak hesabına veya alt kaynağa erişim tanımlamak için kullanılır. Tüm kullanıcılara, gruplara veya hizmet sorumlularına yerleşik bir rol veya Azure Haritalar REST API'leri için bir veya daha fazla izinden oluşan özel bir rol aracılığıyla erişim verilebilir.

Senaryoları uygulamak için kimlik doğrulama kavramlarını görüntülemenizi öneririz. Özetle, bu güvenlik tanımı belirli API'ler ve kapsamlar üzerinde erişim denetimi yapabilen nesneler aracılığıyla uygulamaları modellemek için bir çözüm sağlar.

Notlar

Bu güvenlik tanımı, uygulamanın erişim istediği Azure Haritalar kaynağı belirtmek için üst bilgi kullanımını x-ms-client-idgerektirir. Bu, Haritalar yönetim API'sinden alınabilir.

Authorization URL, Azure genel bulut örneğine özgüdür. Bağımsız bulutların benzersiz Yetkilendirme URL'leri ve Microsoft Entra ID yapılandırmaları vardır. * Azure rol tabanlı erişim denetimi azure yönetim düzleminden Azure portal, PowerShell, CLI, Azure SDK'ları veya REST API'leri aracılığıyla yapılandırılır. * Azure Haritalar Web SDK'sının kullanımı, bir uygulamanın birden çok kullanım örneği için yapılandırma tabanlı kurulumuna olanak tanır.

Microsoft kimlik platformu hakkında daha fazla bilgi için bkz. Microsoft kimlik platformu genel bakış.

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

Scopes

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

subscription-key

Bu, Azure portal bir Azure Haritalar hesabı İçerik Oluşturucu veya PowerShell, CLI, Azure SDK'ları veya REST API'sini kullandığınızda sağlanan paylaşılan bir anahtardır.

Bu anahtarla, tüm uygulamalar tüm REST API'lere erişebilir. Başka bir deyişle, bu anahtar, verildikleri hesapta ana anahtar olarak kullanılabilir.

Herkese açık uygulamalar için, anahtarınızın güvenli bir şekilde depolanabilmesi için gizli istemci uygulamaları yaklaşımını kullanarak Azure Haritalar REST API'lerine erişmenizi öneririz.

Type: apiKey
In: query

SAS Token

Bu paylaşılan erişim imzası belirteci, Azure portal, PowerShell, CLI, Azure SDK'ları veya REST API'leri aracılığıyla Azure yönetim düzlemi aracılığıyla Azure Haritalar kaynağındaki SAS listeleme işleminden oluşturulur.

Bu belirteçle, tüm uygulamalar Azure rol tabanlı erişim denetimleri ve belirli bir belirteç için kullanım süre sonu, oran ve bölgeler için ayrıntılı denetim ile erişim yetkisine sahip olur. Başka bir deyişle SAS Belirteci, uygulamaların paylaşılan anahtardan daha güvenli bir şekilde erişimi denetlemesine izin vermek için kullanılabilir.

Herkese açık uygulamalar için önerimiz, işleme kötüye kullanımını sınırlamak ve SAS Belirtecini düzenli olarak yenilemek için Harita hesabı kaynağında izin verilen kaynakların belirli bir listesini yapılandırmayı önermektedir.

Type: apiKey
In: header

Örnekler

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

Tanımlar

Name	Description
ErrorAdditionalInfo	Kaynak yönetimi hatası ek bilgileri.
ErrorDetail	Hata ayrıntısı.
ErrorResponse	Hata yanıtı
RouteLegSummary	Yol bölümü için özet nesnesi.
RouteMatrix	Matris sonuç nesnesi
RouteMatrixResult	Bu nesne başarılı bir Yol Matrisi çağrısından döndürülür. Örneğin, 2 çıkış noktası ve 3 hedef sağlanmışsa, her birinde 3 öğe bulunan 2 diziye gidilir. Her öğenin içeriği sorguda sağlanan seçeneklere bağlıdır.
RouteMatrixResultResponse	Giriş matrisindeki geçerli hücrenin yanıt nesnesi.
RouteMatrixSummary	Özet nesnesi

ErrorAdditionalInfo

Kaynak yönetimi hatası ek bilgileri.

Name	Tür	Description
info	object	Ek bilgiler.
type	string	Ek bilgi türü.

ErrorDetail

Hata ayrıntısı.

Name	Tür	Description
additionalInfo	ErrorAdditionalInfo[]	Hata ek bilgileri.
code	string	Hata kodu.
details	ErrorDetail[]	Hata ayrıntıları.
message	string	Hata iletisi.
target	string	Hata hedefi.

ErrorResponse

Hata yanıtı

Name	Tür	Description
error	ErrorDetail	Hata nesnesi.

RouteLegSummary

Yol bölümü için özet nesnesi.

Name	Tür	Description
arrivalTime	string	Rota veya bacak için tahmini varış zamanı. Saat UTC olarakdır.
batteryConsumptionInkWh	number	Elektrikli Tüketim Modeli kullanılarak kilowatt saat (kWh) cinsinden tahmini elektrik enerjisi tüketimi. vehicleEngineType elektrikli olarak ayarlanırsa ve constantSpeedConsumptionInkWhPerHundredkm belirtilirse dahil edilir. BatteryConsumptionInkWh değeri, geri kazanılmış elektrik enerjisini içerir ve bu nedenle negatif olabilir (bu da enerji kazanıldığına işaret eder). Hem maxChargeInkWh hem de currentChargeInkWh belirtilirse, pil şarj düzeyinin maxChargeInkWh değerini asla aşmadığından emin olmak için yeniden iyileşme sınırlanır. MaxChargeInkWh veya currentChargeInkWh belirtilmezse, tüketim hesaplamasında kısıtlanmamış geri alma varsayılır.
departureTime	string	Rota veya bacak için tahmini kalkış saati. Saat UTC olarakdır.
fuelConsumptionInLiters	number	Yanma Tüketimi Modeli kullanılarak litre cinsinden tahmini yakıt tüketimi. vehicleEngineType yanma olarak ayarlanırsa ve constantSpeedConsumptionInLitersPerHundredkm belirtilirse dahil edilir. Değer negatif olmayacaktır.
historicTrafficTravelTimeInSeconds	integer	Zamana bağlı geçmiş trafik verileri kullanılarak hesaplanan tahmini seyahat süresi. Yalnızca computeTravelTimeFor = tümü sorguda kullanılıyorsa dahil edilir.
lengthInMeters	integer	Metre Cinsinden Uzunluk özelliği
liveTrafficIncidentsTravelTimeInSeconds	integer	Gerçek zamanlı hız verileri kullanılarak hesaplanan tahmini seyahat süresi. Yalnızca computeTravelTimeFor = tümü sorguda kullanılıyorsa dahil edilir.
noTrafficTravelTimeInSeconds	integer	Trafik koşullarından (ör. tıkanıklık) dolayı rotada gecikme yaşanmaz gibi hesaplanan tahmini seyahat süresi. Yalnızca computeTravelTimeFor = tümü sorguda kullanılıyorsa dahil edilir.
trafficDelayInSeconds	integer	Trafik bilgilerine göre gerçek zamanlı olayların neden olduğu saniye cinsinden tahmini gecikme. Gelecekte kalkış saatiyle planlanan rotalar için gecikmeler her zaman 0'dır. Farklı türlerdeki trafik bilgilerini kullanarak ek seyahat süreleri döndürmek için computeTravelTimeFor=all parametresinin eklenmesi gerekir.
travelTimeInSeconds	integer	Gerçek zamanlı trafik nedeniyle gecikmeyi içeren saniye cinsinden tahmini seyahat süresi özelliği. Traffic=false travelTimeInSeconds yine de trafik nedeniyle gecikmeyi içerdiğini unutmayın. DepartAt gelecekteyse, seyahat süresi zamana bağlı geçmiş trafik verileri kullanılarak hesaplanır.

RouteMatrix

Matris sonuç nesnesi

Name	Tür	Description
response	RouteMatrixResultResponse	Giriş matrisindeki geçerli hücrenin yanıt nesnesi.
statusCode	integer	Giriş matrisindeki geçerli hücre için StatusCode özelliği.

RouteMatrixResult

Bu nesne başarılı bir Yol Matrisi çağrısından döndürülür. Örneğin, 2 çıkış noktası ve 3 hedef sağlanmışsa, her birinde 3 öğe bulunan 2 diziye gidilir. Her öğenin içeriği sorguda sağlanan seçeneklere bağlıdır.

Name	Tür	Description
formatVersion	string	Sürüm Özelliğini Biçimlendir
matrix	RouteMatrix[]	2 boyutlu yol özetleri dizisi olarak sonuç verir.
summary	RouteMatrixSummary	Özet nesnesi

RouteMatrixResultResponse

Giriş matrisindeki geçerli hücrenin yanıt nesnesi.

Name	Tür	Description
routeSummary	RouteLegSummary	Yol bölümü için özet nesnesi.

RouteMatrixSummary

Özet nesnesi

Name	Tür	Description
successfulRoutes	integer	Yanıttaki başarılı yolların sayısı.
totalRoutes	integer	İstenen toplam yol sayısı. Giriş matrisindeki hücre sayısı.

Route - Get Route Matrix

Zaman Uyumlu Yönlendirme Matrisi İsteği Gönderme

Zaman Uyumsuz Yol Matrisi İsteği Gönderme

Eşitleme Sonuçlarını İndir

Zaman Uyumsuz Sonuçları İndir

URI Parametreleri

İstek Başlığı

Yanıtlar

Güvenlik

AADToken

Notlar

Scopes

subscription-key

SAS Token

Örnekler

Successfully retrieve the status for a route matrix request

Sample Request

Sample Response

Tanımlar

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Ek kaynaklar