Azure Time Series Insights 1. Nesil Sorgu API'si

Bu makalede çeşitli REST Sorgu API'leri açıklanmaktadır. REST API'leri, Azure Time Series Insights 1. Nesil ortamlarını sorgulamanızı sağlayan HTTP işlemleri kümelerini (yöntemler) destekleyen hizmet uç noktalarıdır.

Ortamlar API'si alma

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'si alma

Get Environment Availability API,olay sayısının olay zaman damgası $ts üzerinden dağılımını döndürür. Ortam kullanılabilirliği önbelleğe alınır ve yanıt süresi ortamdaki olayların sayısına bağlı değildir.

• 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
    }
  }
  

  Olay içermeyen ortamlar için boş bir nesne döndürülür.

Ortam Meta Veri API'si alma

Get Environment Metadata API, 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 Insights 1. Nesil, meta verileri dahili olarak önbelleğe alır ve yaklaşık olarak önbelleğe alır ve arama aralığındaki tam olaylarda bulunan daha fazla özellik döndürebilir.

• 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 boş properties olduğunda veya bir arama aralığında olay olmadığında boş bir dizi döndürülür.

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

Ortam Olayları API'lerini alma

Ortam Olaylarını Al API'si, arama aralığı ve koşuluyla eşleşen 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)
  • Koşul 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 özelliğe göre sıralama) şu anda desteklenmiyor.
  • Olaylar sıralanabilir ve üst kısımla sınırlanabilir.
  • Sıralama tüm özellik türlerinde desteklenir. Sıralama, Boole ifadeleri için tanımlanan karşılaştırma işleçlerine dayanı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ı Akışı API'si alma

Get Environment Events Streamed API'si, arama aralığı ve koşuluyla eşleşen ham olayların listesini döndürür.

Bu API, akış yapmak ve kısmi sonuçlar döndürmek için WebSocket Güvenli Protokolünü kullanır. Her zaman ek olaylar döndürür. Başka bir ifadeyle, yeni ileti bir öncekine eklenir. Yeni ileti, önceki iletide bulunmayan yeni olaylar içeriyor. Yeni ileti eklendiğinde ö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)
  • Koşul 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 özelliğe göre sıralama) şu anda desteklenmiyor.
  • Olaylar sıralanabilir ve üst kısımla sınırlanabilir.
  • Sıralama tüm özellik türlerinde desteklenir. Sıralama, Boole ifadeleri için tanımlanan karşılaştırma işleçlerine dayanı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'lerini alma

Get Environment Aggregates API'leri, isteğe bağlı olarak diğer özelliklerin değerlerini ölçerken olayları belirtilen özelliğe göre gruplandırmaktadır.

• Uç nokta ve işlem:

  POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>
  

• Giriş yükü yapısı:

  • Search span yan tümcesi (zorunlu)
  • Koşul yan tümcesi (isteğe bağlı)
  • Aggregates 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 > 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ğeri, 0 sayı değeri ve diğer ölçü türleri için bir değer içeren tek bir null kayıt null içerir.

Akışa Alınan Ortam Toplamları API'lerini alma

Get Environment Aggregates Streamed API,isteğe bağlı olarak diğer özelliklerin değerlerini ölçerken olayları belirtilen özelliğe göre gruplandırıyor:

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

• Uç nokta ve işlem:

  GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>
  

• Giriş yükü yapısı:

  • Search span yan tümcesi (zorunlu)
  • Koşul yan tümcesi (isteğe bağlı)
  • Aggregates yan 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ğeri, 0 sayı değeri ve diğer ölçü türleri için bir değer içeren tek bir null kayıt 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:

Hata işleme ve çözümleme

Özellik Bulunamadı davranışı

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

Ancak bu davranışı, özellikleri var olan ancak ortamda mevcut olmayan değerlerle null değerlendirecek şekilde değiştirebilirsiniz. Bunu yapmak için isteğe bağlı istek üst bilgisini x-ms-property-not-found-behavior değeriyle UseNullayarlarsınız.

İstek üst bilgisi için olası değerler veya ThrowError 'dır UseNull (varsayılan). Değer olarak ayarladığınızda UseNull , özellikler mevcut olmasa bile sorgu başarılı olur ve yanıt, bulunamaz özellikleri görüntüleyen uyarılar içerir.

Çözümlenmemiş özellikleri bildirme

Koşul, boyut ve ölçü ifadeleri için özellik başvuruları belirtebilirsiniz. Belirli bir ad ve türe sahip bir özellik belirtilen bir arama aralığı için mevcut değilse, genel bir zaman aralığı boyunca bir özelliği çözümlemeye çalışılır.

Çözümlemenin başarısına bağlı olarak aşağıdaki uyarı veya hata yayılabilir:

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

Hata yanıtları

Sorgu yürütmesi 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 isteğe innerError bağlıdır. Hatalı biçimlendirilmiş istek gibi temel hatalara ek olarak aşağıdaki hatalar döndürülür:

Uyarılar

Sorgu API'sinin yanıtı, HTTP yanıtının veya WebSocket yanıt iletisinin kökü altında girdi olarak "warnings" uyarıların listesini içerebilir. Şu anda belirli bir arama aralığı için özellik bulunamazsa ancak genel zaman aralığı için bir ortamda bulunursa uyarılar oluşturulur. Ayrıca üst bilgi x-ms-property-not-found-behavior olarak ayarlandığında UseNull ve başvuruda bulunan bir özellik genel arama yayılma alanında bile mevcut olmadığında oluşturulur.

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

Aşağıdaki kod koşul, koşul dizesini koşul, boyut ve ölçüye yönelik uyarı örneklerini 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. Geliştiriciler için Azure Active Directory.

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

HTTP isteklerini ve yanıtlarını test etme konusunda yardımcı olan araçlar şunlardır:

• Fiddler. Bu ücretsiz web hata ayıklama proxy'si REST isteklerinizi kesebilir, böylece HTTP isteğini ve yanıt iletilerini tanılayabilirsiniz.
• JWT.io. Bu aracı kullanarak talepleri taşıyıcı belirtecinize hızla atabilir ve ardından içeriklerini doğrulayabilirsiniz.
• Postacı. Bu, REST API'lerinin hatalarını ayıklamaya yönelik ücretsiz bir HTTP isteği ve yanıt testi aracıdır.

1. Nesil belgelerini gözden geçirerek Azure Time Series Insights 1. Nesil hakkında daha fazla bilgi edinin.