Aracılığıyla paylaş

Cihazları sorgulamak için IoT Central REST API kullanma

  • Makale

IoT Central REST API,IoT Central uygulamalarıyla tümleşen istemci uygulamaları geliştirmenizi sağlar. IoT Central uygulamanızdaki cihazları sorgulamak için REST API'yi kullanabilirsiniz. Sorgu REST API'sini nasıl kullanabileceğinize ilişkin örnekler aşağıda verilmiştir:

  • Cihaz tarafından bildirilen son 10 telemetri değerini alın.
  • Hata durumunda olan ve eski üretici yazılımına sahip tüm cihazları bulun.
  • 10 dakikalık pencerelerde ortalaması alınan cihazlardan telemetri eğilimleri.
  • Tüm termostat cihazlarınızın geçerli üretici yazılımı sürümünü alın.

Bu makalede, cihazları sorgulamak için API'nin /query nasıl kullanılacağı açıklanmaktadır.

Bir cihaz, desteklediği özellikleri, telemetriyi ve komutları bileşenler ve modüller halinde gruplandırabilir.

Her IoT Central REST API çağrısı bir yetkilendirme üst bilgisi gerektirir. Daha fazla bilgi edinmek için bkz . IoT Central REST API çağrılarının kimliğini doğrulama ve yetkilendirme.

IoT Central REST API'sinin başvuru belgeleri için bkz . Azure IoT Central REST API başvurusu.

İpucu

Postman'i kullanarak bu makalede açıklanan REST API çağrılarını deneyebilirsiniz. IoT Central Postman koleksiyonunu indirin ve Postman'a aktarın. Koleksiyonda, uygulamanızın alt etki alanı ve yönetici belirteci gibi değişkenleri ayarlamanız gerekir.

IoT Central kullanıcı arabirimini kullanarak cihazları sorgulamayı öğrenmek için bkz . Cihaz verilerini analiz etmek için veri gezginini kullanma.

Sorgu çalıştırma

Sorgu çalıştırmak için aşağıdaki isteği kullanın:

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

Sorgu istek gövdesindedir ve aşağıdaki örneğe benzer:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

dtmi:eclipsethreadx:devkit:hlby5jgib2o yan tümcesindeki FROM değer bir cihaz şablonu kimliğidir. Cihaz şablonu kimliğini bulmak için IoT Central uygulamanızdaki Cihazlar sayfasına gidin ve şablonu kullanan bir cihazın üzerine gelin. Kart, cihaz şablonu kimliğini içerir:

Sayfa URL'sinde cihaz şablonu kimliğinin nasıl bulunduğunu gösteren ekran görüntüsü.

Yanıt, aynı cihaz şablonunu paylaşan birden çok cihazdan telemetriyi içerir. Bu isteğin yanıtı aşağıdaki örneğe benzer:

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

Sözdizimi

Sorgu söz dizimi SQL söz dizimine benzer ve aşağıdaki yan tümcelerden oluşur:

  • SELECT gereklidir ve cihaz telemetri değerleri gibi almak istediğiniz verileri tanımlar.
  • FROM gereklidir ve sorguladığınız cihaz türünü tanımlar. Bu yan tümcesi cihaz şablonu kimliğini belirtir.
  • WHERE isteğe bağlıdır ve sonuçları filtrelemenize olanak tanır.
  • ORDER BY isteğe bağlıdır ve sonuçları sıralamanıza olanak tanır.
  • GROUP BY isteğe bağlıdır ve sonuçları toplamanıza olanak tanır.

Aşağıdaki bölümlerde bu yan tümceler daha ayrıntılı olarak açıklanmaktadır.

SELECT yan tümcesi

SELECT yan tümcesi, sorgu çıkışına eklenecek veri değerlerini listeler ve aşağıdaki öğeleri içerebilir:

  • Telemetri. Cihaz şablonundaki telemetri adlarını kullanın.
  • $id. Cihaz kimliği.
  • $provisioned. Cihazın henüz sağlanmış olup olmadığını gösteren boole değeri.
  • $simulated. Cihazın simülasyon cihazı olup olmadığını gösteren boole değeri.
  • $ts. Telemetri değeriyle ilişkili zaman damgası.

Cihaz şablonunuz bileşenler kullanıyorsa, bileşende tanımlanan telemetriye aşağıdaki gibi başvurursunuz:

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Bileşen adını cihaz şablonunda bulabilirsiniz:

Bileşen adının nasıl bulunduğunu gösteren ekran görüntüsü.

Yan tümcesinde SELECT aşağıdaki sınırlar geçerlidir:

  • Joker karakter işleci yok.
  • Seçme listesinde 15'ten fazla öğe olamaz.
  • Sorgu en fazla 10.000 kayıt döndürür.

Diğer adlar

yan tümcesindeki AS bir öğenin diğer adını tanımlamak için anahtar sözcüğünü SELECT kullanın. Diğer ad sorgu çıkışında kullanılır. Sorgunun başka bir yerinde de kullanabilirsiniz. Örneğin:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

İpucu

Seçme listesindeki başka bir öğeyi diğer ad olarak kullanamazsınız. Örneğin, aşağıdakilere izin verilmez SELECT id, temp AS id....

Sonuç aşağıdaki çıkış gibi görünür:

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

TOP

Sorgunun döndürdüğü sonuç sayısını sınırlamak için öğesini TOP kullanın. Örneğin, aşağıdaki sorgu ilk 10 sonucu döndürür:

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

kullanmıyorsanız TOP, sorgu en fazla 10.000 sonuç döndürür.

Sonuçları, sonuç sayısını sınırlamadan önce TOP sıralamak için ORDER BY kullanın.

FROM yan tümcesi

FROM Yan tümcesi bir cihaz şablonu kimliği içermelidir. FROM yan tümcesi, sorguladığınız cihazın türünü belirtir.

Cihaz şablonu kimliğini bulmak için IoT Central uygulamanızdaki Cihazlar sayfasına gidin ve şablonu kullanan bir cihazın üzerine gelin. Kart, cihaz şablonu kimliğini içerir:

Cihaz şablonu kimliğinin cihazlar sayfasında nasıl bulunduğunu gösteren ekran görüntüsü.

Bir cihazın cihaz şablonu kimliğini almak için Cihazlar - REST API alma çağrısını da kullanabilirsiniz.

WHERE yan tümcesi

WHERE yan tümcesi, sonuçları filtrelemek için değerleri ve zaman pencerelerini kullanmanıza olanak tanır:

Zaman aralıkları

Uygulamanız tarafından belirli bir zaman penceresinde alınan telemetriyi almak için yan tümcesinin WHERE bir parçası olarak kullanınWITHIN_WINDOW. Örneğin, son güne ait sıcaklık ve nem telemetrisini almak için aşağıdaki sorguyu kullanın:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Zaman penceresi değeri ISO 8601 süre biçimini kullanır. Aşağıdaki tabloda bazı örnekler verilmiştir:

Örnek Açıklama
PT10M Son 10 dakika
P1D Geçen gün
P2DT12H Son 2 gün 12 saat
P1W Geçen hafta
PT5H Son beş saat
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z' Belirli bir zaman aralığı

Değer karşılaştırmaları

Belirli değerlere göre telemetri alabilirsiniz. Örneğin, aşağıdaki sorgu sıcaklığın sıfırdan büyük olduğu, basıncın 50'den büyük olduğu ve cihaz kimliğinin sample-002 ve sample-003'ten biri olduğu tüm iletileri döndürür:

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

Aşağıdaki işleçler desteklenir:

  • Mantıksal işleçler AND ve OR.
  • Karşılaştırma işleçleri =, !=, >, <, >=, <=, <>ve IN.

Not

işleci IN yalnızca telemetri ve $idile çalışır.

Yan tümcesinde WHERE aşağıdaki sınırlar geçerlidir:

  • Tek bir sorguda en fazla 10 işleç kullanabilirsiniz.
  • Sorguda WHERE yan tümcesi yalnızca telemetri ve cihaz meta veri filtrelerini içerebilir.
  • Sorguda en fazla 10.000 kayıt alabilirsiniz.

Toplamalar ve GROUP BY yan tümcesi

Toplama işlevleri, bir zaman aralığı içinde telemetri verilerinde ortalama, maksimum ve minimum gibi değerleri hesaplamanıza olanak sağlar. Örneğin, aşağıdaki sorgu 10 dakikalık pencerelerde cihazdan sample-001 ortalama sıcaklığı ve nemi hesaplar:

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

Sonuçlar aşağıdaki çıkışa benzer:

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

Aşağıdaki toplama işlevleri desteklenir: SUM, MAX, MIN, COUNT, , AVG, FIRSTve LAST.

Pencere boyutunu belirtmek için kullanın GROUP BY WINDOW . kullanmıyorsanız GROUP BY WINDOW, sorgu telemetriyi son 30 gün içinde toplar.

Not

Yalnızca telemetri değerlerini toplayabilirsiniz.

ORDER BY yan tümcesi

ORDER BY yan tümcesi, sorgu sonuçlarını telemetri değerine, zaman damgasına veya cihaz kimliğine göre sıralamanıza olanak tanır. Artan veya azalan düzende sıralayabilirsiniz. Örneğin, aşağıdaki sorgu önce en son sonuçları döndürür:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

İpucu

Sorgunun sıralamadan sonra döndürdüğü sonuç sayısını sınırlamak için ile birleştirin ORDER BYTOP .

Sınırlar

Sorgular için geçerli sınırlar şunlardır:

  • Yan tümce listesinde en fazla 15 öğe SELECT vardır.
  • Yan tümcesinde 10'dan WHERE fazla mantıksal işlem yoktur.
  • Sorgu dizesinin uzunluk üst sınırı 350 karakterdir.
  • Yan tümce listesinde joker karakteri (*) SELECT kullanamazsınız.
  • Sorgular en fazla 10.000 kayıt alabilir.

Sonraki adımlar

Rest API ile cihazları sorgulamayı öğrendiğinize göre, önerilen bir sonraki adım IoT Central REST API'sini kullanarak kullanıcıları ve rolleri yönetmeyi öğrenmektir.