IoT Hub cihaz ikizlerini anlama ve kullanma

Cihaz TWINS , meta veriler, konfigürasyonlar ve koşullar dahil olmak üzere cihaz durum BILGILERINI depolayan JSON belgelerdir. Azure IoT Hub, IoT Hub'a bağladığınız her cihaz için bir cihaz çifti tutar.

Not

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

Bu makalede şunları açıklanmaktadır:

  • Cihaz ikizi yapısı: Etiketler, istenen ve bildirilen özellikler.
  • Cihaz uygulamalarının ve arka uçlarından oluşan işlemler cihaz ikikilerinde gerçekleştirilebilir.

Cihaz ikizlerini şu şekilde kullan:

  • Cihaza özel meta verileri bulutta depolayın. Örneğin, bir havalandırma makinesinin dağıtım konumu.

  • Cihaz uygulamanızdan kullanılabilir yetenekler ve koşullar gibi geçerli durum bilgilerini bildirin. Örneğin, bir cihaz hücresel veya WiFi üzerinden IoT Hub 'ınıza bağlanır.

  • Uzun süre çalışan iş akışlarının durumunu cihaz uygulaması ile arka uç uygulaması arasında eşitler. Örneğin, çözüm arka ucu yüklenecek yeni bellenim sürümünü belirttiğinde ve cihaz uygulaması, güncelleştirme işleminin çeşitli aşamalarını raporlar.

  • Cihazınızın meta verilerini, yapılandırmasını veya durumunu sorgulayın.

Bildirilen özellikleri, cihazdan buluta iletileri veya karşıya dosya yüklemeyi kullanma hakkında rehberlik için cihazdan buluta iletişim kılavuzuna bakın.

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

Cihaz TWINS 'in bir Azure IoT Tak ve Kullan cihazı tarafından kullanılan cihaz modeliyle ilişkisini öğrenmek için bkz. ıot Tak ve kullan dijital TWINS 'ı anlama.

Cihaz ikikesi

Cihaz TWINS, cihazla ilgili bilgi depolar:

  • Cihaz ve arka uçlar cihaz koşullarını ve yapılandırmayı eşitleyebilmek için kullanabilir.

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

Bir cihaz ikizi yaşam döngüsü, ilgili cihaz kimliğiylebağlantılıdır. IoT Hub ' de bir cihaz kimliği oluşturulduğunda veya silindiğinde, cihaz WINS 'i örtülü olarak oluşturulur ve silinir.

Bir cihaz ikizi şunları içeren bir JSON belgesidir:

  • Etiketler. JSON belgesinin çözüm arka ucunun okuyave yazabilmesi için bir bölümü. Etiketler cihaz uygulamalarına görünür değildir.

  • İstenen özellikler. Cihaz yapılandırmasını veya koşullarını eşitlemeye yönelik bildirilen özelliklerle birlikte kullanılır. Çözüm arka ucu, istenen özellikleri ayarlayabilir ve cihaz uygulaması bunları okuyabilir. Cihaz uygulaması, istenen özelliklerde yapılan değişikliklere ilişkin bildirimler de alabilir.

  • Bildirilen özellikler. Cihaz yapılandırması veya koşulları eşitlemesini sağlamak için istenen özelliklerle birlikte kullanılır. Cihaz uygulaması bildirilen özellikleri ayarlayabilir ve çözüm arka ucu bunları okuyabilir ve sorgulayabilir.

  • Cihaz kimliği özellikleri. Device ikizi JSON belgesinin kökü, kimlik kayıt defterindedepolanan karşılık gelen cihaz kimliğinden salt okunurdur özellikleri içerir. Özellikler connectionStateUpdatedTime ve generationId dahil edilmez.

Cihaz ikizi özelliklerinin ekran görüntüsü

Aşağıdaki örnekte bir Device ikizi JSON belgesi gösterilmektedir:

{
    "deviceId": "devA",
    "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": {
        "$etag": "123",
        "deploymentLocation": {
            "building": "43",
            "floor": "1"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata" : {...},
            "$version": 1
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": 55,
            "$metadata" : {...},
            "$version": 4
        }
    }
}

Kök nesnesinde cihaz kimliği özellikleri ve hem hem de özellikleri için kapsayıcı nesneleri bulunur tags reported desired . propertiesKapsayıcı, $metadata $etag $version Device ikizi meta verileri ve iyimser eşzamanlılık bölümlerinde açıklanan bazı salt okunurdur (,, ve) öğeleri içerir.

Bildirilen özellik örneği

Önceki örnekte, Device ikizi batteryLevel cihaz uygulaması tarafından bildirilen bir özelliği içerir. Bu özellik, en son bildirilen pil düzeyine dayanarak cihazlarda sorgulama ve işlem yapmayı mümkün kılar. Diğer örnekler, cihaz uygulaması raporlama cihaz yeteneklerini veya bağlantı seçeneklerini içerir.

Not

Bildirilen özellikler, çözüm arka ucunun bir özelliğin bilinen son değeri ile ilgilendiği senaryoları basitleştirir. Çözüm arka ucunun, zaman serisi gibi zaman damgası bulunan olayların dizileri biçiminde cihaz telemetrisini işlemesi gerekiyorsa cihazdan buluta iletileri kullanın.

İstenen özellik örneği

Önceki örnekte, telemetryConfig cihaz ikizi istenen ve bildirilen özellikler, çözüm arka ucu ve cihaz uygulaması tarafından bu cihaz için telemetri yapılandırmasını eşitleyecek şekilde kullanılır. Örnek:

  1. Çözüm arka ucu istenen özelliği istenen yapılandırma değeriyle ayarlar. Belge, istenen özellik kümesine sahip olan bölümüdür:

    "desired": {
        "telemetryConfig": {
            "sendFrequency": "5m"
        },
        ...
    },
    
  2. Cihaz uygulamasına, bağlantı kurulduktan sonra veya ilk kez yeniden bağlanıldığında değişiklik yapılır. Daha sonra cihaz uygulaması, güncelleştirilmiş yapılandırmayı (veya özelliğini kullanarak bir hata koşulunu status ) raporlar. Bildirilen özelliklerin bölümü aşağıda verilmiştir:

    "reported": {
        "telemetryConfig": {
            "sendFrequency": "5m",
            "status": "success"
        }
        ...
    }
    
  3. Çözüm arka ucu, cihaz TWINS 'i sorgulayarak , yapılandırma işleminin sonuçlarını birçok cihazda izleyebilir.

Not

Yukarıdaki kod parçacıkları, bir cihaz yapılandırmasını ve durumunu kodlamak için en iyi duruma getirilmiş örneklerdir. IoT Hub, cihaz TWINS 'te istenen ve bildirilen özellikler ikizi cihaz için belirli bir şema uygulamaz.

Üretici yazılımı güncelleştirmeleri gibi uzun süreli işlemleri eşleştirmek için TWINS kullanabilirsiniz. Cihazlarda uzun süren bir işlemi senkronize etmek ve izlemek için özellikleri kullanma hakkında daha fazla bilgi için bkz. cihazları yapılandırmak için istenen özellikleri kullanma.

Arka uç işlemleri

Çözüm arka ucu, HTTPS üzerinden sunulan aşağıdaki atomik işlemleri kullanarak cihaz ikizi üzerinde çalışır:

  • İkizi CIHAZ kimliğini alın. Bu işlem, Etiketler ve istenen ve bildirilen sistem özellikleri dahil olmak üzere Device ikizi belgesini döndürür.

  • Cihaz Ikizi kısmen güncelleştirme. Bu işlem, çözüm arka ucunun, bir cihaz ikizi etiketleri veya istenen özellikleri kısmen güncelleştirmesine olanak sağlar. Kısmi güncelleştirme, herhangi bir özelliği ekleyen veya güncelleştiren bir JSON belgesi olarak ifade edilir. Olarak ayarlanan özellikler null kaldırılır. Aşağıdaki örnek, yeni bir istenen özelliği değeri ile oluşturur {"newProperty": "newValue"} , var olan değerinin üzerine yazar existingProperty "otherNewValue" ve kaldırır otherOldProperty . İstenen varolan özellikler veya etiketlere başka bir değişiklik yapılmaz:

    {
         "properties": {
             "desired": {
                 "newProperty": {
                     "nestedProperty": "newValue"
                 },
                 "existingProperty": "otherNewValue",
                 "otherOldProperty": null
             }
         }
    }
    
  • İstenen özellikleri değiştirin. Bu işlem, çözüm arka ucunun, tüm mevcut özellikleri tümüyle üzerine yazmasına ve için yeni bir JSON belgesi yerine geçecek şekilde olanak sağlar properties/desired .

  • Etiketleri değiştirin. Bu işlem, çözüm arka ucunun tüm mevcut etiketlerin üzerine yazılmasına ve yeni bir JSON belgesini yerine kullanmasına olanak sağlar tags .

  • İkizi bildirimleri alın. Bu işlem, ikizi değiştirildiğinde çözüm arka ucunun bildirilmesini sağlar. Bunu yapmak için, IoT çözümünüzün bir rota oluşturması ve veri kaynağını twinChangeEvents' e eşit olarak ayarlaması gerekir. Varsayılan olarak, bu tür yollar önceden mevcut olmadığından, hiçbir ikizi bildirimi gönderilmez. Değişiklik hızı çok yüksekse veya iç arızalar gibi diğer nedenlerden dolayı IoT Hub tüm değişiklikleri içeren yalnızca bir bildirim gönderebilir. Bu nedenle, uygulamanızın tüm ara durumların güvenilir denetim ve günlüğe kaydetme ihtiyacı varsa cihazdan buluta iletileri kullanmanız gerekir. İkizi bildirim iletisi, özellikleri ve gövdesi içerir.

    • Özellikler

      Name Değer
      $content türü uygulama/json
      $iothub-enqueuedtime Bildirimin gönderildiği zaman
      $iothub-ileti-kaynak twinChangeEvents
      $content kodlaması UTF-8
      deviceId Cihazın KIMLIĞI
      hubName IoT Hub adı
      operationTimestamp ISO8601 işlem zaman damgası
      iothub-message-schema twinChangeNotification
      Optype "replaceTwin" veya "updateTwin"

      İleti sistemi özellikleri simgesiyle önek $ olarak gösterilir.

    • Gövde

      Bu bölüm, JSON biçimindeki tüm ikiz değişikliklerini içerir. Etiketler, properties.reported, properties.desired ve "$metadata" öğelerini içeren etiketler, properties.reported gibi tüm ikiz bölümlerini içerebiliyor olması fark ile düzeltme ekiyle aynı biçimi kullanır. Örneğin,

      {
        "properties": {
            "desired": {
                "$metadata": {
                    "$lastUpdated": "2016-02-30T16:24:48.789Z"
                },
                "$version": 1
            },
            "reported": {
                "$metadata": {
                    "$lastUpdated": "2016-02-30T16:24:48.789Z"
                },
                "$version": 1
            }
        }
      }
      

Yukarıdaki tüm işlemler İyimser eşzamanlılığı destekler ve Denetim erişimi altında tanımlandığı gibi ServiceConnect iznini IoT Hub.

Bu işlemlere ek olarak çözüm arka uç şunları da sağlar:

Cihaz işlemleri

Cihaz uygulaması, aşağıdaki atomik işlemleri kullanarak cihaz ikizi üzerinde çalışır:

  • Cihaz ikizi alın. Bu işlem, o anda bağlı olan cihaz için cihaz ikizi belgesini (istenen ve bildirilen sistem özellikleri dahil) döndürür. (Etiketler cihaz uygulamaları tarafından görünmez.)

  • Bildirilen özellikleri kısmen güncelleştirin. Bu işlem, o anda bağlı olan cihazın bildirilen özelliklerinin kısmi güncelleştirmesini sağlar. Bu işlem, çözüm arka ucunda istenen özelliklerin kısmi bir güncelleştirmesi için kullandığı JSON güncelleştirme biçimini kullanır.

  • İstenen özellikleri gözlemler. O anda bağlı olan cihaz, güncelleştirmeler olduğunda istenen özelliklere bildirilebilir. Cihaz, çözüm arka ucunda yürütülen aynı güncelleştirmeyi (kısmi veya tam değiştirme) alır.

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

Azure IoT cihaz SDK'leri, birçok dilden ve platformdan önceki işlemlerin kullanımını kolaylaştırır. İstenen özellikler eşitlemesi için temel IoT Hub ayrıntıları hakkında daha fazla bilgi için bkz. Cihaz yeniden bağlanma akışı.

Etiketler ve özellikler biçimi

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

  • Anahtarlar: JSON nesnelerinin tüm anahtarları UTF-8 kodlamalı, büyük/büyük harfe duyarlı ve 1 KB'a kadar uzunluktadır. İzin verilen karakterler UNICODE denetim karakterlerini (segment C0 ve C1) ve . , $ ve SP'yi dışlar.

  • Değerler: JSON nesnelerinin tüm değerleri şu JSON türlerinden olabilir: boole, sayı, dize, nesne. Diziler de de destekler.

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

    • Dize değerleri UTF-8 kodlamalıdır ve en fazla 4 KB uzunluğunda olabilir.

  • Derinlik: Etiketlerdeki JSON nesnelerinin, istenen özelliklerin ve bildirilen özelliklerin maksimum derinliği 10'dır. Örneğin, aşağıdaki nesne geçerlidir:

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

Cihaz ikizi boyutu

IoT Hub değerine 8 KB boyut sınırı ve ve değerinde her biri tags için 32 KB boyut sınırı properties/desired properties/reported uygulanır. Bu toplamlar , ve gibi salt okunur $etag $version öğelerden $metadata/$lastUpdated oluşur.

İkiz boyutu şu şekilde hesaplanır:

  • JSON belgesinde yer alan her özellik IoT Hub, özelliğin anahtarının ve değerinin uzunluğunu toplu olarak hesaplar ve ekler.

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

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

  • UTF8 ile kodlanmış dizelerin boyutu, UNICODE denetim karakterleri (segment C0 ve C1) hariç olmak üzere tüm karakterleri sayarak hesaplanır.

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

IoT Hub , veya belgelerinin boyutunu sınırın üzerine artıran tüm işlemler tags properties/desired properties/reported hatayla reddeder.

Cihaz ikizi meta verileri

IoT Hub, istenen ve bildirilen cihaz ikizi özelliklerinde her JSON nesnesi için son güncelleştirmenin zaman damgasını sürdürür. Zaman damgası UTC biçimindedir ve ISO8601 biçiminde YYYY-MM-DDTHH:MM:SS.mmmZ kodlanır.

Örnek:

{
    ...
    "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": {
                        "$lastUpdated": "2016-03-31T16:35:48.789Z"
                    },
                    "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
        }
    }
    ...
}

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

İyimser eşzamanlılık

Etiketler, istenen ve bildirilen özelliklerin hepsi iyimser eşzamanlılığı destekler. Etiketler, RFC7232 başınaetiketin JSON gösterimini temsil eden bir ETag içerir. Tutarlılık sağlamak için çözümün arka ucundaki koşullu güncelleştirme işlemlerinde ETag'leri kullanabilirsiniz.

İstenen ve bildirilen cihaz ikizi özellikleri ETag'lere sahip değildir, ancak $version artımlı olması garanti edilen bir değere sahiptir. ETag'e benzer şekilde, güncelleştirmeler tutarlılık sağlamak için güncelleştirme tarafları tarafından kullanılabilir. Örneğin, bildirilen bir özellik için bir cihaz uygulaması veya istenen bir özellik için çözüm arka uç.

Bir gözlem aracısı (istenen özellikleri gözlemleyen cihaz uygulaması gibi) alma işlemi ile güncelleştirme bildiriminin sonucu arasında karşılıklı muadil olması gereken durumlarda sürümler de yararlıdır. Cihaz yeniden bağlanma akışı bölümü daha fazla bilgi sağlar.

Cihaz yeniden bağlantısı akışı

IoT Hub, bağlantısı kesilmiş cihazlar için istenen özellikleri güncelleştirme bildirimlerini korumaz. Ardından, bağlanan bir cihazın güncelleştirme bildirimlerine abone olmak için abone olmak için istenen tüm özellikler belgesini de almaları gerekir. Güncelleştirme bildirimleri ile tam alma arasında geçiş yapma olasılığı gözlenirse aşağıdaki akışın sağlanması gerekir:

  1. Cihaz uygulaması bir IoT hub'a bağlanır.
  2. Cihaz uygulaması istenen özelliklere abone olur güncelleştirme bildirimleri.
  3. Cihaz uygulaması, istenen özellikler için belgenin tamamını verir.

Cihaz uygulaması, tam alınan belgenin $version sürümünden daha az veya eşit olan tüm bildirimleri yoksayabilirsiniz. Bu yaklaşım, IoT Hub her zaman artma garantisine sahip olduğundan mümkündür.

Not

Bu mantık, Azure IoT cihaz SDK'larında zaten uygulanmıştır. Bu açıklama yalnızca cihaz uygulamasının Herhangi bir Azure IoT cihaz SDK'sı kullanamaysa ve MQTT arabirimini doğrudan programlaması gerekirse yararlıdır.

Ek başvuru malzemeleri

Geliştirici kılavuzunda yer alan IoT Hub konular şunlardır:

  • Genel IoT Hub uç noktaları makalesinde, her IoT hub'ını çalışma zamanı ve yönetim işlemleri için ortaya çıkaran çeşitli uç noktalar açıklanmıştır.

  • Azaltma ve kotalar makalesi, IoT Hub hizmeti için geçerli olan kotaları ve hizmeti kullanırken beklemeniz gereken azaltma davranışını açıklar.

  • Azure IoT cihaz ve hizmet SDK'ları makalesinde, uygulamalarla etkileşimde bulunarak hem cihaz hem de hizmet uygulamaları geliştirirken kullanabileceğiniz çeşitli dil IOT HUB.

  • Cihaz IoT Hub, işler ve ileti yönlendirme için sorgu dili makalesinde, IoT Hub ikizleri ve işleriniz hakkında daha fazla bilgi almak için kullanabileceğiniz IoT Hub dili açıklanmıştır.

  • MQTT IoT Hub makalesi, MQTT protokolü için IoT Hub daha fazla bilgi sağlar.

Sonraki adımlar

Artık cihaz ikizleri hakkında bilgi edinebilirsiniz. Geliştirici kılavuzuyla ilgili IoT Hub ilginizi çekebilirsiniz:

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