API Kueri Azure Time Series Insights Gen1
Perhatian
Ini adalah artikel Gen1.
Artikel ini menjelaskan berbagai REST Query API. REST API adalah titik akhir layanan yang mendukung set operasi HTTP (metode), yang memungkinkan Anda untuk mengkueri lingkungan Azure Time Series Insights Gen1.
Penting
- Azure Time Series Insights Gen1 menggunakan Protokol HTTPS untuk Get Environments, Get Environment Availability, Get Metadata, Get Environment Events, dan Get Environment Aggregates API.
- Azure Time Series Insights Gen1 menggunakan Protokol WebSocket Secure (WSS) untuk Dapatkan Peristiwa Lingkungan Yang Dialirkan dan Dapatkan API Streaming Agregat.
Dapatkan API Lingkungan
GET Environments API mengembalikan daftar lingkungan yang diizinkan untuk diakses oleh pemanggil.
Titik akhir dan operasi:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Contoh isi permintaan: Tidak berlaku
Contoh isi respons:
{ "environments": [ { "displayName":"Sensors", "environmentFqdn": "00000000-0000-0000-0000-000000000000.env.timeseries.azure.com", "environmentId":"00000000-0000-0000-0000-000000000000", "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/RdxProdAssetsEastUs/providers/Microsoft.TimeSeriesInsights/environments/Sensors", "roles": [ "Reader", "Contributor" ] } ] }Catatan
Lingkungan properti responsFqdn adalah nama domain unik yang sepenuhnya memenuhi syarat untuk lingkungan yang digunakan dalam permintaan API Kueri per lingkungan.
Mendapatkan API Ketersediaan Lingkungan
Get Environment Availability API mengembalikan distribusi jumlah peristiwa selama tanda waktu peristiwa $ts. Ketersediaan lingkungan di-cache, dan waktu respons tidak bergantung pada jumlah peristiwa di lingkungan.
Tip
Get Environment Availability API dapat digunakan untuk menginisialisasi pengalaman antarmuka pengguna front-end.
Titik akhir dan operasi:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Contoh isi permintaan: Tidak berlaku
Contoh isi respons:
{ "range": { "from": "2016-08-01T01:02:03Z", "to": "2016-08-31T03:04:05Z" }, "intervalSize": "1h", "distribution": { "2016-08-01T00:00:00Z": 123, "2016-08-31T03:00:00Z": 345 } }Objek kosong dikembalikan untuk lingkungan tanpa peristiwa.
Dapatkan API Metadata Lingkungan
Get Environment Metadata API mengembalikan metadata lingkungan untuk rentang pencarian tertentu. Metadata dikembalikan sebagai sekumpulan referensi properti. Azure Time Series Insights Gen1 secara internal menyimpan cache dan perkiraan metadata dan dapat mengembalikan lebih banyak properti yang ada dalam peristiwa yang tepat dalam rentang pencarian.
Titik akhir dan operasi:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Struktur payload input:
- Klausa rentang pencarian (wajib)
Contoh isi permintaan:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Contoh isi respons:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }Array kosong
propertiesdikembalikan saat lingkungan kosong atau tidak ada peristiwa dalam rentang pencarian.Properti bawaan tidak dikembalikan dalam daftar properti.
Dapatkan API Peristiwa Lingkungan
Get Environment Events API mengembalikan daftar peristiwa mentah yang cocok dengan rentang pencarian dan predikat.
Titik akhir dan operasi:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Struktur payload input:
- Klausa rentang pencarian (wajib)
- Klausa predikat (opsional)
- Klausa batas (wajib)
Contoh isi permintaan:
{ "searchSpan": { "from": { "dateTime": "2019-12-30T00:00:00.000Z" }, "to": { "dateTime": "2019-12-31T23:00:00.000Z" } }, "predicateString": "PointValue.Double = 3.14", "top": { "sort": [ { "input": { "builtInProperty": "$ts" }, "order": "Asc" } ], "count": 1000 } }Catatan
- Pengurutan berlapis (yaitu, pengurutan menurut dua properti atau lebih) saat ini tidak didukung.
- Peristiwa dapat diurutkan dan dibatasi pada bagian atas.
- Pengurutan didukung pada semua jenis properti. Pengurutan bergantung pada operator perbandingan yang ditentukan untuk ekspresi Boolean.
Contoh isi respons:
{ "warnings": [], "events": [ { "schema": { "rid": 0, "$esn" : "buildingsensors", "properties" : [{ "name" : "sensorId", "type" : "String" }, { "name" : "sensorValue", "type" : "String" }] }, "$ts" : "2016-08-30T23:20:00Z", "values" : ["IndoorTemperatureSensor", 72.123] }, { "schemaRid" : 0, "$ts" : "2016-08-30T23:21:00Z", "values" : ["IndoorTemperatureSensor", 72.345] } ] }
Mendapatkan API Aliran Peristiwa Lingkungan
GET Environment Events Streamed API mengembalikan daftar peristiwa mentah yang cocok dengan rentang pencarian dan predikat.
API ini menggunakan Protokol Aman WebSocket untuk melakukan streaming dan mengembalikan hasil parsial. Ini selalu mengembalikan peristiwa tambahan. Artinya, pesan baru bersifat aditif untuk pesan sebelumnya. Pesan baru berisi peristiwa baru yang tidak ada di pesan sebelumnya. Pesan sebelumnya harus disimpan saat pesan baru ditambahkan.
Titik akhir dan operasi:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Struktur payload input:
- Klausa rentang pencarian (wajib)
- Klausa predikat (opsional)
- Klausa batas (wajib)
Contoh pesan permintaan:
{ "headers" : { "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>", "x-ms-client-request-id" : "132gae-w343-41a1-2342-w23ta4532" }, "content": { "searchSpan": { "from": "2017-04-30T23:00:00.000Z", "to": "2017-05-01T00:00:00.000Z" }, "top": { "sort": [ { "input": { "builtInProperty": "$ts" }, "order": "Asc" } ], "count": 1000 } } }Catatan
- Pengurutan berlapis (yaitu, pengurutan menurut dua properti atau lebih) saat ini tidak didukung.
- Peristiwa dapat diurutkan dan dibatasi pada bagian atas.
- Pengurutan didukung pada semua jenis properti. Pengurutan bergantung pada operator perbandingan yang ditentukan untuk ekspresi Boolean.
Contoh pesan respons:
{ "headers": { "x-ms-request-id": "a325-a345-sy43-w332-a4qat36a2262" }, "content": { "events": [ { "schema": { "rid": 0, "$esn": "devicedata", "properties": [ { "name": "Id", "type": "String" }, { "name": "TemperatureControlLevel", "type": "Double" }, { "name": "Type", "type": "String" }, { "name": "UnitVersion", "type": "String" }, { "name": "Station", "type": "String" }, { "name": "ProductionLine", "type": "String" }, { "name": "Factory", "type": "String" }, { "name": "Timestamp", "type": "DateTime" } ] }, "$ts": "2017-04-30T23:00:00Z", "values": [ "82faa3c1-f11d-44f5-a1ca-e448f6123eee", 0.9835468282931982, "temp control rate", "1.1.7.0", "Station5", "Line1", "Factory2", "2017-04-30T23:00:00Z" ] }, { "schemaRid": 0, "$ts": "2017-04-30T23:00:00Z", "values": [ "acb2f926-62cc-4a88-9246-94a26ebcaee3", 0.8542095381579537, "temp control rate", "1.1.7.0", "Station2", "Line1", "Factory3", "2017-04-30T23:00:00Z" ] } ] }, "warnings": [], "percentCompleted": 100 }
Mendapatkan API Agregat Lingkungan
Get Environment Aggregates API mengelompokkan peristiwa dengan properti tertentu karena secara opsional mengukur nilai properti lain.
Catatan
Batas wadah mendukung nilai 10ⁿ, 2×10ⁿ, atau nilai 5×10ⁿ untuk menyelaraskan dengan dan mendukung histogram numerik dengan lebih baik.
Titik akhir dan operasi:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktur payload input:
- Klausa rentang pencarian (wajib)
- Klausa predikat (opsional)
- Klausul agregat (wajib)
Contoh isi permintaan:
{ "searchSpan": { "from": { "dateTime": "2019-12-30T00:00:00.000Z" }, "to": { "dateTime": "2019-12-31T23:00:00.000Z" } }, "predicateString": "PointValue.Double > 1000", "aggregates": [ { "dimension": { "uniqueValues": { "input": { "property": "iothub-connection-device-id", "type": "String" }, "take": 100 } }, "aggregate": { "dimension": { "dateHistogram": { "input": { "builtInProperty": "$ts" }, "breaks": { "size": "1h" } } }, "measures": [ { "min": { "input": { "property": "series.flowRate", "type": "Double" } } }, { "count": {} } ] } } ] }Contoh isi respons:
{ "aggregates": [ { "dimension": [ "Test-Device-A11342" ], "aggregate": { "dimension": [ "2019-12-30T23:00:00Z", "2019-12-31T00:00:00Z" ], "measures": [ [ [ 0.319668575730514, 2678 ], [ 0.08442680357734211, 1238 ] ] ] } } ], "warnings": [] }Jika tidak ada ekspresi pengukuran yang ditentukan dan daftar peristiwa kosong, respons akan kosong.
Jika pengukuran ada, respons berisi satu rekaman dengan
nullnilai dimensi,0nilai untuk hitungan, dannullnilai untuk jenis pengukuran lainnya.
Mendapatkan API Aliran Agregat Lingkungan
Get Environment Aggregates Streamed API mengelompokkan peristiwa dengan properti tertentu karena secara opsional mengukur nilai properti lain:
- API ini menggunakan Protokol Aman WebSocket untuk streaming dan mengembalikan hasil parsial.
- Ini selalu mengembalikan penggantian (rekam jepret) dari semua nilai.
- Paket sebelumnya dapat dibuang oleh klien.
Catatan
Batas wadah mendukung nilai 10ⁿ, 2×10ⁿ, atau nilai 5×10ⁿ untuk menyelaraskan dengan dan mendukung histogram numerik dengan lebih baik.
Titik akhir dan operasi:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktur payload input:
- Klausa rentang pencarian (wajib)
- Klausa predikat (opsional)
- Klausul agregat (wajib)
Contoh pesan permintaan:
{ "headers":{ "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>" }, "content":{ "predicate":{ "predicateString":"" }, "searchSpan":{ "from":"2017-04-30T23:00:00.000Z", "to":"2017-05-01T00:00:00.000Z" }, "aggregates":[{ "dimension":{ "dateHistogram":{ "input":{ "builtInProperty":"$ts" }, "breaks":{ "size":"1m" } } }, "measures":[{ "count":{} }] }] } }Contoh pesan respons:
{ "headers":{ "x-ms-request-id":"abc3243-23af-23ad-3224s-a32525age" }, "content":[ { "dimension":[ "2017-04-30T23:00:00Z", "2017-04-30T23:01:00Z", "2017-04-30T23:02:00Z", "2017-04-30T23:03:00Z", "2017-04-30T23:04:00Z" ], "measures":[ [ 722 ], [ 721 ], [ 722 ], [ 721 ], [ 722 ] ] } ], "warnings":[ ], "percentCompleted":100 }Jika tidak ada ekspresi pengukuran yang ditentukan dan daftar peristiwa kosong, respons akan kosong.
Jika pengukuran ada, respons berisi satu rekaman dengan
nullnilai dimensi,0nilai untuk hitungan, dannullnilai untuk jenis pengukuran lainnya.
Batas
Batas berikut diterapkan selama eksekusi kueri untuk cukup memanfaatkan sumber daya di antara beberapa lingkungan dan pengguna:
| API yang berlaku | Nama batas | Nilai batas | SKU terpengaruh | Catatan |
|---|---|---|---|---|
| Semua | Ukuran permintaan maks | 32 KB | S1, S2 | |
| Dapatkan Ketersediaan Lingkungan, Dapatkan Metadata Lingkungan, Dapatkan Peristiwa Lingkungan, Dapatkan Agregat Lingkungan Yang Dialirkan | Jumlah maksimum permintaan bersamaan per lingkungan | 10 | S1, S2 | |
| Dapatkan Peristiwa Lingkungan, Dapatkan Agregat Lingkungan Yang Dialirkan | Ukuran respons maks | 16 MB | S1, S2 | |
| Dapatkan Peristiwa Lingkungan, Dapatkan Agregat Lingkungan Yang Dialirkan | Jumlah maksimum referensi properti unik dalam predikat, termasuk ekspresi string predikat | 50 | S1, S2 | |
| Dapatkan Peristiwa Lingkungan, Dapatkan Agregat Lingkungan Yang Dialirkan | Istilah pencarian teks lengkap maks tanpa referensi properti dalam string predikat | 2 | S1, S2 | Contoh: HAS 'abc', 'abc' |
| Dapatkan Peristiwa Lingkungan | Jumlah maksimum peristiwa sebagai respons | 10.000 | S1, S2 | |
| Mendapatkan Agregat Lingkungan Yang Dialirkan | Jumlah dimensi maksimum | 5 | S1, S2 | |
| Mendapatkan Agregat Lingkungan Yang Dialirkan | Kardinalitas total maksimum di semua dimensi | 150.000 | S1, S2 | |
| Mendapatkan Agregat Lingkungan Yang Dialirkan | Jumlah ukuran maksimum | 20 | S1, S2 |
Penanganan dan resolusi kesalahan
Perilaku Properti Tidak Ditemukan
Untuk properti yang direferensikan dalam kueri, baik sebagai bagian dari predikat atau bagian dari agregat (pengukuran), secara default, kueri mencoba menyelesaikan properti dalam rentang pencarian global lingkungan. Jika properti ditemukan, kueri berhasil. Jika properti tidak ditemukan, kueri gagal.
Namun, Anda dapat memodifikasi perilaku ini untuk memperlakukan properti sebagai yang ada tetapi dengan null nilai jika tidak ada di lingkungan. Anda melakukan ini dengan mengatur header x-ms-property-not-found-behavior permintaan opsional dengan nilai UseNull.
Nilai yang mungkin untuk header permintaan adalah UseNull atau ThrowError (default). Saat Anda menetapkan UseNull sebagai nilai, kueri akan berhasil meskipun properti tidak ada, dan respons akan berisi peringatan yang menampilkan properti yang tidak ditemukan.
Melaporkan properti yang belum terselesaikan
Anda dapat menentukan referensi properti untuk predikat, dimensi, dan ekspresi pengukuran. Jika properti dengan nama dan jenis tertentu tidak ada untuk rentang pencarian tertentu, upaya dilakukan untuk menyelesaikan properti selama rentang waktu global.
Bergantung pada keberhasilan resolusi, peringatan atau kesalahan berikut mungkin dipancarkan:
- Jika properti ada di lingkungan selama rentang waktu global, properti diselesaikan dengan tepat, dan peringatan dipancarkan untuk memberi tahu Anda bahwa nilai properti ini adalah
nulluntuk rentang pencarian tertentu. - Jika properti tidak ada di lingkungan, kesalahan dipancarkan, dan eksekusi kueri gagal.
Respons kesalahan
Jika eksekusi kueri gagal, payload respons JSON berisi respons kesalahan dengan struktur berikut:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
Di sini, innerError bersifat opsional. Selain kesalahan dasar, seperti permintaan cacat, kesalahan berikut dikembalikan:
| Kode status HTTP | Kode kesalahan | Contoh pesan kesalahan | Kemungkinan kode kesalahan dalam |
|---|---|---|---|
| 400 | InvalidApiVersion | "API versi '2016' tidak didukung. Versi yang didukung adalah '2016-12-12'." | |
| 400 | InvalidInput | "Tidak dapat mengurai string predikat." | PredicateStringParseError |
| 400 | InvalidInput | "Tidak dapat menerjemahkan string predikat." | InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Beberapa agregat tidak didukung." | |
| 400 | InvalidInput | "Properti predikat tidak ditemukan." | PropertyNotFound |
| 400 | InvalidInput | "Ukur properti tidak ditemukan." | PropertyNotFound |
| 400 | InvalidInput | "Properti dimensi tidak ditemukan." | PropertyNotFound |
| 400 | InvalidInput | "Jumlah ukuran melebihi batas." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Kedalaman agregat melebihi batas." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Total kardinalitas melebihi batas." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Properti 'dari' hilang." | BreaksPropertyMissing |
| 400 | InvalidInput | "Properti 'ke' hilang." | BreaksPropertyMissing |
| 400 | InvalidInput | "Ukuran permintaan melebihi batas." | RequestSizeExceededLimit |
| 400 | InvalidInput | "Ukuran respons melebihi batas." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Jumlah peristiwa melebihi batas." | EventCountExceededLimit |
| 400 | InvalidInput | "Jumlah referensi properti melebihi batas." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Hanya permintaan WebSocket yang diizinkan di jalur 'agregat'." | |
| 400 | InvalidUrl | "URL permintaan '/a/b' tidak dapat diurai." | |
| 408 | RequestTimeout | "Waktu permintaan habis setelah '30' detik." | |
| 503 | TooManyRequests | "Jumlah permintaan bersamaan '10' terlampaui untuk lingkungan '95880732-01b9-44ea-8d2d-4d764dfe1904'." | EnvRequestLimitExceeded |
Peringatan
Respons API Kueri mungkin berisi daftar peringatan sebagai "warnings" entri di bawah akar respons HTTP atau pesan respons WebSocket. Saat ini peringatan dihasilkan jika properti tidak ditemukan untuk rentang pencarian tertentu tetapi ditemukan di lingkungan untuk rentang waktu global. Ini juga dihasilkan ketika header x-ms-property-not-found-behavior diatur ke UseNull dan properti yang dirujuk tidak ada bahkan dalam rentang pencarian global.
Setiap objek peringatan mungkin berisi bidang berikut:
| Nama bidang | Jenis bidang | Catatan |
|---|---|---|
| code | String | Salah satu kode peringatan yang telah ditentukan sebelumnya |
| message | String | Pesan peringatan terperinci |
| target | String | Jalur JSON yang dipisahkan titik ke entri payload input JSON menyebabkan peringatan |
| warningDetails | Kamus | Opsional; detail peringatan tambahan (misalnya, posisi dalam string predikat) |
Kode berikut menyajikan contoh peringatan untuk predikat, string predikat dalam predikat, dimensi, dan pengukuran:
"warnings": [
{
"code": "PropertyNotFound",
"message": "Predicate property 'X' of type 'String' is not found in local search span.",
"target": "predicate.and[0].eq.left.property.name"
},
{
"code": "PropertyNotFound",
"message": "Predicate string property 'X' is not found in local search span.",
"target": "predicate.and[1].predicateString",
"warningDetails": {
"startPos": 1,
"endPos": 2,
"line": 1,
"col": 1
}
},
{
"code": "PropertyNotFound",
"message": "Dimension property 'X' of type 'String' is not found in local search span.",
"target": "aggregates.dimension.uniqueValues.input.property"
},
{
"code": "PropertyNotFound",
"message": "Measure property 'X' of type 'String' is not found in local search span.",
"target": "aggregates.aggregates.measures[0].min.input.property"
}
]
Lihat juga
Untuk informasi selengkapnya tentang pendaftaran aplikasi dan model pemrograman Azure Active Directory, lihat Azure Active Directory untuk pengembang.
Untuk mempelajari tentang parameter permintaan dan autentikasi, lihat Autentikasi dan otorisasi.
Alat yang membantu menguji permintaan dan respons HTTP meliputi:
- Fiddler. Proksi penelusuran kesalahan web gratis ini dapat mencegat permintaan REST Anda, sehingga Anda dapat mendiagnosis pesan permintaan dan respons HTTP.
- JWT.io. Anda dapat menggunakan alat ini untuk dengan cepat membuang klaim dalam token pembawa Anda lalu memvalidasi kontennya.
- Tukang pos. Ini adalah alat pengujian permintaan dan respons HTTP gratis untuk men-debug REST API.
Pelajari selengkapnya tentang Azure Time Series Insights Gen1 dengan meninjau dokumentasi Gen1.