Azure Time Series Analizler 1. Nesil Sorgu API'si

Dikkat

Bu bir 1. Nesil makalesi.

Bu makalede çeşitli REST Sorgu API'leri açıklanmıştır. REST API'leri, Azure Time Series ve 1. Nesil ortamlarını sorgulamaya olanak sağlayan HTTP işlem kümelerini (yöntemler) destekleyen Analizler uç noktalarıdır.

Önemli

  • Azure Time Series Analizler 1. Nesil; Ortamları Al, OrtamKullanılabilirliğini Al,Meta Verileri Al,Ortam Olaylarını Al ve Ortam Toplamlarını Al API'leri için HTTPS Protokolünü kullanır.
  • Azure Time Series Analizler 1. Nesil, Ortam Olaylarını Akışa Al ve Akışa Alınan Toplamları Al API'leri için WebSocket Secure (WSS) Protokolünü kullanır.

Ortam Al API'si

Ortamları Al API'si, çağıranın erişim yetkisine sahip olduğu ortamların listesini döndürür.

  • Uç nokta ve işlem:

    GET https://api.timeseries.azure.com/environments?api-version=2016-12-12
    
  • Örnek istek gövdesi: Uygulanamaz

  • Örnek yanıt gövdesi:

    {
      "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"
          ]
        }
      ]
    }
    

    Not

    environmentFqdn yanıt özelliği, ortam başına Sorgu API'si isteklerinde kullanılan ortam için benzersiz, tam etki alanı adıdır.

Ortam Kullanılabilirliği API'sini al

Ortam Kullanılabilirliğini Al API'si, olay sayısı dağıtımını olay zaman damgası üzerinden$ts. Ortam kullanılabilirliği önbelleğe alınmış ve yanıt süresi bir ortamdaki olayların sayısına bağlı değildir.

İpucu

Ortam Kullanılabilirliğini Al API'si, ön uç kullanıcı arabirimi deneyimini başlatmak için kullanılabilir.

  • Uç nokta ve işlem:

    GET https://<environmentFqdn>/availability?api-version=2016-12-12
    
  • Örnek istek gövdesi: Uygulanamaz

  • Örnek yanıt gövdesi:

    {
      "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
      }
    }
    

    Boş bir nesne hiçbir olay ile ortamlar için döndürülür.

Ortam Meta Verileri API'sini al

Ortam Meta Verilerini Al API'si, belirli bir arama aralığı için ortam meta verilerini döndürür. Meta veriler özellik başvuruları kümesi olarak döndürülür. Azure Time Series Analizler 1. Nesil, meta verileri önbelleğe alır ve yaklaşık olarak önbelleğe alır ve arama süresinde tam olaylarda mevcut olan daha fazla özellik getirebilirsiniz.

  • Uç nokta ve işlem:

    POST https://<environmentFqdn>/metadata?api-version=2016-12-12
    
  • Giriş yükü yapısı:

    • Search span yan tümcesi (zorunlu)
  • Örnek istek gövdesi:

    {
       "searchSpan": {
         "from": {"dateTime":"2016-08-01T00:00:00.000Z"},
         "to": {"dateTime":"2016-08-31T00:00:00.000Z"}
       }
    }
    
  • Örnek yanıt gövdesi:

    {
       "properties": [
         {
           "name": "sensorId",
           "type": "String"
         },
         {
           "name": "sensorValue",
           "type": "Double"
         },
         {
           "name": "iothub-connection-device-id",
           "type": "String"
         }
       ]
    }
    

    Ortam properties boş olduğunda veya arama süresinde olay yoksa boş bir dizi döndürülür.

    Yerleşik özellikler, özellikler listesinde döndürülz.

Ortam Olaylarını Al API'si

Ortam Olaylarını Al API'si, arama aralığı ve hazırlıkla eşan ham olayların listesini döndürür.

  • Uç nokta ve işlem:

    POST https://<environmentFqdn>/events?api-version=<apiVersion>
    
  • Giriş yükü yapısı:

    • Search span yan tümcesi (zorunlu)
    • Predicate yan tümcesi (isteğe bağlı)
    • Limit yan tümcesi (zorunlu)
  • Örnek istek gövdesi:

    {
      "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
      }
    }
    

    Not

    • İç içe sıralama (yani iki veya daha fazla özelle sıralama) şu anda desteklenmiyor.
    • Olaylar sıralanmış ve üst sınırlanmış olabilir.
    • Sıralama tüm özellik türlerinde de kullanılabilir. Sıralama, Boole ifadeleri için tanımlanan karşılaştırma işleçlerini temel almaktadır.
  • Örnek yanıt gövdesi:

    {
      "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]
        }
      ]
    }
    

Ortam Olaylarını Akışlı API'sini al

Ortam Olaylarını Akışa Al API'si, arama aralığı ve önk aranacak ham olayların listesini döndürür.

Bu API, akış yapmak ve kısmi sonuçlar dönmek için WebSocket Güvenli Protokolü kullanır. Her zaman ek olaylar döndürür. Başka bir ifadeyle, yeni ileti önceki iletiye eklenebilir. Yeni ileti, önceki iletide yer alan yeni olayları içerir. Yeni ileti ekleniyorken önceki ileti tutulmalıdır.

  • Uç nokta ve işlem:

    GET wss://<environmentFqdn>/events?api-version=<apiVersion>
    
  • Giriş yükü yapısı:

    • Search span yan tümcesi (zorunlu)
    • Predicate yan tümcesi (isteğe bağlı)
    • Limit yan tümcesi (zorunlu)
  • Örnek istek iletisi:

    {
      "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
        }
      }
    }
    

    Not

    • İç içe sıralama (yani iki veya daha fazla özelle sıralama) şu anda desteklenmiyor.
    • Olaylar sıralanmış ve üst sınırlanmış olabilir.
    • Sıralama tüm özellik türlerinde de kullanılabilir. Sıralama, Boole ifadeleri için tanımlanan karşılaştırma işleçlerini temel almaktadır.
  • Örnek yanıt iletisi:

    {
      "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
    }
    

Ortam Toplamları API'sini al

Get Environment Aggregates API'si, isteğe bağlı olarak diğer özelliklerin değerlerini ölçüp olayları belirtilen bir özeleğe göre gruplar.

Not

Demet sınırları, 10ⁿ, 2×10ⁿ veya 5×10ⁿ değerleri destekler ve sayısal histogramları daha iyi destekler.

  • Uç nokta ve işlem:

    POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>
    
  • Giriş yükü yapısı:

    • Search span yan tümcesi (zorunlu)
    • Predicate yan tümcesi (isteğe bağlı)
    • Aggregates tümcesi (zorunlu)
  • Örnek istek gövdesi:

    {
     "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": {}
             }
           ]
         }
       }
     ]
    }
    
  • Örnek yanıt gövdesi:

    {
      "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": []
    }
    

    Hiçbir ölçü ifadesi belirtilmezse ve olay listesi boşsa yanıt boş olur.

    Ölçüler varsa yanıt, boyut değerine, sayı değerine ve diğer ölçü türlerine yönelik bir değere sahip null tek bir kayıt 0 null içerir.

Akışlı Ortam Toplamları API'sini Al

Get Environment Aggregates Streamed API'si, isteğe bağlı olarak diğer özelliklerin değerlerini ölçüp olayları belirtilen bir özeleğe göre gruplar:

  • Bu API, akış yapmak ve kısmi sonuçlar almak için WebSocket Güvenli Protokolü'dür.
  • Her zaman tüm değerlerin yerine (anlık görüntü) döndürür.
  • Önceki paketler istemci tarafından atılır.

Not

Demet sınırları, 10ⁿ, 2×10ⁿ veya 5×10ⁿ değerleri destekler ve sayısal histogramları daha iyi destekler.

  • Uç nokta ve işlem:

    GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>
    
  • Giriş yükü yapısı:

    • Search span yan tümcesi (zorunlu)
    • Predicate yan tümcesi (isteğe bağlı)
    • Aggregates tümcesi (zorunlu)
  • Örnek istek iletisi:

    {
      "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":{}
          }]
        }]
      }
    }
    
  • Örnek yanıt iletileri:

    {  
      "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
    }
    

    Hiçbir ölçü ifadesi belirtilmezse ve olay listesi boşsa yanıt boş olur.

    Ölçüler varsa yanıt, boyut değerine, sayı değerine ve diğer ölçü türlerine yönelik bir değere sahip null tek bir kayıt 0 null içerir.

Sınırlar

Birden çok ortam ve kullanıcı arasında kaynakları adil bir şekilde kullanmak için sorgu yürütme sırasında aşağıdaki sınırlar uygulanır:

Geçerli API'ler Sınır adı Sınır değeri Etkilenen SKUS'lar Notlar
Tümü En fazla istek boyutu 32 KB S1, S2
Ortam Kullanılabilirliğini Al, Ortam Meta Verilerini Al, Ortam Olaylarını Al, Akışa Alınan Ortam Toplamlarını Al Ortam başına en fazla eş zamanlı istek sayısı 10 S1, S2
Ortam Olaylarını Al, Akışa Alınan Ortam Toplamlarını Al Maksimum yanıt boyutu 16mb S1, S2
Ortam Olaylarını Al, Akışa Alınan Ortam Toplamlarını Al Kaynak dize ifadeleri de dahil olmak üzere, birkate içinde en fazla benzersiz özellik başvurusu sayısı 50 S1, S2
Ortam Olaylarını Al, Akışa Alınan Ortam Toplamlarını Al Koşullar dizesinde özellik başvurusu olmayan maksimum tam metin arama terimleri 2 S1, S2 Örnek: HAS 'abc' , 'abc'
Ortam Olaylarını Al Yanıtta en fazla olay sayısı 10,000 S1, S2
Akışa Alınan Ortam Toplamlarını Al En fazla boyut sayısı 5 S1, S2
Akışa Alınan Ortam Toplamlarını Al Tüm boyutlar genelinde maksimum toplam kardinalite 150.000 S1, S2
Akışa Alınan Ortam Toplamlarını Al En fazla ölçü sayısı 20 S1, S2

Hata işleme ve çözüm

Özellik Bulunamadı davranışı

Sorguda başvurulan özellikler için, varsayılan olarak, toplamaların bir parçası veya toplamaların (ölçüler) bir parçası olarak, sorgu ortamın her genel arama özelliğini çözümlemeye çalışır. özelliği bulunursa sorgu başarılı olur. Özellik bulunamazsa sorgu başarısız olur.

Ancak, bu davranışı, özellikleri var olan ancak ortamda mevcut olan null değerler olarak kabul etmek için değiştirebilirsiniz. Bunu yapmak için isteğe bağlı istek üst bilgisinde x-ms-property-not-found-behavior değerini UseNull ayarlarsanız.

İstek üst bilgisi için olası değerler veya UseNull ThrowError (varsayılan) değerleridir. Değer olarak ayarlanmazsa, özellikler mevcut olsa bile sorgu başarılı olur ve yanıt, bulunamayacak özellikleri görüntü UseNull alan uyarılar içerir.

Çözümlenmemiş özellikleri bildirme

Hazırlık, boyut ve ölçü ifadeleri için özellik başvuruları belirtabilirsiniz. Belirli bir ad ve türe sahip bir özellik, belirtilen arama aralığı için mevcut yoksa, genel bir zaman aralığı içinde bir özelliği çözümlemeye yönelik bir deneme yapılır.

Çözümün başarı durumuna bağlı olarak aşağıdaki uyarı veya hata yayma olabilir:

  • Bir özellik genel bir zaman aralığı içinde ortamda mevcutsa uygun şekilde çözümlenir ve bu özelliğin değerinin belirli bir arama aralığı için olduğunu bildiren bir null uyarı verilir.
  • Ortamda bir özellik yoksa bir hata verilir ve sorgu yürütme başarısız olur.

Hata yanıtları

Sorgu yürütme başarısız olursa, JSON yanıt yükü aşağıdaki yapıya sahip bir hata yanıtı içerir:

{
  "error" : {
    "code" : "...",
    "message" : "...",
    "innerError" : {  
      "code" : "...",
      "message" : "...",
    }
  }
}

Burada innerError isteğe bağlıdır. Hatalı biçimlendirilmiş istek gibi temel hatalara ek olarak aşağıdaki hatalar döndürülür:

HTTP durum kodu Hata kodu Hata iletisi örneği Olası iç hata kodları
400 InvalidApiVersion "API sürümü '2016' desteklenmiyor. Desteklenen sürümler :'2016-12-12'."
400 InvalidInput "Önkate dize ayrıştırılamadı." PredicateStringParseError
400 InvalidInput "Önkate dize çevrilemiyor." InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound
400 InvalidInput "Birden çok toplama desteklenmiyor."
400 InvalidInput "Predicate özelliği bulunamadı." PropertyNotFound
400 InvalidInput "Ölçü özelliği bulunamadı." PropertyNotFound
400 InvalidInput "Boyut özelliği bulunamadı." PropertyNotFound
400 InvalidInput "Ölçü sayısı sınırı aştı." NumberOfMeasuresExceededLimit
400 InvalidInput "Toplam derinlik sınırı aşıldı." AggregateDepthExceededLimit
400 InvalidInput "Toplam kardinalite sınırı aşıldı." TotalCardinalityExceededLimit
400 InvalidInput "'from' özelliği eksik." BreaksPropertyMissing
400 InvalidInput "'to' özelliği eksik." BreaksPropertyMissing
400 InvalidInput "İstek boyutu sınırı aştı." RequestSizeExceededLimit
400 InvalidInput "Yanıt boyutu sınırı aşıldı." ResponseSizeExceededLimit
400 Invalidınput "Olay sayısı sınırı aşıldı." EventCountExceededLimit
400 Invalidınput "Özellik başvuru sayısı sınırı aşıldı." PropertyReferenceCountExceededLimit
400 Invalidmethod "' Toplamalar ' yolunda yalnızca WebSocket isteklerine izin verilir."
400 Invalidurl "'/A/b ' istek URL 'SI ayrıştırılamadı."
408 RequestTimeout "' 30 ' saniye sonra istek zaman aşımına uğradı."
503 TooManyRequests "' 95880732-01b9-44EA-8D2D-4d764dfe1904 ' ortamı için eşzamanlı istek sayısı ' 10 ' aşıldı." EnvRequestLimitExceeded

Uyarılar

Bir sorgu API 'SI yanıtı "warnings" , http yanıtı veya WebSocket yanıt iletisi kökünün altında giriş olarak bir uyarı listesi içerebilir. Belirli bir arama alanı için özellik bulunmazsa ancak genel zaman aralığı için bir ortamda bulunursa, şu anda uyarılar oluşturulur. Ayrıca, üst bilgi x-ms-property-not-found-behavior ayarlandığında UseNull ve başvurulan bir özellik genel arama aralığında bile mevcut olmadığında da oluşturulur.

Her bir uyarı nesnesi aşağıdaki alanları içerebilir:

Alan adı Alan türü Notlar
kodudur Dize Önceden tanımlanmış uyarı kodlarından biri
message Dize Ayrıntılı bir uyarı iletisi
hedef Dize JSON girişi yük girişi için noktayla ayrılmış bir JSON yolu uyarıya neden olur
Uyarı ayrıntıları Sözlük Seçim ek uyarı ayrıntıları (örneğin, koşul dizesindeki konum)

Aşağıdaki kod, koşul için uyarı örnekleri, koşul dizesi koşul, boyut ve ölçü örnekleri sunar:

"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"
  }
]

Ayrıca bkz.

uygulama kaydı ve Azure Active Directory programlama modeli hakkında daha fazla bilgi için bkz. Azure Active Directory for developers.

İstek ve kimlik doğrulama parametreleri hakkında bilgi edinmek için bkz. kimlik doğrulama ve yetkilendirme.

HTTP isteklerinin ve yanıtlarının test edilmesine yardımcı olan araçlar şunlardır:

  • Fiddler. Bu ücretsiz Web hata ayıklama proxy 'si REST isteklerinizi ele geçirebilir, böylece HTTP isteği ve yanıt iletilerini tanılayabilirsiniz.
  • JWT.io. Bu aracı kullanarak, taşıyıcı belirteçinizdeki taleplerin hızla dökümünü yapabilir ve sonra içeriklerini doğrulayabilirsiniz.
  • Postman. Bu, REST API 'Leri hata ayıklama için ücretsiz bir HTTP isteği ve yanıt sınama aracıdır.

Gen1 belgeleriniinceleyerek Azure Time Series Insights Gen1 hakkında daha fazla bilgi edinin.