IoT Hub'da modül ikizlerini anlama ve kullanma

IoT Hub'da, her cihaz kimliğinin altında en fazla 50 modül kimliği oluşturabilirsiniz. Her modül kimliği örtük olarak bir modül ikizi oluşturur. Cihaz ikizlerine benzer şekilde, modül ikizleri de meta veriler, yapılandırmalar ve koşullar gibi modül durumu bilgilerini depolayan JSON belgeleridir. Azure IoT Hub, IoT Hub'a bağladığınız her modül için bir modül ikizi tutar.

Bu makale, önce IoT Hub'da cihaz ikizlerini anlama ve kullanma makalesini okuduğunuzu varsayar.

Cihaz tarafında IoT Hub cihaz yazılım geliştirme setleri (SDK) her birinin IoT Hub'a bağımsız bir bağlantı açtığı modüller oluşturmanıza olanak tanır. Bu işlevsellik, cihazınızdaki farklı bileşenler için ayrı ad alanları kullanmanıza olanak tanır. Örneğin, üç farklı algılayıcısı olan bir otomat var. Şirketinizdeki farklı departmanlar her algılayıcıyı denetler. Bir departmanın yalnızca denetledikleri algılayıcıya iş veya doğrudan yöntemler gönderebilmesi ve çakışmaları ve kullanıcı hatalarını önlemesi için her algılayıcı için bir modül oluşturabilirsiniz.

Modül kimliği ve modül ikizi, cihaz kimliği ve cihaz ikizi ile aynı özellikleri sağlar ancak daha ayrıntılıdır. Bu daha ayrıntılı ayrıntı düzeyi, işletim sistemi tabanlı cihazlar veya birden çok bileşeni yöneten üretici yazılımı cihazları gibi yetenekli cihazların bu bileşenlerin her biri için yapılandırmayı ve koşulları yalıtmalarını sağlar. Modül kimliği ve modül ikizleri, modüler yazılım bileşenlerine sahip IoT cihazlarıyla çalışırken karşılaşılan endişelerin yönetim ayrımını sağlar. Modül ikizinin genel kullanıma sunulmasıyla, modül ikizi düzeyinde tüm cihaz ikizi işlevselliğini desteklemeyi hedefliyoruz.

Not

Bu makalede açıklanan özellikler yalnızca IoT Hub'ın standart katmanında kullanılabilir. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. çözüm için doğru IoT Hub katmanını ve boyutunu seçme.

Bu makalede şunlar açıklanmaktadır:

• Modül ikizinin yapısı: etiketler, istenen ve bildirilen özellikler.
• Cihaz uygulamalarının ve çözüm arka ucunun modül ikizlerinde gerçekleştirebileceği işlemler.

Bildirilen özellikleri, cihazdan buluta iletileri veya dosya yüklemeyi kullanma yönergeleri için Cihazdan buluta iletişim kılavuzuna bakın.

İstenen özellikleri, doğrudan yöntemleri veya buluttan cihaza iletileri kullanma yönergeleri için Buluttan cihaza iletişim kılavuzuna bakın.

Modül ikizleri

Modül ikizleri, aşağıdaki modülle ilgili bilgileri depolar:

• Cihazdaki ve IoT Hub'lardaki modüller, modül koşullarını ve yapılandırmasını eşitlemek için kullanabilir.

• Çözüm arka ucu, uzun süre çalışan işlemleri sorgulamak ve hedeflemek için kullanılabilir.

Modül ikizinin yaşam döngüsü ilgili modül kimliğine bağlıdır. IoT Hub'da modül kimliği oluşturulduğunda veya silindiğinde modül çiftleri otomatik olarak oluşturulur ve silinir.

Modül ikizi, şunları içeren bir JSON belgesidir:

• Etiketler' e tıklayın. JSON belgesinin arka uç uygulamalarının okuyabileceği ve yazabileceği bir bölüm. Etiketler cihazdaki modüllerde görünmez. Etiketler sorgulama amacıyla ayarlanır.

• İstenen özellikler. Modül yapılandırmasını veya koşullarını eşitlemek için bildirilen özelliklerle birlikte kullanılır. Arka uç uygulamaları istenen özellikleri ayarlayabilir ve modül uygulaması bunları okuyabilir. Modül uygulaması, istenen özelliklerdeki değişikliklerin bildirimlerini de alabilir.

• Bildirilen özellikler. Modül yapılandırmasını veya koşullarını eşitlemek için istenen özelliklerle birlikte kullanılır. Modül uygulaması bildirilen özellikleri ayarlayabilir ve arka uç uygulamaları bunları okuyabilir ve sorgulayabilir.

• Modül kimliği özellikleri. Modül ikizi JSON belgesinin kökü, kimlik kayıt defterinde depolanan ilgili modül kimliğinden salt okunur özellikleri içerir.

Aşağıdaki örnekte bir modül ikizi JSON belgesi gösterilmektedir:

{
    "deviceId": "devA",
    "moduleId": "moduleA",
    "etag": "AAAAAAAAAAc=", 
    "status": "enabled",
    "statusReason": "provisioned",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "connected",
    "lastActivityTime": "2015-02-30T16:24:48.789Z",
    "cloudToDeviceMessageCount": 0, 
    "authenticationType": "sas",
    "x509Thumbprint": {     
        "primaryThumbprint": null, 
        "secondaryThumbprint": null 
    }, 
    "version": 2, 
    "tags": {
        "deploymentLocation": {
            "building": "43",
            "floor": "1"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata" : {...},
            "$version": 1
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": 55,
            "$metadata" : {...},
            "$version": 4
        }
    }
}

En üst düzeyde, modül ikizi nesnesi, modül kimliği özelliklerini ve tags, reported ve desired özellikleri için kapsayıcı nesneleri içerir. Kapsayıcı, properties Modül ikizi meta verileri ve $metadataİyimser eşzamanlılık$versionbazı salt okunur öğeleri ( ve ) içerir.

Bildirilen özellik örneği

Önceki örnekte modül ikizi bildirilen bir batteryLevel özelliği içeriyor. Bu özellik, bildirilen son pil düzeyine göre modülleri sorgulamayı ve çalıştırmayı mümkün kılar. Diğer örnekler arasında modül uygulaması raporlama modülü özellikleri veya bağlantı seçenekleri yer alır.

Not

Bildirilen özellikler, bir özelliğin bilinen son değeriyle ilgilendiğiniz senaryoları basitleştirir. Modül telemetrisini zaman serisi gibi zaman damgalı olaylar dizilerinde işlemek istiyorsanız cihazdan buluta iletileri kullanın.

İstenen özellik örneği

Önceki örnekte, arka uç uygulamaları ve modül uygulaması tarafından bu modül için telemetri yapılandırmasını eşitlemek amacıyla telemetryConfig modül ikizinin istenen ve bildirilen özellikleri kullanılır. Örneğin:

1. Arka uç uygulaması istenen özelliği istenen yapılandırma değeriyle ayarlar. Belgenin istenen özellik kümesine sahip bölümü aşağıdadır:

   ...
   "desired": {
       "telemetryConfig": {
           "sendFrequency": "5m"
       },
       ...
   },
   ...
   

2. Modül bağlıysa modül uygulamasına değişiklik anında bildirilir. Bağlı değilse, modül uygulaması bağlandığında modül yeniden bağlantı akışını izler. Modül uygulaması daha sonra güncellenmiş yapılandırmayı (veya status özelliği kullanılarak bir hata durumunu) bildirir. Bildirilen özelliklerin bölümü aşağıdadır:

   "reported": {
       "telemetryConfig": {
           "sendFrequency": "5m",
           "status": "success"
       }
       ...
   }
   

3. Arka uç uygulaması, modül ikizlerini sorgulayarak yapılandırma işleminin sonuçlarını birçok modülde izleyebilir.

Not

Yukarıdaki kod parçacıkları, bir modül yapılandırmasını ve durumunu kodlamanın bir yolu olan okunabilirlik için iyileştirilmiş örneklerdir. IoT Hub, modül ikizlerinde istenen ve bildirilen özellikler için belirli bir şema uygulamaz.

Önemli

IoT Tak Çalıştır, değişiklikleri istenen ve bildirilen özelliklerle eşitlemek için birkaç ek özellik kullanan bir şema tanımlar. Çözümünüz IoT Tak Çalıştır kullanıyorsa, ikiz özelliklerini güncelleştirirken Tak ve Kullan kurallarını izlemeniz gerekir. Daha fazla bilgi ve bir örnek için, IoT Tak Çalıştır'da yazılabilir özellikler bölümüne bkz.

Arka uç işlemleri

Arka plan uygulamaları, HTTPS üzerinden erişilebilen aşağıdaki atomik işlemleri kullanarak ikiz modül üzerinde çalışır.

• Modül ikizini kimlik ile alın. Bu işlem, etiketler ve istenen ve bildirilen sistem özellikleri de dahil olmak üzere modül ikizi belgesini döndürür.

• Modül ikizini kısmen güncelle. Bu işlem bir modül ikizindeki etiketleri veya istenen özellikleri kısmen güncelleştirir. Kısmi güncelleştirme, herhangi bir özelliği ekleyen veya güncelleştiren bir JSON belgesi olarak ifade edilir. olarak ayarlanan null özellikler kaldırılır. Aşağıdaki örnek, değeri {"newProperty": "newValue"} olan yeni bir istenen özellik oluşturur, mevcut değeri existingProperty'i "otherNewValue" ile değiştirir ve otherOldProperty öğesini kaldırır. Mevcut istenen özelliklerde veya etiketlerde başka değişiklik yapılmaz:

  {
      "properties": {
          "desired": {
              "newProperty": {
                  "nestedProperty": "newValue"
              },
              "existingProperty": "otherNewValue",
              "otherOldProperty": null
          }
      }
  }
  

• İstenen özellikleri değiştirin. Bu işlem, mevcut tüm istenen özelliklerin tamamen üzerine yazar ve yerine properties/desired için yeni bir JSON belgesi geçer.

• Etiketleri değiştirin. Bu işlem, tüm mevcut etiketlerin üzerine yazarak tags için yeni bir JSON belgesi ile değiştirir.

• Çift bildirimler alın. Bu işlem, ikiz değiştirildiğinde bunu bildirir. Modül ikizi değişiklik bildirimlerini almak için IoT çözümünüzün bir yol oluşturması ve Veri Kaynağı'nı twinChangeEvents'e eşit olarak ayarlaması gerekir. Varsayılan olarak, böyle bir yol yoktur, bu nedenle ikiz bildirimleri gönderilmez. Değişiklik oranı çok yüksekse veya iç hatalar gibi diğer nedenlerle IoT Hub tüm değişiklikleri içeren tek bir bildirim gönderebilir. Bu nedenle, uygulamanızın tüm ara durumların güvenilir bir şekilde denetlenmesi ve günlüğe kaydedilmesi gerekiyorsa cihazdan buluta iletileri kullanmanız gerekir. İkili bildirim mesajında döndürülen özellikler ve gövde hakkında daha fazla bilgi edinmek için Telemetri dışı olay şemaları bölümüne bakın.

Yukarıdaki tüm işlemler İyimser eşzamanlılığı destekler ve IoT Hub'a Erişimi Denetleme makalesinde açıklandığı gibi ServiceConnect izni gerektirir.

Bu işlemlere ek olarak, arka uç uygulamaları SQL benzeri IoT Hub sorgu dilini kullanarak modül ikizlerini sorgulayabilir.

Modül işlemleri

Modül uygulaması aşağıdaki atomik işlemleri kullanarak modül ikizi üzerinde çalışır:

• Modül ikizlerini alın. Bu işlem, bağlı olan modülün modül ikizi belgesini (istenen ve bildirilen sistem özellikleri dahil) döndürür.

• Bildirilen özellikleri kısmen güncelleştirin. Bu işlem, o anda bağlı olan modülün bildirilen özelliklerinin kısmi güncelleştirmesini etkinleştirir.

• İstenen özellikleri gözlemleyin. Şu anda bağlı olan modül, gerçekleştiğinde istenen özelliklere yapılan güncelleştirmelerin bildirilmesini seçebilir.

Yukarıdaki tüm işlemler, IoT Hub'a Erişimi Denetleme makalesinde tanımlandığı gibi DeviceConnect izni gerektirir.

Azure IoT cihaz SDK'ları, birçok dil ve platformdan önceki işlemlerin kullanımını kolaylaştırır.

Etiketler ve özellikler biçimi

Etiketler, istenen özellikler ve bildirilen özellikler aşağıdaki kısıtlamalara sahip JSON nesneleridir:

• Anahtarlar: JSON nesnelerindeki tüm anahtarlar UTF-8 kodlanmış, büyük/küçük harfe duyarlı ve en fazla 1 KB uzunluğundadır. İzin verilen karakterler UNICODE denetim karakterlerini (C0 ve C1 kesimleri) ve ., $ve SP'yi dışlar.

• Değerler: JSON nesnelerindeki tüm değerler şu JSON türlerinde olabilir: boole, sayı, dize, nesne. Diziler de sistem tarafından desteklenir.

  • Tamsayılar en düşük -4503599627370496 ve en yüksek 4503599627370495 değerine sahip olabilir.

  • Dize değerleri UTF-8 ile kodlanmıştır ve uzunluk üst sınırı 4 KB olabilir.

• Derinlik: Etiketlerde, istenen özelliklerde ve bildirilen özelliklerde en fazla JSON nesnesi derinliği 10'dur. Örneğin, aşağıdaki nesne geçerlidir:

  {
       ...
       "tags": {
           "one": {
               "two": {
                   "three": {
                       "four": {
                           "five": {
                               "six": {
                                   "seven": {
                                       "eight": {
                                           "nine": {
                                               "ten": {
                                                   "property": "value"
                                               }
                                           }
                                       }
                                   }
                               }
                           }
                       }
                   }
               }
           }
       },
       ...
  }
  

Modül ikizi boyutu

IoT Hub, tags değeri için 8 KB, ve her bir properties/desired ve properties/reported değeri için 32 KB boyut sınırı uygular. Bu toplamlar, $version ve $metadata/$lastUpdated gibi salt okunur öğeler hariç tutulmaktadır.

İkiz boyutu aşağıdaki gibi hesaplanır:

• IoT Hub, her özelliğin anahtarını ve değerini toplu olarak hesaplar ve uzunluğunu ekler.

• Özellik anahtarları UTF8 ile kodlanmış dizeler olarak kabul edilir.

• Basit özellik değerleri UTF8 kodlu dizeler, sayısal değerler (8 Bayt) veya Boole değerleri (4 Bayt) olarak kabul edilir.

• UTF8 ile kodlanmış dizelerin boyutu, UNICODE denetim karakterleri (C0 ve C1 kesimleri) hariç tüm karakterler sayılarak hesaplanır.

• Karmaşık özellik değerleri (iç içe nesneler), özellik anahtarlarının ve içerdikleri özellik değerlerinin toplam boyutuna göre hesaplanır.

IoT Hub, bu belgelerin boyutunu sınırın üzerine çıkarabilecek tüm işlemler hatayla reddeder.

Modül ikizi meta verileri

IoT Hub, istenen ve bildirilen özelliklerdeki her JSON nesnesi için son güncelleştirmenin zaman damgasını tutar. Zaman damgaları UTC biçimindedir ve ISO8601YYYY-MM-DDTHH:MM:SS.mmmZ. Örneğin:

{
    ...
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata": {
                "telemetryConfig": {
                    "sendFrequency": {
                        "$lastUpdated": "2016-03-30T16:24:48.789Z"
                    },
                    "$lastUpdated": "2016-03-30T16:24:48.789Z"
                },
                "$lastUpdated": "2016-03-30T16:24:48.789Z"
            },
            "$version": 23
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": "55%",
            "$metadata": {
                "telemetryConfig": {
                    "sendFrequency": "5m",
                    "status": {
                        "$lastUpdated": "2016-03-31T16:35:48.789Z"
                    },
                    "$lastUpdated": "2016-03-31T16:35:48.789Z"
                },
                "batteryLevel": {
                    "$lastUpdated": "2016-04-01T16:35:48.789Z"
                },
                "$lastUpdated": "2016-04-01T16:24:48.789Z"
            },
            "$version": 123
        }
    }
    ...
}

Nesne anahtarlarını kaldıran güncelleştirmeleri korumak için bu bilgiler her düzeyde tutulur (yalnızca JSON yapısının yaprakları değil).

İyimser eşzamanlılık

Etiketler, istenen özellikler ve bildirilen özelliklerin tümü iyimser eşzamanlılığı destekler. İkiz özellik güncelleştirmelerinin sırasını garanti etmeniz gerekiyorsa, bir sonraki güncelleştirmeyi göndermeden önce bildirilen özellikleri geri çağırmayı bekleyerek uygulama düzeyinde eşitleme uygulamayı göz önünde bulundurun.

Modül ikizlerinin, RFC7232'ye göre, ikizin JSON gösterimini temsil eden bir ETag (etag özelliği) vardır. Tutarlılığı sağlamak için arka uç uygulamalarından koşullu güncelleştirme işlemlerinde özelliğini kullanabilirsiniz etag . Bu seçenek, tags kapsayıcıyı içeren işlemler için tutarlılığı sağlar.

Modül ikizi istenen ve bildirilen özellikler de artımlı olması garanti edilen bir $version değere sahiptir. ETag'e benzer şekilde, güncelleştirmelerin tutarlılığını zorlamak için sürüm değerini kullanabilirsiniz. Örneğin, bildirilen bir özellik için modül uygulaması veya istenen özellik için bir arka uç uygulaması.

Bir gözlem aracısının (istenen özellikleri gözlemleyen modül uygulaması gibi) alma işleminin sonucu ile güncelleştirme bildirimi arasındaki yarışları uzlaştırması gerektiğinde de sürümler yararlıdır. Modül yeniden bağlantı akışı bölümü daha fazla bilgi sağlar.

Modül yeniden bağlantı akışı

IoT Hub, bağlantısı kesilmiş modüller için istenen özellikleri güncelleştirme bildirimlerini korumaz. Bağlanmakta olan bir modülün, güncelleştirme bildirimlerine abone olmanın yanı sıra istenen özellikler belgesinin tamamını alması gerekir. Güncelleştirme bildirimleri ile tam alma arasında yarış olasılığı göz önünde bulundurulduğunda aşağıdaki akışın sağlanması gerekir:

1. Modül uygulaması bir IoT hub'ına bağlanır.
2. Modül uygulaması istenen özellikler güncelleştirme bildirimlerine abonedir.
3. Modül uygulaması istenen özellikler için belgenin tamamını alır.

Modül uygulaması, tam alınan belgenin sürümüyle eşit veya daha az olan $version tüm bildirimleri yoksayabilir. IoT Hub sürümlerin her zaman arttığını garanti ettiğinden bu yaklaşım mümkündür.

Sonraki adımlar

Bu makalede açıklanan kavramlardan bazılarını denemek için aşağıdaki IoT Hub öğreticilerine bakın:

• .NET arka ucu ve .NET cihazı kullanarak IoT Hub modül kimliği ve modül ikizi ile çalışmaya başlayın