Azure Time Series Insights 1. Nesil Sorgu API'si
Dikkat
Bu bir Gen1 makalesi.
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.
Önemli
- Azure Time Series Insights 1. Nesil, Get Environments, Get Environment Availability, Get Metadata, Get Environment Events ve Get Environment Aggregates API'leri için HTTPS Protokollerini kullanır.
- Azure Time Series Insights 1. Nesil, Akışa Alınan Ortam Olaylarını Alma ve Toplu Akışa Alınan API'ler için WebSocket Secure (WSS) Protokollerini kullanı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.
İpucu
Ortam Kullanılabilirliğini Alma API'sini kullanarak ön uç kullanıcı arabirimi deneyimini başlatabilirsiniz.
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-12Giriş 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ş
propertiesolduğ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.
Not
Demet sınırları 10ⁿ, 2×10ⁿ veya 5×10ⁿ değerlerini destekleyip 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)
- 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,
0sayı değeri ve diğer ölçü türleri için bir değer içeren tek birnullkayıtnulliç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.
Not
Demet sınırları 10ⁿ, 2×10ⁿ veya 5×10ⁿ değerlerini destekleyip 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)
- 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,
0sayı değeri ve diğer ölçü türleri için bir değer içeren tek birnullkayıtnulliç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 SKU'lar | Notlar |
|---|---|---|---|---|
| Tümü | En büyük istek boyutu | 32 KB | S1, S2 | |
| Ortam Kullanılabilirliğini Alma, Ortam Meta Verilerini Alma, Ortam Olaylarını Alma, Ortam Toplamlarını Akışa Alma | Ortam başına en fazla eşzamanlı istek sayısı | 10 | S1, S2 | |
| Ortam Olaylarını Alma, Ortam Toplamlarını Akışa Alma | Maksimum yanıt boyutu | 16MB | S1, S2 | |
| Ortam Olaylarını Alma, Ortam Toplamlarını Akışa Alma | Koşul dizesi ifadeleri de dahil olmak üzere koşuldaki en fazla benzersiz özellik başvurusu sayısı | 50 | S1, S2 | |
| Ortam Olaylarını Alma, Ortam Toplamlarını Akışa Alma | Koşul dizesinde özellik başvurusu olmayan en fazla tam metin arama terimleri | 2 | S1, S2 | Örnek: HAS 'abc', 'abc' |
| Ortam Olaylarını Alma | Yanıt olarak en fazla olay sayısı | 10,000 | S1, S2 | |
| Ortam Toplamlarını Akışa Alma | Boyut sayısı üst | 5 | S1, S2 | |
| Ortam Toplamlarını Akışa Alma | Tüm boyutlar genelinde maksimum toplam kardinalite | 150.000 | S1, S2 | |
| Ortam Toplamlarını Akışa Alma | En fazla ölçü sayısı | 20 | S1, S2 |
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
nullbildiren 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:
| HTTP durum kodu | Hata kodu | Hata iletisi örneği | Olası iç hata kodları |
|---|---|---|---|
| 400 | InvalidApiVersion | "'2016' API sürümü desteklenmiyor. Desteklenen sürümler :'2016-12-12'." | |
| 400 | InvalidInput | "Koşul dizesi ayrıştırılamıyor." | PredicateStringParseError |
| 400 | InvalidInput | "Koşul dizesi çevrilemedi." | InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Birden çok toplama desteklenmiyor." | |
| 400 | InvalidInput | "Koşul özelliği bulunamadı." | PropertyNotFound |
| 400 | InvalidInput | "Measure özelliği bulunamadı." | PropertyNotFound |
| 400 | InvalidInput | "Boyut özelliği bulunamadı." | PropertyNotFound |
| 400 | InvalidInput | "Ölçü sayısı sınırı aştı." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Toplama derinliği sınırı aştı." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Toplam kardinalite sınırı aştı." | 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ştı." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Olay sayısı sınırı aştı." | EventCountExceededLimit |
| 400 | InvalidInput | "Özellik başvuru sayısı sınırı aştı." | PropertyReferenceCountExceededLimit |
| 400 | GeçersizMethod | "'Toplamalar' yolunda yalnızca WebSocket isteklerine izin verilir." | |
| 400 | InvalidUrl | "'/a/b' istek URL'si ayrıştırılamadı." | |
| 408 | RequestTimeout | "İstek '30' saniye sonra zaman aşımına uğradı." | |
| 503 | TooManyRequests | "'95880732-01b9-44ea-8d2d-4d764dfe1904' ortamı için '10' eşzamanlı istek sayısı aşıldı." | EnvRequestLimitExceeded |
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:
| Alan adı | Alan türü | Notlar |
|---|---|---|
| kod | Dize | Önceden tanımlanmış uyarı kodlarından biri |
| ileti | Dize | Ayrıntılı bir uyarı iletisi |
| Hedef | Dize | Uyarıya neden olan JSON giriş yükü girişinin noktayla ayrılmış JSON yolu |
| warningDetails | Sözlük | Isteğe bağlı; ek uyarı ayrıntıları (örneğin, koşul dizesindeki konum) |
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.