IoT Edge'de modülleri dağıtmayı ve yolları kurmayı öğrenin

Applies to: IoT Edge 1.5

Önemli

IoT Edge 1.5 LTS, desteklenen bir sürümdür. IoT Edge 1.4 LTS, 12 Kasım 2024'te kullanım ömrüne ulaştı. Önceki bir sürümü kullanıyorsanız bkz. Update IoT Edge.

Her IoT Edge cihaz en az iki modül çalıştırır: IoT Edge çalışma zamanının parçası olan $edgeAgent ve $edgeHub. bir IoT Edge cihazı farklı işlemler için birden çok modül çalıştırabilir. Cihazınıza hangi modüllerin yükleneceğini ve birlikte çalışacak şekilde nasıl ayarlandığını bildirmek için bir dağıtım bildirimi kullanın.

Dağıtım bildirimi , aşağıdakileri açıklayan bir JSON belgesidir:

• üç bileşen içeren IoT Edge aracısı modül ikizi:
  • Cihazda çalışan her modülün kapsayıcı görüntüsü.
  • Modül görüntüleri içeren özel kapsayıcı kayıt defterlerini kullanmak için kimlik bilgileri.
  • Her modülün nasıl oluşturulduğuna ve yönetil olduğuna ilişkin yönergeler.
• IoT Edge hub modül ikizi, modüller arasında ve IoT Hub'a iletilerin akışını içeren bir sistemdir.
• Ek modül ikizlerinin istenen özellikleri (isteğe bağlı).

Tüm IoT Edge cihazlar bir dağıtım bildirimine ihtiyaç duyar. Yeni yüklenen IoT Edge çalışma zamanı, siz geçerli bir bildirim ayarlayana kadar bir hata kodu gösterir.

Azure IoT Edge öğreticilerinde, Azure IoT Edge portalında bir sihirbaz kullanarak bir dağıtım bildirimi oluşturursunuz. Ayrıca REST veya IoT Hub Hizmeti SDK'sını kullanarak program aracılığıyla bir dağıtım bildirimi uygulayabilirsiniz. Daha fazla bilgi için bkz. IoT Edge dağıtımlarını anlama.

Dağıtım bildirimi oluşturma

Dağıtım bildirimi, istenen özellikleriyle ayarlanan modül ikizlerinin listesidir. Bir IoT Edge cihazına veya cihaz grubuna hangi modüllerin yükleneceğini ve bunların nasıl ayarlandığını bildirir. Dağıtım bildirimleri her modül ikizi için istenen özellikleri içerir. IoT Edge cihazlar her modül için bildirilen özellikler bildirir.

Her dağıtım bildirimi iki modül gerektirir: $edgeAgent ve $edgeHub. Bu modüller, IoT Edge cihazı ve üzerinde çalışan modülleri yöneten IoT Edge çalışma zamanının bir parçasıdır. Bu modüller hakkında daha fazla bilgi için bkz. IoT Edge çalışma zamanını ve mimarisini anlama.

İki çalışma zamanı modülüne ek olarak bir IoT Edge cihazda çalıştırmak için en fazla 50 ek modül ekleyebilirsiniz.

Yalnızca IoT Edge çalışma zamanını ($edgeAgent ve $edgeHub) içeren bir dağıtım bildirimi geçerlidir.

Dağıtım bildirimleri şu biçimi kullanır:

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Modülleri konfigüre et

IoT Edge çalışma zamanının modülleri dağıtımınıza nasıl yükleneceğini tanımlayın. IoT Edge aracısı, IoT Edge bir cihaz için yükleme, güncelleştirme ve durum raporlamayı yöneten çalışma zamanı bileşenidir. Bu nedenle modül ikizi tüm $edgeAgent modüller için yapılandırma ve yönetim bilgilerine sahiptir. Bu bilgiler, IoT Edge aracısı için yapılandırma parametrelerini içerir.

$edgeAgent Özellikler şu biçimi kullanır:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

IoT Edge aracısı şema sürümü 1.1, IoT Edge sürüm 1.0.10 ile yayımlandı ve modül başlatma sırasını ayarlamanıza olanak tanır. 1.0.10 veya sonraki bir sürümü çalıştıran tüm IoT Edge dağıtımlar için şema sürüm 1.1'i kullanın.

Modül yapılandırması ve yönetimi

bir IoT Edge cihazında hangi modüllerin çalıştırılacağını ve IoT Edge aracı istenen özellikler listesinde bunların nasıl ayarlanıp yönetileceğini tanımlayın.

İstediğiniz veya eklemeniz gereken özelliklerin tam listesi için IoT Edge aracısının ve IoT Edge hub'ının Özellikleri bölümüne bakın.

Örneğin:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Her modülün bir settings özelliği vardır; bu özellik modül görüntüsü, kapsayıcı kayıt defterindeki kapsayıcı görüntüsü için bir adres ve başlangıçta görüntüyü ayarlamak için gereken herhangi bir createOptions'ı içerir. Daha fazla bilgi için bkz. IoT Edge modülleri için kapsayıcı oluşturma seçeneklerini yapılandırma.

EdgeHub modülü ve özel modüller, IoT Edge aracısına bunları nasıl yöneteceklerini belirten üç özelliğe de sahiptir:

• Durum: Modülün ilk dağıtıldığında çalışıp çalışmadığı veya durup durmadığı. Gerekli.

• RestartPolicy: IoT Edge aracısı durursa modülü ne zaman ve ne zaman yeniden başlatır. Modül hata olmadan durursa otomatik olarak yeniden başlatılmaz. Daha fazla bilgi için Docker Belgeleri - Kapsayıcıları Otomatik Başlatma bölümüne bakın. Gerekli.

• StartupOrder: IoT Edge sürüm 1.0.10'da kullanıma sunulmuştur. IoT Edge aracısının modülleri ilk dağıtıldığında başlatmak için kullandığı sıra. Sıra, başlangıç değeri 0 olan bir modülün önce başladığı ve ardından daha yüksek sayıların izlendiği tamsayıları kullanır. $edgeAgent modülünün başlangıç değeri yoktur çünkü her zaman ilk başlar. isteğe bağlı.

  IoT Edge aracısı başlangıç değeri sırasına göre modülleri başlatır, ancak bir sonrakini başlatmadan önce her modülün başlatılmasını beklemez.

  Başlangıç sırası, bazı modüllerin diğerlerine bağlı olması durumunda yardımcı olur. Örneğin, diğer modüller başlatıldığında iletileri yönlendirmeye hazır olması için önce edgeHub modülünün başlatılmasını isteyebilirsiniz. Alternatif olarak, veri gönderen modülleri başlatmadan önce bir depolama modülü başlatmak da isteyebilirsiniz. Ancak modüllerinizi her zaman diğer modüllerin hatalarını işleyecek şekilde tasarlar. Kapsayıcılar istediğiniz zaman ve birkaç kez durdurulabilir ve yeniden başlatılabilir.

  Not

  Modülün özelliklerini değiştirmek bu modülü yeniden başlatır. Örneğin, şunun özelliklerini değiştirirseniz yeniden başlatma gerçekleşir:

  • modül görüntüsü
  • Docker oluşturma seçenekleri
  • ortam değişkenleri
  • yeniden başlatma ilkesi
  • görüntü çekme ilkesi
  • sürüm
  • başlangıç sırası

  Modül özelliklerini değiştirmezseniz, modül yeniden başlatma tetiklenmemiştir.

Rotaları tanımlama

IoT Edge hub'ı modüller, IoT Hub ve aşağı akış cihazları arasındaki iletişimi yönetir. $edgeHub modül ikizinin, iletilerin bir dağıtım içinde nasıl taşındığını tanımlayan adlı routes istenen bir özelliği vardır. Aynı dağıtımda birden çok yol ayarlayabilirsiniz.

Bu söz dizimini kullanarak istenen $edgeHub özelliklerde yolları bildirin:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

IoT Edge sürüm 1.0.10 ile yayımlanan IoT Edge hub şeması sürüm 1, yol önceliklendirmesini ve yaşam süresini ayarlamanıza olanak tanır. 1.0.10 veya sonraki bir sürümü çalıştıran tüm IoT Edge dağıtımlar için şema sürüm 1.1'i kullanın.

Her yol, gelen iletiler için bir kaynağa ve giden iletiler için bir havuza ihtiyaç duyar. Koşul isteğe bağlıdır ve iletileri filtrelemenize olanak tanır.

Önce önemli iletileri işlemek için yollara öncelik atayın. Bu özellik, yukarı akış bağlantısı zayıf veya sınırlı olduğunda ve standart telemetri iletilerine göre kritik verilere öncelik vermeniz gerektiğinde yardımcı olur.

Kaynak

Kaynak, iletilerin nereden geldiğini belirtir. IoT Edge modüllerden veya aşağı akış cihazlarından iletileri yönlendirebilir.

Modüller, IoT SDK'larını ve ModuleClient sınıfını kullanarak iletileri için belirli çıkış kuyrukları ayarlayabilir. Çıkış kuyrukları gerekli değildir, ancak birden çok yolu yönetmeye yardımcı olur. Aşağı akış cihazları, ioT SDK'larındaki DeviceClient sınıfını kullanarak IoT Edge ağ geçidi cihazlarına ileti gönderir, aynı IoT Hub ileti gönderir gibi. Daha fazla bilgi için bkz. Azure IoT Hub SDK'larını anlama ve kullanma.

Kaynak özelliği şu değerlerden herhangi birini kullanabilir:

Kaynak	Açıklama
/*	Herhangi bir modülden veya alt cihazdan gelen tüm cihazdan-buluta iletiler veya ikiz değişiklik bildirimleri.
/twinChangeNotifications	Herhangi bir modülden veya aşağı akış cihazından gelen herhangi bir ikiz değişiklik (bildirilen özellikler).
/messages/*	Bir modül tarafından bazı veya hiç çıkış kullanılmadan veya bir alt akış cihazı ile gönderilen herhangi bir cihazdan buluta ileti.
/messages/modules/*	Bir modül tarafından bazı çıkışlar veya hiçbir çıkış kullanılarak cihazdan buluta gönderilen herhangi bir ileti.
/messages/modules/<moduleId>/*	Belirli bir modül tarafından bazı veya hiç çıkış olmadan gönderilen herhangi bir cihazdan buluta mesaj.
/messages/modules/<moduleId>/outputs/*	Belirli bir modül tarafından herhangi bir çıkış yoluyla gönderilen cihazdan buluta herhangi bir ileti.
/messages/modules/<moduleId>/outputs/<output>	Belirli bir modül tarafından belirli bir çıkış üzerinden gönderilen herhangi bir cihazdan buluta ileti.

Koşul

Koşul, yol bildiriminde isteğe bağlıdır. Kaynaktan havuza tüm iletileri geçirmek için WHERE yan tümcesini çıkartın. Veya koşula uyan iletileri veya ileti türlerini filtrelemek için IoT Hub sorgu dilini kullanın. IoT Edge yollar, ikiz etiketlerine veya özelliklerine göre iletileri filtrelemeyi desteklemez.

IoT Edge modüller arasında hareket eden iletiler, cihazlarınız ve Azure IoT Hub arasındaki iletilerle aynı biçimi kullanır. Tüm iletiler JSON biçimini kullanır ve systemProperties, appProperties ve gövde parametrelerine sahiptir.

Bu söz dizimini kullanarak üç parametreden herhangi birinin etrafında sorgular oluşturun:

• Sistem özellikleri: $<propertyName> veya {$<propertyName>}
• Uygulama özellikleri: <propertyName>
• Gövde özellikleri: $body.<propertyName>

İleti özellikleri için sorgu oluşturma örnekleri için bkz. Cihazdan buluta ileti yönlendirmeleri sorgu ifadeleri.

Örneğin, aşağı akış cihazından bir ağ geçidi cihazına ulaşan iletileri filtrelemek isteyebilirsiniz. Modüllerden gönderilen iletiler connectionModuleId adlı bir sistem özelliği içerir. Aşağı akış cihazlarından gelen iletileri doğrudan IoT Hub yönlendirmek ve modül iletilerini dışlamak için şu yolu kullanın:

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

Lavabo

Havuz, iletilerin nereye gönderileceği tanımlar. İletileri yalnızca modüller ve IoT Hub alabilir. İletileri diğer cihazlara yönlendiremezsiniz. Havuz özelliği joker karakterleri desteklemez.

sink özelliği şu değerlerden herhangi birini kullanabilir:

Lavabo	Açıklama
$upstream	İletiyi IoT Hub'a gönder
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")	İletiyi belirli bir modülün belirli bir girişine gönderme

IoT Edge en az bir kez garantisi sağlar. IoT Edge hub, bir yol iletiyi hedefine teslim edemiyorsa, iletileri yerel olarak depolar. Örneğin, IoT Edge hub IoT Hub'a bağlanamıyorsa veya hedef modül bağlanmamışsa.

IoT Edge hub'ı, storeAndForwardConfiguration.timeToLiveSecs özelliğinde ayarlanan zamana kadar olan iletileri depolar.

Öncelik ve yaşam süresi

Yolları, yolu tanımlayan bir dize olarak veya yol dizesi, öncelik tamsayısı ve yaşam süresi tamsayısı olan bir nesne olarak bildirin.

Seçenek 1

"route1": "FROM <source> WHERE <condition> INTO <sink>",

Seçenek 2 (IoT Edge sürüm 1.0.10'da IoT Edge hub şema sürümü 1.1 ile kullanıma sunulmuştur)

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

Öncelik değerleri 0 ile 9 arasında değişir ve burada 0 en yüksek önceliktir. Sistem iletileri uç noktalarına göre kuyruğa alır. Sistem, aynı uç nokta için öncelik 1 iletilerini işlemeden önce belirli bir uç nokta için tüm öncelikli 0 iletilerini işler. Aynı uç nokta için birden çok yol aynı önceliğe sahipse, sistem iletileri geldikleri sırayla işler. Öncelik ayarlamazsanız, yol en düşük önceliği kullanır.

timeToLiveSecs özelliği, doğrudan ayarlamadığınız sürece IoT Edge hub'ının storeAndForwardConfiguration değerini kullanır. Değer herhangi bir pozitif tamsayı olabilir.

Öncelik kuyruklarının nasıl yönetildiğinin ayrıntıları için bkz. Rota önceliği ve ömrü.

İstenen özellikleri tanımlama veya güncelleştirme

Dağıtım bildirimi, IoT Edge cihaza dağıtılan her modül için istenen özellikleri ayarlar. Dağıtım bildirimindeki istenen özellikler, şu anda modül ikizinde bulunan istenen özelliklerin üzerine yazar.

Dağıtım bildiriminde modül ikizinin istenen özelliklerini ayarlamazsanız IoT Hub modül ikizini değiştirmez. Bunun yerine, istenen özellikleri program aracılığıyla ayarlayın.

Cihaz ikizlerini değiştirmenize olanak sağlayan mekanizmalar, modül ikizlerini de değiştirmenize olanak sağlar. Daha fazla bilgi için modül ikizi geliştirici kılavuzuna bakın.

Dağıtım bildirimi örneği

Aşağıdaki örnekte geçerli bir dağıtım bildirimi belgesinin nasıl görünebileceği gösterilmektedir.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

Sonraki adımlar

• $edgeAgent ve $edgeHub'e ekleyebileceğiniz veya eklemeniz gereken özelliklerin tam listesi için bkz: IoT Edge aracısının ve IoT Edge hub'ın Özellikleri.
• IoT Edge modüllerin nasıl çalıştığını öğrendiğinize göre IoT Edge modülleri geliştirmeye yönelik gereksinimler ve araçlar hakkında bilgi edineceksiniz.