Öğretici: Bir arka uç hizmetinden cihazlarınızı yapılandırma

Cihazlarınızdan telemetri almanın yanı sıra cihazlarınızı arka uç hizmetinizden yapılandırmak isteyebilirsiniz. Cihazlarınıza bir istenen yapılandırma gönderdiğinizde bu cihazlardan durum ve uyumluluk güncelleştirmeleri almak da isteyebilirsiniz. Örneğin, bir cihaz için hedef çalışma sıcaklığı aralığı ayarlayabilir veya cihazlarınızdan üretici yazılımı sürüm bilgileri toplayabilirsiniz.

Bir cihaz ile IoT hub arasında durum bilgilerini eşitlemek için cihaz ikizlerini kullanırsınız. Cihaz ikizi, belirli bir cihazla ilişkili olan ve IoT Hub tarafından bunları sorgulayabileceğiniz bulutta depolanan bir JSON belgesidir. Bir cihaz ikizi istenen özellikleri, bildirilen özellikleri ve etiketleri içerir. İstenen özellikler arka uç uygulaması tarafından ayarlanır ve bir cihaz tarafından okunur. Bildirilen özellikler bir cihaz tarafından ayarlanır ve bir arka uç uygulaması tarafından okunur. Etiketler bir arka uç uygulaması tarafından oluşturulur ve asla bir cihaza gönderilmez. Cihazlarınızı düzenlemek için etiketleri kullanırsınız. Bu öğreticide istenen ve bildirilen özellikleri kullanarak durum bilgilerini nasıl eşitleyebileceğiniz gösterilmiştir:

İkiz özeti

Bu öğreticide, aşağıdaki görevleri gerçekleştireceksiniz:

  • Bir IoT hub oluşturun ve kimlik kayıt defterine bir test cihazı ekleyin.
  • Durum bilgilerini simülasyon cihazınıza göndermek için istenen özellikleri kullanın.
  • Simülasyon cihazınızdan toplanan durum bilgilerini almak için bildirilen özellikleri kullanın.

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Önkoşullar

  • Azure Cloud Shell'Da Bash ortamını kullanın.

    Cloud Shell’i yeni bir pencerede başlatma

  • Dilerseniz CLI başvuru komutlarını çalıştırmak için Azure CLI’yi yükleyebilirsiniz.

    • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI ile oturum açın. Kimlik doğrulama işlemini tamamlamak için terminalinizde görüntülenen adımları izleyin. Ek oturum açma seçenekleri için bkz. Azure CLI ile oturum açma.

    • İstendiğinde, ilk kullanımda Azure CLI uzantılarını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma.

    • Yüklü sürümü ve bağımlı kitaplıkları bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

Bu hızlı başlangıçta çalıştırdığınız iki örnek uygulama, Node.js kullanılarak yazılır. Geliştirme makinenizde Node.js ile v10 arasındaki. x. x veya üzeri bir sürüm gerekir.

nodejs.org adresinden birden fazla platform için Node.js’yi indirebilirsiniz.

Aşağıdaki komutu kullanarak geliştirme makinenizde geçerli Node.js sürümünü doğrulayabilirsiniz:

node --version

https://github.com/Azure-Samples/azure-iot-samples-node/archive/master.zip adresinden örnek Node.js projesini indirin ve ZIP arşivini ayıklayın.

Güvenlik duvarınızdaki 8883 numaralı bağlantı noktasını açık olduğundan emin olun. Bu öğreticideki cihaz örneği, 8883 numaralı bağlantı noktası üzerinden iletişim kuran MQTT protokolünü kullanır. Bu bağlantı noktası, bazı kurumsal ve eğitim ağ ortamlarında engellenebilir. Bu sorunu geçici olarak çözmek için daha fazla bilgi ve IoT Hub bkz. bağlanma (MQTT).

Azure kaynakları ayarlama

Bu öğreticiyi tamamlayabilmeniz için Azure aboneliğinizin cihaz kimliği kayıt defterine cihaz eklenmiş bir IOT hub içermesi gerekir. Cihaz kimliği kayıt defterindeki giriş, bu öğreticide çalıştırdığınız simülasyon cihazının hub’ınıza bağlanmasına imkan tanır.

Aboneliğinizde zaten bir IoT Hub 'ı ayarlanmamışsa, aşağıdaki CLı betiği ile bir tane ayarlayabilirsiniz. Bu betikte IoT hub için tutorial-iot-hub adı kullanılır ve betiği çalıştırırken bu adı kendi benzersiz adınızla değiştirmeniz gerekir. Betik, kaynak grubunu ve hub’ı Orta ABD bölgesinde oluşturur ve bunu size daha yakın bir konum olacak şekilde değiştirebilirsiniz. Betik, IoT hub hizmetinizin arka uç örneğinde IoT hub’ınıza bağlanmak için kullanacağınız bağlantı dizesini döndürür:

hubname=tutorial-iot-hub
location=centralus

# Install the IoT extension if it's not already installed:
az extension add --name azure-iot

# Create a resource group:
az group create --name tutorial-iot-hub-rg --location $location

# Create your free-tier IoT Hub. You can only have one free IoT Hub per subscription.
az iot hub create --name $hubname --location $location --resource-group tutorial-iot-hub-rg --partition-count 2 --sku F1

# Make a note of the service connection string, you need it later:
az iot hub connection-string show --name $hubname --policy-name service -o table

Bu öğreticide MyTwinDevice adlı bir simülasyon cihazı kullanılır. Aşağıdaki betik bu cihazı kimlik kayıt defterinize ekler ve bunun bağlantı dizesini alır:

# Set the name of your IoT hub:
hubname=tutorial-iot-hub

# Create the device in the identity registry:
az iot hub device-identity create --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg

# Retrieve the device connection string, you need this later:
az iot hub device-identity connection-string show --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg -o table

Durum bilgilerini gönderme

Bir arka uç uygulamasından bir cihaza durum bilgilerini göndermek için istenen özellikleri kullanırsınız. Bu bölümde şunları nasıl yapabileceğinizi öğrenirsiniz:

  • Bir cihazda istenen özellikleri alma ve işleme.
  • İstenen özellikleri bir arka uç uygulamasından gönderme.

İstenen özellikleri alan simülasyon cihazı örnek kodunu görüntülemek için indirdiğiniz örnek Node.js projesinde iot-hub/Tutorials/DeviceTwins klasörüne gidin. Sonra SimulatedDevice.js dosyasını bir metin düzenleyicide açın.

Arka uç uygulamasından gönderilen istenen özellik değişikliklerine yanıt veren simülasyon cihazında çalışan kod aşağıdaki bölümlerde açıklanmıştır:

Cihaz ikizi nesnesini alma

Aşağıdaki kod bir cihaz bağlantı dizesi kullanarak IoT hub’ınıza bağlanır:

// Get the device connection string from a command line argument
var connectionString = process.argv[2];

Aşağıdaki kod istemci nesnesinden bir ikiz alır:

// Get the device twin
client.getTwin(function(err, twin) {
  if (err) {
    console.error(chalk.red('Could not get device twin'));
  } else {
    console.log(chalk.green('Device twin created'));

Örnek istenen özellikler

İstenen özelliklerinizi uygulamanız için uygun olacak şekilde dilediğiniz gibi yapılandırabilirsiniz. Bu örnekte fanOn adlı bir üst düzey özellik kullanılır ve geriye kalan özellikler ayrı components (bileşenler) olarak gruplandırılır. Aşağıdaki JSON kod parçacığı, Bu öğreticinin kullandığı istenen özelliklerin yapısını gösterir. JSON, istenen. JSON dosyasıdır.

{
  "fanOn": "true",
  "components": {
    "system": {
      "id": "17",
      "units": "farenheit",
      "firmwareVersion": "9.75"
    },
    "wifi" : { 
      "channel" : "6",
      "ssid": "my_network"
    },
    "climate" : {
      "minTemperature": "68",
      "maxTemperature": "76"
    }
  }
}

İşleyiciler oluşturma

İstenen özellik güncelleştirmeleri için JSON hiyerarşisinin farklı düzeylerindeki güncelleştirmelere yanıt veren işleyiciler oluşturabilirsiniz. Örneğin, bu işleyici bir arka uç uygulamasından cihaza gönderilen tüm özellik değişikliklerini algılar. Delta değişkeni, çözüm arka ucundan gönderilen istenen özellikleri içerir:

// Handle all desired property updates
twin.on('properties.desired', function(delta) {
    console.log(chalk.yellow('\nNew desired properties received in patch:'));

Aşağıdaki işleyici yalnızca fanOn istenen özelliğinde yapılan değişikliklere tepki verir:

// Handle changes to the fanOn desired property
twin.on('properties.desired.fanOn', function(fanOn) {
    console.log(chalk.green('\nSetting fan state to ' + fanOn));

    // Update the reported property after processing the desired property
    reportedPropertiesPatch.fanOn = fanOn ? fanOn : '{unknown}';
});

Birden çok özelliğe yönelik işleyiciler

Daha önce gösterilen örnek istenen özellikler JSON öğesinde components altındaki climate düğümü minTemperature ve maxTemperature şeklinde iki özellik içerir.

Bir cihazın yerel ikiz nesnesi istenen ve bildirilen özelliklerin eksiksiz bir kümesini depolar. Arka uçtan gönderilen delta, istenen özelliklerin yalnızca bir alt kümesini güncelleştirebilir. Aşağıdaki kod parçacığında, simülasyon cihazı minTemperature ve maxTemperature özelliklerinden yalnızca biri için güncelleştirme alırsa cihazı yapılandırmak üzere diğer değer için yerel ikizdeki değeri kullanır:

// Handle desired properties updates to the climate component
twin.on('properties.desired.components.climate', function(delta) {
    if (delta.minTemperature || delta.maxTemperature) {
      console.log(chalk.green('\nUpdating desired tempertures in climate component:'));
      console.log('Configuring minimum temperature: ' + twin.properties.desired.components.climate.minTemperature);
      console.log('Configuring maximum temperture: ' + twin.properties.desired.components.climate.maxTemperature);

      // Update the reported properties and send them to the hub
      reportedPropertiesPatch.minTemperature = twin.properties.desired.components.climate.minTemperature;
      reportedPropertiesPatch.maxTemperature = twin.properties.desired.components.climate.maxTemperature;
      sendReportedProperties();
    }
});

Yerel ikiz nesnesi istenen ve bildirilen özellikleri eksiksiz bir kümesini depolar. Arka uçtan gönderilen delta, istenen özelliklerin yalnızca bir alt kümesini güncelleştirebilir.

Ekleme, güncelleştirme ve silme işlemlerini işleme

Arka uçtan gönderilen istenen özellikler belirli bir istenen özellik üzerinde hangi işlemin gerçekleştirildiğini göstermez. Kodunuzun işlemi yerel olarak depolanan güncel istenen özellikler kümesinden ve hub’dan gönderilen değişikliklerden çıkarsaması gerekir.

Aşağıdaki kod parçacığında, simülasyon cihazının istenen özelliklerde components listesindeki ekleme, güncelleştirme ve silme işlemlerini nasıl işlediği gösterilmiştir. Bir bileşenin silinmesi gerektiğini belirtmek için nasıl null değerlerini kullanabileceğinizi görebilirsiniz:

// Keep track of all the components the device knows about
var componentList = {};

// Use this componentList list and compare it to the delta to infer
// if anything was added, deleted, or updated.
twin.on('properties.desired.components', function(delta) {
  if (delta === null) {
    componentList = {};
  }
  else {
    Object.keys(delta).forEach(function(key) {

      if (delta[key] === null && componentList[key]) {
        // The delta contains a null value, and the
        // device has a record of this component.
        // Must be a delete operation.
        console.log(chalk.green('\nDeleting component ' + key));
        delete componentList[key];

      } else if (delta[key]) {
        if (componentList[key]) {
          // The delta contains a component, and the
          // device has a record of it.
          // Must be an update operation.
          console.log(chalk.green('\nUpdating component ' + key + ':'));
          console.log(JSON.stringify(delta[key]));
          // Store the complete object instead of just the delta
          componentList[key] = twin.properties.desired.components[key];

        } else {
          // The delta contains a component, and the
          // device has no record of it.
          // Must be an add operation.
          console.log(chalk.green('\nAdding component ' + key + ':'));
          console.log(JSON.stringify(delta[key]));
          // Store the complete object instead of just the delta
          componentList[key] = twin.properties.desired.components[key];
        }
      }
    });
  }
});

Arka uçtan bir cihaza istenen özellikler gönderme

Bir cihazın istenen özellik güncelleştirmelerini almak için nasıl işleyici uyguladığını gördünüz. Bu bölümde, bir arka uç uygulamasından bir cihaza nasıl istenen özellik değişiklikleri gönderilebileceği gösterilmiştir.

İstenen özellikleri alan simülasyon cihazı örnek kodunu görüntülemek için indirdiğiniz örnek Node.js projesinde iot-hub/Tutorials/DeviceTwins klasörüne gidin. Sonra ServiceClient.js dosyasını bir metin düzenleyicide açın.

Aşağıdaki kod parçacığında cihaz kimliği kayıt defterine bağlanıp belirli bir cihazın ikizine nasıl erişilebileceği gösterilmiştir:

// Create a device identity registry object
var registry = Registry.fromConnectionString(connectionString);

// Get the device twin and send desired property update patches at intervals.
// Print the reported properties after some of the desired property updates.
registry.getTwin(deviceId, async (err, twin) => {
  if (err) {
    console.error(err.message);
  } else {
    console.log('Got device twin');

Aşağıdaki kod parçacığında arka uç uygulamasının cihaza gönderdiği farklı istenen özellik patches (düzeltme ekleri) gösterilmiştir:

// Turn the fan on
var twinPatchFanOn = {
  properties: {
    desired: {
      patchId: "Switch fan on",
      fanOn: "false",
    }
  }
};

// Set the maximum temperature for the climate component
var twinPatchSetMaxTemperature = {
  properties: {
    desired: {
      patchId: "Set maximum temperature",
      components: {
        climate: {
          maxTemperature: "92"
        }
      }
    }
  }
};

// Add a new component
var twinPatchAddWifiComponent = {
  properties: {
    desired: {
      patchId: "Add WiFi component",
      components: {
        wifi: { 
          channel: "6",
          ssid: "my_network"
        }
      }
    }
  }
};

// Update the WiFi component
var twinPatchUpdateWifiComponent = {
  properties: {
    desired: {
      patchId: "Update WiFi component",
      components: {
        wifi: { 
          channel: "13",
          ssid: "my_other_network"
        }
      }
    }
  }
};

// Delete the WiFi component
var twinPatchDeleteWifiComponent = {
  properties: {
    desired: {
      patchId: "Delete WiFi component",
      components: {
        wifi: null
      }
    }
  }
};

Aşağıdaki kod parçacığında arka uç uygulamasının bir cihaza nasıl istenen özellik güncelleştirmesi gönderdiği gösterilmiştir:

// Send a desired property update patch
async function sendDesiredProperties(twin, patch) {
  twin.update(patch, (err, twin) => {
    if (err) {
      console.error(err.message);
    } else {
      console.log(chalk.green(`\nSent ${twin.properties.desired.patchId} patch:`));
      console.log(JSON.stringify(patch, null, 2));
    }
  });
}

Uygulamaları çalıştırma

Bu bölümde, bir arka uç uygulamasının bir simülasyon cihazı uygulamasına istenen özellik güncelleştirmeleri gönderişini izlemek için iki örnek uygulama çalıştırırsınız.

Simülasyon cihazını ve arka uç uygulamalarını çalıştırmak için cihaz ve hizmet bağlantı dizelerine sahip olmanız gerekir. Bu öğreticinin başlangıcında kaynakları oluştururken bağlantı dizelerini not almıştınız.

Simülasyon cihazı uygulamasını çalıştırmak için bir kabuk veya komut istemi penceresi açın ve indirdiğiniz Node.js projesinin iot-hub/Tutorials/DeviceTwins klasörüne gidin. Sonra aşağıdaki komutları çalıştırın:

npm install
node SimulatedDevice.js "{your device connection string}"

Arka uç uygulamasını çalıştırmak için başka bir kabuk veya komut istemi penceresi açın. Sonra indirdiğiniz Node.js projesindeki iot-hub/Tutorials/DeviceTwins klasörüne gidin. Sonra aşağıdaki komutları çalıştırın:

npm install
node ServiceClient.js "{your service connection string}"

Aşağıdaki ekran görüntüsünde simülasyon cihazı uygulamasından alınan çıkış gösterilmiş ve uygulamanın maxTemperature istenen özelliğine yönelik bir güncelleştirmeyi nasıl işlediği vurgulanmıştır. Her iki üst düzey işleyicinin ve iklim bileşeni işleyicilerinin nasıl çalıştığını görebilirsiniz:

En üst düzey işleyicinin ve İklim bileşen işleyicilerinin nasıl çalışacağını gösteren ekran görüntüsü.

Aşağıdaki ekran görüntüsünde arka uç uygulamasından alınan çıkış gösterilmiş ve uygulamanın maxTemperature istenen özelliğine yönelik bir güncelleştirmeyi nasıl gönderdiği vurgulanmıştır:

Arka uç uygulamasındaki çıktıyı gösteren ve nasıl bir güncelleştirme gönderdiğini vurgulayan ekran görüntüsü.

<a name="receive-state-information">Durum bilgilerini alma

Arka uç uygulamanız durum bilgilerini bir cihazdan bildirilen özellikler olarak alır. Bir cihaz, bildirilen özellikleri ayarlar ve hub’ınıza gönderir. Bir arka uç uygulaması, hub'ınızda depolanan cihaz ikizinden bildirilen özelliklerin geçerli değerlerini okuyabilir.

Bir cihazdan bildirilen özellikler gönderme

Bildirilen özellik değerlerine düzeltme eki olarak güncelleştirmeler gönderebilirsiniz. Aşağıdaki kod parçacığında simülasyon cihazının gönderdiği düzeltme eki için bir şablon gösterilmiştir. Simülasyon cihazı hub’a göndermeden önce düzeltme ekinin alanlarını güncelleştirir:

[!code-javascript[Reported properties patches](~/iot-samples-node/iot-hub/Tutorials/DeviceTwins/SimulatedDevice.js?name=reportedpatch&highlight=2 "Reported properties patches")]

Simülasyon cihazı bildirilen özellikleri içeren düzeltme ekini hub’a göndermek için aşağıdaki işlevi kullanır:

// Send the reported properties patch to the hub
function sendReportedProperties() {
  twin.properties.reported.update(reportedPropertiesPatch, function(err) {
    if (err) throw err;
    console.log(chalk.blue('\nTwin state reported'));
    console.log(JSON.stringify(reportedPropertiesPatch, null, 2));
  });
}

Bildirilen özellikleri işleme

Bir arka uç uygulaması cihaz ikizi aracılığıyla bir cihazın geçerli bildirilen özellik değerlerine erişir. Aşağıdaki kod parçacığında arka uç uygulamasının sanal cihaz için bildirilen özellik değerlerini nasıl okuduğu gösterilmiştir:

// Display the reported properties from the device
function printReportedProperties(twin) {
  console.log("Last received patch: " + twin.properties.reported.lastPatchReceivedId);
  console.log("Firmware version: " + twin.properties.reported.firmwareVersion);
  console.log("Fan status: " + twin.properties.reported.fanOn);
  console.log("Min temperature set: " + twin.properties.reported.minTemperature);
  console.log("Max temperature set: " + twin.properties.reported.maxTemperature);
}

Uygulamaları çalıştırma

Bu bölümde, bir simülasyon cihazı uygulamasının bir arka uç uygulamasına bildirilen özellik güncelleştirmeleri gönderişini izlemek için iki örnek uygulama çalıştırırsınız.

İstenen özelliklerin bir cihaza nasıl gönderildiğini görmek için çalıştırdığınız iki örnek uygulamayı çalıştırırsınız.

Simülasyon cihazını ve arka uç uygulamalarını çalıştırmak için cihaz ve hizmet bağlantı dizelerine sahip olmanız gerekir. Bu öğreticinin başlangıcında kaynakları oluştururken bağlantı dizelerini not almıştınız.

Simülasyon cihazı uygulamasını çalıştırmak için bir kabuk veya komut istemi penceresi açın ve indirdiğiniz Node.js projesinin iot-hub/Tutorials/DeviceTwins klasörüne gidin. Sonra aşağıdaki komutları çalıştırın:

npm install
node SimulatedDevice.js "{your device connection string}"

Arka uç uygulamasını çalıştırmak için başka bir kabuk veya komut istemi penceresi açın. Sonra indirdiğiniz Node.js projesindeki iot-hub/Tutorials/DeviceTwins klasörüne gidin. Sonra aşağıdaki komutları çalıştırın:

npm install
node ServiceClient.js "{your service connection string}"

Aşağıdaki ekran görüntüsünde simülasyon cihazı uygulamasından alınan çıkış gösterilmiş ve uygulamanın hub’ınıza nasıl bir bildirilen özellik güncelleştirmesi gönderdiği vurgulanmıştır:

Sanal cihaz

Aşağıdaki ekran görüntüsünde, arka uç uygulamasından gelen çıktı ve cihazın raporlanan özellik güncelleştirmesini nasıl aldığı ve işleyeni vurgulanır:

Arka uç uygulaması

Kaynakları temizleme

Sonraki öğreticiyi tamamlamayı planlıyorsanız, kaynak grubunu ve IoT hub’ı değiştirmeden bırakın ve sonra bunları yeniden kullanın.

Artık gerekli değilse portaldan IoT hub’ı ve kaynak grubunu silin. Bunu yapmak için, IoT hub’ınızı içeren tutorial-iot-hub-rg kaynak grubunu seçin ve Sil’e tıklayın.

Alternatif olarak, CLI kullanın:

# Delete your resource group and its contents
az group delete --name tutorial-iot-hub-rg

Sonraki adımlar

Bu öğreticide, cihazınız ile IoT hub’ınız arasında durum bilgilerini nasıl eşitleyebileceğinizi öğrendiniz. Cihaz güncelleştirme işlemini uygulamak için cihaz ikizlerini kullanmayı öğrenmek için sonraki öğreticiye ilerleyin.

Raspberry Pi 3 B+ başvuruAzure IoT Hub öğreticisi için bir cihaz güncelleştirmesi uygulama.