IoT Tak Çalıştır dijital ikizlerini anlama

Makale
02/06/2024

IoT Tak Çalıştır cihaz, Digital Twins Tanım Dili (DTDL) şeması tarafından açıklanan bir model uygular. Model, belirli bir cihazın sahip olabileceği bileşen, özellik, komut ve telemetri iletileri kümesini açıklar.

Not

DTDL, IoT Tak Çalıştır özel değildir. Azure Digital Twins gibi diğer IoT hizmetleri bunu binalar ve enerji ağları gibi ortamların tamamını temsil etmek için kullanır.

Azure IoT hizmeti SDK'ları, bir hizmetin bir cihazın dijital ikizini etkileşime geçirmesine olanak sağlayan API'leri içerir. Örneğin, bir hizmet dijital ikizden cihaz özelliklerini okuyabilir veya bir cihazda komut çağırmak için dijital ikizi kullanabilir. Daha fazla bilgi edinmek için bkz . IoT Hub dijital ikiz örnekleri.

Bu makaledeki örnek IoT Tak Çalıştır cihaz, Thermostat bileşenlerine sahip bir Sıcaklık Denetleyicisi modeli uygular.

Cihaz ikizleri ve dijital ikizler

Azure IoT Hub, dijital ikizin yanı sıra her bağlı cihaz için de bir cihaz ikizi tutar. Cihaz ikizi, bir cihaz özelliklerinin gösterimi olması açısından dijital ikize benzer. IoT hub'ı, bir IoT Tak Çalıştır cihazı ilk kez sağlandığında dijital ikiz ve cihaz ikizi başlatır. Azure IoT hizmeti SDK'ları, cihaz ikizleriyle etkileşime yönelik API'leri içerir.

Cihaz ikizleri; meta veriler, yapılandırmalar ve koşullar gibi cihaz durumu bilgilerini depolayan JSON belgelerdir. Daha fazla bilgi edinmek için bkz . IoT Hub hizmeti istemci örnekleri. Cihaz ve çözüm oluşturucuları, IoT Tak Çalıştır kurallarını kullanarak cihazları ve çözümleri uygulamak için aynı cihaz ikizi API'lerini ve SDK'larını kullanabilir. Bir cihaz ikizinde yazılabilir özelliğin durumu istenen özelliklere ve bildirilen özellikler bölümlerine bölünür. Tüm salt okunur özellikler, bildirilen özellikler bölümünde kullanılabilir.

Dijital ikiz API'leri bileşenler, özellikler ve komutlar gibi üst düzey DTDL yapıları üzerinde çalışır ve çözüm oluşturucularının IoT Tak Çalıştır çözümler oluşturmasını kolaylaştırır. Dijital ikizde özelliğin geçerli ve istenen durumunun birleşik bir görünümü vardır. Belirli bir özelliğin eşitleme durumu ilgili varsayılan bileşen $metadata bölümünde depolanır.

Cihaz ikizi JSON örneği

Aşağıdaki kod parçacığı JSON nesnesi olarak biçimlendirilmiş bir IoT Tak Çalıştır cihaz ikizini gösterir:

{
  "deviceId": "sample-device",
  "modelId": "dtmi:com:example:TemperatureController;1",
  "version": 15,
  "properties": {
    "desired": {
      "thermostat1": {
        "__t": "c",
        "targetTemperature": 21.8
      },
      "$metadata": {...},
      "$version": 4
    },
    "reported": {
      "serialNumber": "alwinexlepaho8329",
      "thermostat1": {
        "maxTempSinceLastReboot": 25.3,
        "__t": "c",
        "targetTemperature": {
          "value": 21.8,
          "ac": 200,
          "ad": "Successfully executed patch",
        }
      },
      "$metadata": {...},
      "$version": 11
    }
  }
}

Dijital ikiz örneği

Aşağıdaki kod parçacığında JSON nesnesi olarak biçimlendirilmiş dijital ikiz gösterilmektedir:

{
  "$dtId": "sample-device",
  "serialNumber": "alwinexlepaho8329",
  "thermostat1": {
    "maxTempSinceLastReboot": 25.3,
    "targetTemperature": 21.8,
    "$metadata": {
      "targetTemperature": {
        "desiredValue": 21.8,
        "desiredVersion": 4,
        "ackVersion": 4,
        "ackCode": 200,
        "ackDescription": "Successfully executed patch",
        "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
      },
      "maxTempSinceLastReboot": {
         "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:example:TemperatureController;1",
    "serialNumber": {
      "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
    }
  }
}

Aşağıdaki tabloda dijital ikiz JSON nesnesindeki alanlar açıklanmaktadır:

Alan adı	Açıklama
`$dtId`	Cihaz dijital ikizinin kimliğini temsil eden kullanıcı tarafından sağlanan bir dize.
`{propertyName}`	JSON'daki bir özelliğin değeri.
`$metadata.$model`	[İsteğe bağlı] Bu dijital ikizi karakterize eden model arabiriminin kimliği.
`$metadata.{propertyName}.desiredValue`	[Yalnızca yazılabilir özellikler için] Belirtilen özelliğin istenen değeri.
`$metadata.{propertyName}.desiredVersion`	[Yalnızca yazılabilir özellikler için] IoT Hub tarafından tutulan istenen değerin sürümü.
`$metadata.{propertyName}.ackVersion`	[Gerekli, yalnızca yazılabilir özellikler için] Dijital ikizi uygulayan cihaz tarafından kabul edilen sürüm, istenen sürüme eşit veya daha büyük olmalıdır.
`$metadata.{propertyName}.ackCode`	[Gerekli, yalnızca yazılabilir özellikler için] Dijital `ack` ikizini uygulayan cihaz uygulaması tarafından döndürülen kod.
`$metadata.{propertyName}.ackDescription`	[İsteğe bağlı, yalnızca yazılabilir özellikler için] `ack` Dijital ikizini uygulayan cihaz uygulaması tarafından döndürülen açıklama.
`$metadata.{propertyName}.lastUpdateTime`	IoT Hub, özelliğin cihaz tarafından son güncelleştirmesinin zaman damgasını korur. Zaman damgaları UTC biçimindedir ve YYYY-MM-DDTHH:MM:SS.mmmZ ISO8601 biçiminde kodlanmıştır.
`{componentName}`	Bileşenin özellik değerlerini ve meta verilerini içeren bir JSON nesnesi.
`{componentName}.{propertyName}`	JSON'da bileşenin özelliğinin değeri.
`{componentName}.$metadata`	Bileşenin meta veri bilgileri.

Özellikler

Özellikler, nesne odaklı programlama dillerindeki özellikler gibi bir varlığın durumunu temsil eden veri alanlarıdır.

Salt okunur özellik

DTDL şeması:

{
    "@type": "Property",
    "name": "serialNumber",
    "displayName": "Serial Number",
    "description": "Serial number of the device.",
    "schema": "string"
}

Bu örnekte, alwinexlepaho8329 cihaz tarafından bildirilen salt okunur özelliğin serialNumber geçerli değeridir.

Aşağıdaki kod parçacıkları özelliğin yan yana JSON gösterimini serialNumber gösterir:

Cihaz ikizi

"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}

Dijital ikiz

"serialNumber": "alwinexlepaho8329"

Yazılabilir özellik

Aşağıdaki örneklerde varsayılan bileşende yazılabilir bir özellik gösterilmektedir.

DTDL:

{
  "@type": "Property",
  "name": "fanSpeed",
  "displayName": "Fan Speed",
  "writable": true,
  "schema": "double"
}

Cihaz ikizi

{
"properties": {
"desired": {
"fanSpeed": 2.0,
},
"reported": {
"fanSpeed": {
"value": 3.0,
"ac": 200,
"av": 1,
"ad": "Successfully executed patch version 1"
}
}
},
}

Dijital ikiz

{
"fanSpeed": 3.0,
"$metadata": {
"fanSpeed": {
"desiredValue": 2.0,
"desiredVersion": 2,
"ackVersion": 1,
"ackCode": 200,
"ackDescription": "Successfully executed patch version 1",
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

Bu örnekte, 3.0 cihaz tarafından bildirilen özelliğin fanSpeed geçerli değeridir. 2.0 çözüm tarafından ayarlanan istenen değerdir. Kök düzeyi özelliğinin istenen değeri ve eşitleme durumu, dijital ikiz için kök düzeyinde $metadata ayarlanır. Cihaz çevrimiçi olduğunda bu güncelleştirmeyi uygulayabilir ve güncelleştirilmiş değeri raporlayabilir.

Bileşenler

Bileşenler, diğer arabirimlerin derlemesi olarak bir model arabirimi oluşturmanıza olanak sağlar. Örneğin Termostat arabirimi bileşen thermostat1 olarak ve thermostat2 Sıcaklık Denetleyicisi model modelinde birleştirilebilir.

Cihaz ikizinde, bir bileşen işaretçi tarafından { "__t": "c"} tanımlanır. Dijital ikizde, varlığı $metadata bir bileşeni işaretler.

Bu örnekte, thermostat1 iki özelliğe sahip bir bileşendir:

maxTempSinceLastReboot salt okunur bir özelliktir.
targetTemperature , cihaz tarafından başarıyla eşitlenen yazılabilir bir özelliktir. Bu özelliklerin istenen değeri ve eşitleme durumu bileşenin $metadataiçindedir.

Aşağıdaki kod parçacıkları, bileşenin yan yana JSON gösterimini thermostat1 gösterir:

Cihaz ikizi

"properties": {
"desired": {
"thermostat1": {
"__t": "c",
"targetTemperature": 21.8
},
"$metadata": {
},
"$version": 4
},
"reported": {
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"__t": "c",
"targetTemperature": {
"value": 21.8,
"ac": 200,
"ad": "Successfully executed patch",
"av": 4
}
},
"$metadata": {
},
"$version": 11
}
}

Dijital ikiz

"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 21.8,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.8,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

Dijital ikiz API'leri

Dijital ikiz API'leri Arasında Get Digital Twin, Update Digital Twin, Invoke Component Command ve Invoke Command işlemleri daha çok bir dijital ikizi yönetir. REST API'lerini doğrudan veya hizmet SDK'larından biri aracılığıyla kullanabilirsiniz.

Dijital ikiz değişiklik olayları

Dijital ikiz değişiklik olayları etkinleştirilirse, bileşenin veya özelliğin geçerli veya istenen değeri her değiştiğinde bir olay tetiklenir. Dijital ikiz değişiklik olayları JSON Düzeltme Eki biçiminde oluşturulur. İkiz değişiklik olayları etkinse ilgili olaylar cihaz ikizi biçiminde oluşturulur.

Cihaz ve dijital ikiz olayları için yönlendirmeyi etkinleştirmeyi öğrenmek için bkz . Farklı uç noktalara cihazdan buluta ileti göndermek için IoT Hub ileti yönlendirmeyi kullanma. İleti biçimini anlamak için bkz . IoT Hub iletileri oluşturma ve okuma.

Örneğin, çözüm tarafından ayarlandığında aşağıdaki dijital ikiz değişiklik olayı tetikleniyor targetTemperature :

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:04 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d463fa034
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature",
    "value": {
      "desiredValue": 21.8,
      "desiredVersion": 4
    }
  }
]

Cihaz yukarıdaki istenen değişikliğin uygulandığını bildirdiğinde aşağıdaki dijital ikiz değişiklik olayı tetikleniyor:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:05 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d464a2c80
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackCode",
    "value": 200
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackDescription",
    "value": "Successfully executed patch"
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackVersion",
    "value": 4
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/lastUpdateTime",
    "value": "2020-07-17T06:11:04.9309159Z"
  },
  {
    "op": "add",
    "path": "/thermostat1/targetTemperature",
    "value": 21.8
  }
]

Not

İkiz değişiklik bildirimi iletileri hem cihazda hem de dijital ikiz değişiklik bildiriminde açıldığında iki katına alınır.

Sonraki adımlar

Dijital ikizler hakkında bilgi edindiğinize göre, aşağıda daha fazla kaynak bulabilirsiniz:

IoT Tak Çalıştır dijital ikizlerini anlama

Cihaz ikizleri ve dijital ikizler

Cihaz ikizi JSON örneği

Dijital ikiz örneği

Özellikler

Salt okunur özellik

Yazılabilir özellik

Bileşenler

Dijital ikiz API'leri

Dijital ikiz değişiklik olayları

Sonraki adımlar

Ek kaynaklar