IoT Hub'de cihaz ikizlerini anlama ve kullanma

Cihaz ikizleri meta veriler, yapılandırmalar ve koşullar gibi cihaz durumu bilgilerini depolayan JSON belgeleridir. 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 standart IoT Hub katmanında kullanılabilir. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. Çözümünüz için doğru IoT Hub katmanını seçme.

Bu makalede şunlar açıklanmaktadır:

• Cihaz ikizinin yapısı: etiketler, istenen ve bildirilen özellikler.
• Cihaz uygulamalarının ve arka uçlarının cihaz ikizlerinde gerçekleştirebileceği işlemler.

Cihaz ikizlerini kullanarak:

• Cihaza özgü meta verileri bulutta depolayın. Örneğin, bir satış makinesinin dağıtım konumu.

• Cihaz uygulamanızdaki kullanılabilir özellikler ve koşullar gibi geçerli durum bilgilerini bildirin. Örneğin, bir cihazın hücresel veya WiFi üzerinden IoT hub'ınıza bağlı olup olmadığı.

• Cihaz uygulaması ve arka uç uygulaması arasında uzun süre çalışan iş akışlarının durumunu eşitleyin. Örneğin, çözüm arka ucu yüklenecek yeni üretici yazılımı sürümünü belirttiğinde ve cihaz uygulaması güncelleştirme işleminin çeşitli aşamalarını raporladığında.

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

Bildirilen özellikleri, cihazdan buluta iletileri veya dosya yükleme özelliklerini 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.

Cihaz ikizlerinin Azure IoT Tak Çalıştır cihazı tarafından kullanılan cihaz modeliyle ilişkisini öğrenmek için bkz. Dijital ikizleri IoT Tak Çalıştır anlama.

Cihaz ikizleri

Cihaz ikizleri, cihazla ilgili şu bilgileri depolar:

• Cihaz ve arka uçlar, cihaz 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 kullanabilir.

Cihaz ikizinin yaşam döngüsü ilgili cihaz kimliğine bağlıdır. IoT Hub bir cihaz kimliği oluşturulduğunda veya silindiğinde cihaz ikizleri örtük olarak oluşturulur ve silinir.

Cihaz ikizi, şunları içeren bir JSON belgesidir:

• Etiketler'i seçin. JSON belgesinin çözüm arka ucunun okuyabileceği ve yazabileceği bir bölüm. Etiketler cihaz uygulamalarına görünmez.

• İstenen özellikler. Cihaz yapılandırmasını veya koşullarını eşitlemek için bildirilen özelliklerle birlikte kullanılır. Çözüm arka ucu istenen özellikleri ayarlayabilir ve cihaz uygulaması bunları okuyabilir. Cihaz uygulaması, istenen özelliklerdeki değişikliklerle ilgili bildirimler de alabilir.

• Bildirilen özellikler. Cihaz yapılandırmasını veya koşullarını eşitlemek 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. Cihaz ikizi JSON belgesinin kökü, kimlik kayıt defterinde depolanan ilgili cihaz kimliğinden salt okunur özellikleri içerir. generationId ve özellikleri connectionStateUpdatedTime dahil edilmeyecektir.

Aşağıdaki örnekte bir cihaz 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": {
        "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 nesnede cihaz kimliği özellikleri ve ile ile özellikleri için tagsreporteddesired kapsayıcı nesneleri bulunur. Kapsayıcı, propertiesCihaz ikizi meta verileri ve $versionİyimser eşzamanlılık bölümlerinde açıklanan bazı salt okunur öğeleri ($metadata ve ) içerir.

Bildirilen özellik örneği

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

Not

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

İstenen özellik örneği

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

1. Çözüm arka ucu 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. Cihaz bağlıysa cihaz uygulamasına değişiklik anında bildirilir. Bağlı değilse, cihaz uygulaması bağlandığında cihaz yeniden bağlantı akışını izler. Ardından cihaz uygulaması güncelleştirilmiş yapılandırmayı (veya özelliğini kullanan bir hata koşulu) status bildirir. Bildirilen özelliklerin bölümü aşağıdadır:

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

3. Çözüm arka ucu, cihaz ikizlerini sorgulayarak birçok cihazda yapılandırma işleminin sonuçlarını izleyebilir.

Not

Önceki kod parçacıkları, bir cihaz yapılandırmasını ve durumunu kodlamanın bir yolunun okunabilirliği için iyileştirilmiş örneklerdir. IoT Hub, cihaz ikizlerinde istenen ve bildirilen cihaz ikizi özellikleri 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ına uymanız gerekir. Daha fazla bilgi ve örnek için bkz. IoT Tak Çalıştır yazılabilir özellikler.

Bellenim güncelleştirmeleri gibi uzun süre çalışan işlemleri eşitlemek için ikizleri kullanabilirsiniz. Uzun süre çalışan bir işlemi cihazlar arasında eşitlemek 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 aracılığıyla kullanıma sunulan aşağıdaki atomik işlemleri kullanarak cihaz ikizi üzerinde çalışır:

• Kimliğine göre cihaz ikizi alma. Bu işlem, etiketler ve istenen ve bildirilen sistem özellikleri de dahil olmak üzere cihaz ikizi belgesini döndürür.

• Cihaz ikizlerini kısmen güncelleştirin. Bu işlem, çözüm arka ucunun cihaz ikizindeki etiketleri veya istenen özellikleri kısmen güncelleştirmesini sağlar. 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ğeriyle {"newProperty": "newValue"}yeni bir istenen özellik oluşturur, ile "otherNewValue"varolan değerinin existingProperty üzerine yazar ve öğesini kaldırırotherOldProperty. 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, çözüm arka ucunun varolan tüm istenen özelliklerin üzerine tamamen yazılmasını ve için properties/desiredyeni bir JSON belgesiyle değiştirmesini sağlar.

• Etiketleri değiştirin. Bu işlem, çözüm arka ucunun tüm mevcut etiketlerin üzerine tamamen yazılmasını ve için tagsyeni bir JSON belgesiyle değiştirmesini sağlar.

• İkiz bildirimleri alın. Bu işlem, ikiz değiştirildiğinde çözüm arka ucunun bildirilmesini sağlar. Bunu yapmak 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. İkiz bildirim iletisinde döndürülen özellikler ve gövde hakkında daha fazla bilgi edinmek için bkz. Telemetri dışı olay şemaları.

Önceki tüm işlemler İyimser eşzamanlılığı destekler ve IoT Hub erişimi denetleme bölümünde tanımlandığı gibi ServiceConnect izni gerektirir.

Bu işlemlere ek olarak çözüm arka ucu şunları yapabilir:

• SQL benzeri IoT Hub sorgu dilini kullanarak cihaz ikizlerini sorgular.

• İşleri kullanarak büyük cihaz ikizleri kümelerinde işlemler gerçekleştirin.

Cihaz işlemleri

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

• Cihaz ikizlerini alma. Bu işlem, bağlı durumdaki cihaz için cihaz ikizi belgesini (istenen ve bildirilen sistem özellikleri dahil) döndürür. (Etiketler cihaz uygulamalarına 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 ucunun istenen özelliklerin kısmi bir güncelleştirmesi için kullandığı JSON güncelleştirme biçimini kullanır.

• İstenen özellikleri gözlemleyin. Şu anda bağlı olan cihaz, gerçekleştiğinde istenen özelliklere yapılan güncelleştirmelerin bildirilmesini seçebilir. Cihaz, çözüm arka ucu tarafından yürütülen aynı güncelleştirme biçimini (kısmi veya tam değiştirme) alır.

Önceki tüm işlemler, IoT Hub Erişimi Denetleme bölümünde 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. İstenen özellikler eşitlemesi için IoT Hub temel öğelerinin ayrıntıları hakkında daha fazla bilgi için bkz. Cihaz yeniden bağlantı akışı.

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 kodlamalı, 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.

  Not

  İleti Yönlendirme'de kullanılan IoT Hub sorguları boşluk veya anahtar adının bir parçası olarak aşağıdaki karakterlerden hiçbirini desteklemez: ()<>@,;:\"/?={}.

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

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

  • Dize değerleri UTF-8 ile kodlanı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"
                                               }
                                           }
                                       }
                                   }
                               }
                           }
                       }
                   }
               }
           }
       },
       ...
  }
  

Cihaz ikizi boyutu

IoT Hub değeri için 8 KB boyut sınırı, ve properties/reporteddeğerinde tagsher properties/desired biri için 32 KB boyut sınırı uygular. Bu toplamlar ve $metadata/$lastUpdatedgibi $version salt okunur öğelerden özeldir.

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

• JSON belgesindeki her özellik için IoT Hub toplu olarak hesaplar ve özelliğin anahtarının ve değerinin uzunluğunu 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 kodlu 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), içerdikleri özellik anahtarlarının ve özellik değerlerinin toplam boyutuna göre hesaplanır.

IoT Hub, , properties/desiredveya properties/reported belgelerinin boyutunu tagssınırın üzerinde artıracak tüm işlemler hatayla reddeder.

Cihaz ikizi meta verileri

IoT Hub, cihaz ikizi istenen ve bildirilen özelliklerde her JSON nesnesi için son güncelleştirmenin zaman damgasını korur. Zaman damgaları UTC biçimindedir ve ISO8601 biçiminde YYYY-MM-DDTHH:MM:SS.mmmZkodlanmıştır.

Ö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": {
                        "$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 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.

Cihaz ikizlerinin RFC7232'ye göre ikizin JSON gösterimini temsil eden bir ETag (etag özelliği) vardır. Tutarlılığı sağlamak için çözüm arka ucundan koşullu güncelleştirme işlemlerinde özelliğini kullanabilirsiniz etag . Kapsayıcıyı içeren tags işlemlerde tutarlılık sağlamak için tek seçenek budur.

Cihaz ikizi istenen ve bildirilen özelliklerin artımlı olması garanti edilen bir $version değeri de vardır. ETag'e benzer şekilde, sürüm güncelleştirme tarafı tarafından güncelleştirmelerin tutarlılığını zorlamak için kullanılabilir. Örneğin, bildirilen bir özellik için bir cihaz uygulaması veya istenen özellik için çözüm arka ucu.

Bir gözlem aracısının (istenen özellikleri gözlemleyen cihaz 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. Cihaz yeniden bağlantı akışı bölümü daha fazla bilgi sağlar.

Cihaz yeniden bağlantı akışı

IoT Hub, bağlantısı kesilmiş cihazlar için istenen özellikleri güncelleştirme bildirimlerini korumaz. Bunun ardından, bağlanan bir cihazın güncelleştirme bildirimlerine abone olmasına ek olarak istenen tam özellikler belgesini alması gerekir. Güncelleştirme bildirimleri ile tam alma arasında yarış olasılığı göz önüne alındığında, aşağıdaki akışın sağlanması gerekir:

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

Cihaz uygulaması, tam alınan belgenin sürümünden küçük veya eşit olan tüm bildirimleri $version yoksayabilir. bu yaklaşım mümkündür çünkü IoT Hub sürümlerin her zaman arttığını garanti eder.

Ek başvuru malzemeleri

IoT Hub geliştirici kılavuzundaki diğer başvuru konuları şunlardır:

• IoT Hub uç noktaları makalesinde, her IoT hub'ına çalışma zamanı ve yönetim işlemleri için kullanıma sunan çeşitli uç noktalar açıklanır.

• Azaltma ve kotalar makalesi, IoT Hub hizmetine uygulanan kotaları ve hizmeti kullandığınızda bekleyebileceğiniz azaltma davranışını açıklar.

• Azure IoT cihaz ve hizmet SDK'ları makalesinde, IoT Hub ile etkileşim kuran hem cihaz hem de hizmet uygulamaları geliştirirken kullanabileceğiniz çeşitli dil SDK'ları listelenir.

• Cihaz ikizleri, işler ve ileti yönlendirme için IoT Hub sorgu dili makalesi, cihaz ikizleriniz ve işleriniz hakkındaki IoT Hub bilgi almak için kullanabileceğiniz IoT Hub sorgu dilini açıklar.

• IoT Hub MQTT destek makalesi, MQTT protokolü için IoT Hub desteği hakkında daha fazla bilgi sağlar.

Sonraki adımlar

Artık cihaz ikizleri hakkında bilgi edindiniz, aşağıdaki IoT Hub geliştirici kılavuzu konuları ilginizi çekebilir:

• IoT Hub modül ikizlerini anlama ve kullanma
• Bir cihazda doğrudan yöntem çağırma
• Birden fazla cihazda işleri zamanlama

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

• Cihaz ikizini kullanma
• Cihaz ikizi özelliklerini kullanma
• VS Code için Azure IoT Araçları ile cihaz yönetimi