Bagikan melalui

API Kueri Azure Time Series Insights Gen1

  • Artikel

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

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-12

  • Contoh 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-12

  • Contoh 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-12

  • Struktur 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 properties dikembalikan 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 null nilai dimensi, 0 nilai untuk hitungan, dan null nilai 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 null nilai dimensi, 0 nilai untuk hitungan, dan null nilai 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 null untuk 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.