Route - Get Route Matrix

Referensi

Layanan:: Maps

Versi API:: 1.0

Gunakan untuk mendapatkan matriks rute yang menunjukkan waktu dan jarak perjalanan untuk semua pasangan yang mungkin dalam daftar asal dan tujuan.

API Get Route Matrix adalah permintaan GET HTTP yang menghitung waktu dan jarak perjalanan untuk semua pasangan yang mungkin dalam daftar asal dan tujuan. Tidak seperti Dapatkan Petunjuk Arah Rute API, yang memberikan instruksi rute terperinci, API ini berfokus pada efisiensi dengan memberi Anda biaya (waktu perjalanan dan jarak) perutean dari setiap asal ke setiap tujuan. Untuk informasi selengkapnya, lihat praktik terbaik untuk layanan Rute Azure Maps.

Untuk setiap asal yang diberikan, layanan menghitung biaya perutean dari asal tersebut ke setiap tujuan tertentu. Kumpulan asal dan kumpulan tujuan dapat dianggap sebagai header kolom dan baris tabel dan setiap sel dalam tabel berisi biaya perutean dari asal ke tujuan untuk sel tersebut. Sebagai contoh, katakanlah perusahaan pengiriman makanan memiliki 20 pengemudi dan mereka perlu menemukan pengemudi terdekat untuk mengambil pengiriman dari restoran. Untuk mengatasi kasus penggunaan ini, mereka dapat memanggil Matrix Route API.

Untuk setiap rute, waktu dan jarak perjalanan dikembalikan. Anda dapat menggunakan biaya komputasi untuk menentukan rute terperinci mana yang akan dihitung menggunakan ROUTE Directions API.

Ukuran maksimum matriks untuk permintaan asinkron 700 dan untuk permintaan sinkronisasi 100 (jumlah asal dikalikan dengan jumlah tujuan).

Kirim Permintaan Matriks Rute Sinkron

Jika skenario Anda memerlukan permintaan sinkron dan ukuran maksimum matriks kurang dari atau sama dengan 100, Anda mungkin ingin membuat permintaan sinkron. Ukuran maksimum matriks untuk API ini 100 (jumlah asal dikalikan dengan jumlah tujuan). Dengan mengingat batasan itu, contoh dimensi matriks yang mungkin adalah: 10x10, 6x8, 9x8 (tidak perlu persegi).

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

Kirim Permintaan Matriks Rute Asinkron

API Asinkron sesuai untuk memproses volume besar permintaan perutean yang relatif kompleks. Saat Anda membuat permintaan dengan menggunakan permintaan asinkron, secara default layanan mengembalikan kode respons 202 di sepanjang URL pengalihan di bidang Lokasi header respons. URL ini harus diperiksa secara berkala sampai data respons atau informasi kesalahan tersedia. Jika parameter waitForResults dalam permintaan diatur ke true, pengguna akan mendapatkan respons 200 jika permintaan selesai di bawah 120 detik.

Ukuran maksimum matriks untuk API ini adalah 700 (jumlah asal dikalikan dengan jumlah tujuan). Dengan mengingat batasan tersebut, contoh dimensi matriks yang mungkin adalah: 50x10, 10x10, 28x25. 10x70 (tidak perlu persegi).

Respons asinkron disimpan selama 24 jam. URL pengalihan mengembalikan respons 404 jika digunakan setelah periode kedaluwarsa.

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

Berikut adalah urutan khas operasi asinkron:

Klien mengirim permintaan Route Matrix GET ke Azure Maps
Server akan merespons dengan salah satu hal berikut:

HTTP 202 Accepted - Permintaan Route Matrix telah diterima.

HTTP Error - Terjadi kesalahan saat memproses permintaan Route Matrix Anda. Ini bisa menjadi 400 Permintaan Buruk atau kode status Kesalahan lainnya.
Jika permintaan Rute Matriks berhasil diterima, header Lokasi dalam respons berisi URL untuk mengunduh hasil permintaan. URI status ini terlihat seperti berikut ini:

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

Klien mengeluarkan permintaan GET pada URL unduhan yang diperoleh di Langkah 3 untuk mengunduh hasilnya

Unduh Hasil Sinkronisasi

Saat Anda membuat permintaan GET untuk Route Matrix Sync API, layanan mengembalikan 200 kode respons untuk permintaan yang berhasil dan array respons. Isi respons akan berisi data dan tidak akan ada kemungkinan untuk mengambil hasilnya nanti.

Unduh Hasil Asinkron

Saat permintaan mengeluarkan respons 202 Accepted, permintaan sedang diproses menggunakan alur asinkron kami. Anda akan diberi URL untuk memeriksa kemajuan permintaan asinkron Anda di header lokasi respons. URI status ini terlihat seperti berikut ini:

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

URL yang disediakan oleh header lokasi akan mengembalikan respons berikut saat permintaan GET dikeluarkan.

HTTP 202 Accepted - Permintaan Matriks diterima tetapi masih diproses. Silakan coba lagi dalam beberapa waktu.

HTTP 200 OK - Permintaan matriks berhasil diproses. Isi respons berisi semua hasilnya.

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

Parameter URI

Nama	Dalam	Diperlukan	Jenis	Deskripsi
format	path	True	string	Id matriks diterima setelah permintaan Rute Matriks berhasil diterima.
api-version	query	True	string	Nomor versi Azure Maps API.

Header Permintaan

Nama	Diperlukan	Jenis	Deskripsi
x-ms-client-id		string	Menentukan akun mana yang ditujukan untuk penggunaan bersama dengan model keamanan ID Microsoft Entra. Ini mewakili ID unik untuk akun Azure Maps dan dapat diambil dari API Akun sarana manajemen Azure Maps. Untuk menggunakan keamanan ID Microsoft Entra di Azure Maps, lihat artikel berikut ini untuk panduan.

Respons

Nama	Jenis	Deskripsi
200 OK	RouteMatrixResult	Permintaan matriks berhasil diproses. Isi respons berisi semua hasilnya.
202 Accepted		Hanya didukung untuk permintaan asinkron. Permintaan Diterima: Permintaan telah diterima untuk diproses. Silakan gunakan URL di Header Lokasi untuk mencoba kembali atau mengakses hasilnya. Header Location: string
Other Status Codes	ErrorResponse	Terjadi kesalahan tak terduga.

Nama

Jenis

Deskripsi

200 OK

RouteMatrixResult

Permintaan matriks berhasil diproses. Isi respons berisi semua hasilnya.

202 Accepted

Hanya didukung untuk permintaan asinkron. Permintaan Diterima: Permintaan telah diterima untuk diproses. Silakan gunakan URL di Header Lokasi untuk mencoba kembali atau mengakses hasilnya.

Header

Location: string

Other Status Codes

ErrorResponse

Terjadi kesalahan tak terduga.

Keamanan

AADToken

Ini adalah Microsoft Entra OAuth 2.0 Flows. Saat dipasangkan dengan akses berbasis peran Azure kontrol dapat digunakan untuk mengontrol akses ke REST API Azure Maps. Kontrol akses berbasis peran Azure digunakan untuk menunjuk akses ke satu atau beberapa akun sumber daya Atau sub-sumber daya Azure Maps. Setiap pengguna, grup, atau perwakilan layanan dapat diberikan akses melalui peran bawaan atau peran kustom yang terdiri dari satu atau beberapa izin ke REST API Azure Maps.

Untuk menerapkan skenario, sebaiknya lihat konsep autentikasi . Singkatnya, definisi keamanan ini menyediakan solusi untuk memodelkan aplikasi melalui objek yang mampu mengontrol akses pada API dan cakupan tertentu.

Catatan

Definisi keamanan ini mengharuskan penggunaan header x-ms-client-id untuk menunjukkan sumber daya Azure Maps mana yang diminta akses aplikasi. Ini dapat diperoleh dari API manajemen Maps.

Authorization URL khusus untuk instans cloud publik Azure. Sovereign cloud memiliki URL Otorisasi yang unik dan konfigurasi ID Microsoft Entra. * Kontrol akses berbasis peran Azure dikonfigurasi dari bidang manajemen Azure melalui portal Microsoft Azure, PowerShell, CLI, Azure SDK, atau REST API. * Penggunaan Azure Maps Web SDK memungkinkan penyiapan berbasis konfigurasi aplikasi untuk beberapa kasus penggunaan.

Untuk informasi selengkapnya tentang platform identitas Microsoft, lihat gambaran umum platform identitas Microsoft .

Jenis: oauth2
Alur: implicit
URL Otorisasi: https://login.microsoftonline.com/common/oauth2/authorize

Cakupan

Nama	Deskripsi
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Ini adalah kunci bersama yang disediakan saat Anda Membuat akun Azure Maps di portal Microsoft Azure atau menggunakan PowerShell, CLI, Azure SDK, atau REST API.

Dengan kunci ini, aplikasi apa pun dapat mengakses semua REST API. Dengan kata lain, kunci ini dapat digunakan sebagai kunci master di akun tempat kunci tersebut dikeluarkan.

Untuk aplikasi yang diekspos secara publik, rekomendasi kami adalah menggunakan pendekatan aplikasi klien rahasia untuk mengakses REST API Azure Maps sehingga kunci Anda dapat disimpan dengan aman.

Jenis: apiKey
Dalam: query

SAS Token

Ini adalah token tanda tangan akses bersama dibuat dari operasi Daftar SAS pada sumber daya Azure Maps melalui bidang manajemen Azure melalui portal Microsoft Azure, PowerShell, CLI, Azure SDK, atau REST API.

Dengan token ini, aplikasi apa pun berwenang untuk mengakses dengan kontrol akses berbasis peran Azure dan kontrol butir halus ke kedaluwarsa, laju, dan wilayah penggunaan untuk token tertentu. Dengan kata lain, Token SAS dapat digunakan untuk memungkinkan aplikasi mengontrol akses dengan cara yang lebih aman daripada kunci bersama.

Untuk aplikasi yang diekspos secara publik, rekomendasi kami adalah mengonfigurasi daftar spesifik asal yang diizinkan pada sumber daya akun peta untuk membatasi penyalahgunaan penyajian dan memperbarui Token SAS secara teratur.

Jenis: apiKey
Dalam: header

Contoh

Successfully retrieve the status for a route matrix request

Permintaan sampel

HTTP

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

Respon sampel

Kode status:: 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
  }
}

Kode status:: 202

Definisi

Nama	Deskripsi
ErrorAdditionalInfo	Info tambahan kesalahan manajemen sumber daya.
ErrorDetail	Detail kesalahan.
ErrorResponse	Respons kesalahan
RouteLegSummary	Objek ringkasan untuk bagian rute.
RouteMatrix	Objek hasil matriks
RouteMatrixResult	Objek ini dikembalikan dari panggilan Route Matrix yang berhasil. Misalnya, jika 2 asal dan 3 tujuan disediakan, akan ada 2 array dengan masing-masing 3 elemen. Konten setiap elemen bergantung pada opsi yang disediakan dalam kueri.
RouteMatrixResultResponse	Objek respons sel saat ini dalam matriks input.
RouteMatrixSummary	Objek ringkasan

ErrorAdditionalInfo

Info tambahan kesalahan manajemen sumber daya.

Nama	Jenis	Deskripsi
info	object	Info tambahan.
type	string	Jenis info tambahan.

ErrorDetail

Detail kesalahan.

Nama	Jenis	Deskripsi
additionalInfo	ErrorAdditionalInfo[]	Info tambahan kesalahan.
code	string	Kode kesalahan.
details	ErrorDetail[]	Detail kesalahan.
message	string	Pesan kesalahan.
target	string	Target kesalahan.

ErrorResponse

Respons kesalahan

Nama	Jenis	Deskripsi
error	ErrorDetail	Objek kesalahan.

RouteLegSummary

Objek ringkasan untuk bagian rute.

Nama	Jenis	Deskripsi
arrivalTime	string	Perkiraan waktu kedatangan untuk rute atau kaki. Waktu dalam UTC.
batteryConsumptionInkWh	number	Perkiraan konsumsi energi listrik dalam jam kilowatt (kWh) menggunakan Model Konsumsi Listrik. Disertakan jika vehicleEngineType diatur ke listrik dan konstantaSpeedConsumptionInkWhPerHundredkm ditentukan. Nilai bateraiConsumptionInkWh mencakup energi listrik yang disembuhkan dan karenanya bisa negatif (yang menunjukkan mendapatkan energi). Jika maxChargeInkWh dan currentChargeInkWh ditentukan, pemulihan akan dibatasi untuk memastikan bahwa tingkat pengisian daya baterai tidak pernah melebihi maxChargeInkWh. Jika maxChargeInkWh atau currentChargeInkWh tidak ditentukan, pemulihan yang tidak dibatasi diasumsikan dalam perhitungan konsumsi.
departureTime	string	Perkiraan waktu keberangkatan untuk rute atau kaki. Waktu dalam UTC.
fuelConsumptionInLiters	number	Perkiraan konsumsi bahan bakar dalam liter menggunakan Model Konsumsi Pembakaran. Disertakan jika vehicleEngineType diatur ke pembakaran dan constantSpeedConsumptionInLitersPerHundredkm ditentukan. Nilainya akan non-negatif.
historicTrafficTravelTimeInSeconds	integer	Perkiraan waktu perjalanan dihitung menggunakan data lalu lintas historis yang bergantung pada waktu. Disertakan hanya jika computeTravelTimeFor = semua digunakan dalam kueri.
lengthInMeters	integer	Properti Panjang Dalam Meter
liveTrafficIncidentsTravelTimeInSeconds	integer	Estimasi waktu perjalanan dihitung menggunakan data kecepatan real time. Disertakan hanya jika computeTravelTimeFor = semua digunakan dalam kueri.
noTrafficTravelTimeInSeconds	integer	Perkiraan waktu perjalanan dihitung seolah-olah tidak ada keterlambatan pada rute karena kondisi lalu lintas (misalnya kemacetan). Disertakan hanya jika computeTravelTimeFor = semua digunakan dalam kueri.
trafficDelayInSeconds	integer	Estimasi keterlambatan dalam detik yang disebabkan oleh insiden real-time sesuai dengan informasi lalu lintas. Untuk rute yang direncanakan dengan waktu keberangkatan di masa mendatang, penundaan selalu 0. Untuk mengembalikan waktu perjalanan tambahan menggunakan berbagai jenis informasi lalu lintas, parameter computeTravelTimeFor=all perlu ditambahkan.
travelTimeInSeconds	integer	Perkiraan waktu perjalanan dalam detik properti yang mencakup keterlambatan karena lalu lintas real time. Perhatikan bahwa bahkan ketika traffic=false travelTimeInSeconds masih menyertakan penundaan karena lalu lintas. Jika DepartAt di masa mendatang, waktu perjalanan dihitung menggunakan data lalu lintas historis yang bergantung pada waktu.

RouteMatrix

Objek hasil matriks

Nama	Jenis	Deskripsi
response	RouteMatrixResultResponse	Objek respons sel saat ini dalam matriks input.
statusCode	integer	Properti StatusCode untuk sel saat ini dalam matriks input.

RouteMatrixResult

Objek ini dikembalikan dari panggilan Route Matrix yang berhasil. Misalnya, jika 2 asal dan 3 tujuan disediakan, akan ada 2 array dengan masing-masing 3 elemen. Konten setiap elemen bergantung pada opsi yang disediakan dalam kueri.

Nama	Jenis	Deskripsi
formatVersion	string	Properti Format Versi
matrix	RouteMatrix[]	Hasil sebagai array 2 dimensi ringkasan rute.
summary	RouteMatrixSummary	Objek ringkasan

RouteMatrixResultResponse

Objek respons sel saat ini dalam matriks input.

Nama	Jenis	Deskripsi
routeSummary	RouteLegSummary	Objek ringkasan untuk bagian rute.

RouteMatrixSummary

Objek ringkasan

Nama	Jenis	Deskripsi
successfulRoutes	integer	Jumlah rute yang berhasil dalam respons.
totalRoutes	integer	Jumlah total rute yang diminta. Jumlah sel dalam matriks input.

Bagikan melalui

Route - Get Route Matrix

Kirim Permintaan Matriks Rute Sinkron

Kirim Permintaan Matriks Rute Asinkron

Unduh Hasil Sinkronisasi

Unduh Hasil Asinkron

Parameter URI

Header Permintaan

Respons

Keamanan

AADToken

Catatan

Cakupan

subscription-key

SAS Token

Contoh

Successfully retrieve the status for a route matrix request

Permintaan sampel

Respon sampel

Definisi

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

Sumber Daya Tambahan: