Öğretici: Azure IoT Hub ileti zenginleştirmelerini kullanma

İleti zenginleştirmeleri, Azure IoT Hub iletileri belirlenen uç noktaya gönderilmeden önce ek bilgilerle damgalama özelliğidir. İleti zenginleştirmelerini kullanmanın bir nedeni, aşağı akış işlemeyi basitleştirmek için kullanılabilecek verileri dahil etmektir. Örneğin, cihaz iletilerini bir cihaz ikizi etiketiyle zenginleştirmek, bu bilgiler için cihaz ikizi API çağrıları yapmak üzere müşterilerin yükünü azaltabilir. Daha fazla bilgi için bkz. İleti zenginleştirmelerine genel bakış.

Bu öğreticinin ilk bölümünde özel uç noktalar oluşturmayı ve iletileri diğer Azure hizmetlerine yönlendirmeyi öğrendiniz. Bu öğreticide, IoT hub'ında ileti zenginleştirmelerini test etmek için gereken ek kaynakları oluşturmayı ve yapılandırmayı öğreneceksiniz. Kaynaklar, zenginleştirilmiş iletileri tutmak için mevcut bir depolama hesabı (öğreticinin ilk bölümünde oluşturulmuş) için ikinci bir depolama kapsayıcısı ve bunları oraya göndermek için bir ileti yolu içerir. İleti yönlendirme ve ileti zenginleştirmeleri için yapılandırmalar tamamlandıktan sonra, IoT hub'ına ileti göndermek için bir uygulama kullanırsınız. Hub daha sonra bunları her iki depolama kapsayıcısına da yönlendirir. Yalnızca zenginleştirilmiş depolama kapsayıcısı için uç noktaya gönderilen iletiler zenginleştirilmiş olur.

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

• Depolama hesabınızda ikinci bir kapsayıcı oluşturun.
• Başka bir özel uç nokta oluşturun ve iletileri IoT hub'ından bu uç noktaya yönlendirin.
• Yeni uç noktaya yönlendirilen ileti zenginleştirmelerini yapılandırın.
• Hub'a ileti gönderen bir IoT cihazının simülasyonunu oluşturan bir uygulama çalıştırın.
• Sonuçları görüntüleyin ve ileti zenginleştirmelerinin hedeflenen iletilere uygulandığını doğrulayın.

Ön koşullar

• Bir Azure aboneliğiniz olmalıdır. Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

• Öğretici: IoT Hub ileti yönlendirmeyi kullanarak cihaz verilerini Azure Depolama'ya gönderme işlemini tamamlamış ve bunun için oluşturduğunuz kaynakları korumuş olmanız gerekir.

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

Azure portalı

Azure portal için başka önkoşul yoktur.

Azure CLI

• Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz. Azure Cloud Shell'de Bash için Hızlı Başlangıç.

  

• CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız Azure CLI'yi yükleyin . Windows veya macOS üzerinde çalışıyorsanız Azure CLI’yi bir Docker kapsayıcısında çalıştırmayı değerlendirin. Daha fazla bilgi için bkz. Azure CLI'yi Docker kapsayıcısında çalıştırma.

  • 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. Diğer oturum açma seçenekleri için bkz. Azure CLI ile oturum açma.

  • İstendiğinde, ilk kullanımda Azure CLI uzantısı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.

Depolama hesabınızda ikinci bir kapsayıcı oluşturma

Bu öğreticinin ilk bölümünde , yönlendirilen iletiler için bir depolama hesabı ve kapsayıcı oluşturdunuz. Şimdi zenginleştirilmiş iletiler için ikinci bir kapsayıcı oluşturmanız gerekir.

Azure portalı

1. Azure portal Depolama hesapları'nı arayın.

2. Daha önce oluşturduğunuz hesabı seçin.

3. Depolama hesabı menüsünde Veri depolama bölümünde Kapsayıcılar'ı seçin.

4. Yeni kapsayıcıyı oluşturmak için Kapsayıcı'ya tıklayın.

   

5. Kapsayıcıyı enrichedolarak adlandırın ve Oluştur'u seçin.

Azure CLI

İpucu

Bu öğretici boyunca kullanılan CLI komutlarının çoğu aynı parametreleri kullanır. Size kolaylık sağlamak için gerektiğinde çağrılabilecek yerel değişkenleri tanımlamanızı öneririz. Tüm komutları aynı oturumda çalıştırdığınızdan emin olun, aksi takdirde değişkenleri yeniden tanımlamanız gerekir.

Bu değişkenlerin değerleri, bu öğreticinin ilk bölümünde kullandığınız kaynaklara yönelik olmalıdır.

1. IoT hub'ınız, depolama hesabınız ve kapsayıcınız için değişkenleri tanımlayın.

   GROUP_NAME: Bu yer tutucuyu IoT hub'ınızı içeren kaynak grubunun adıyla değiştirin.

   IOTHUB_NAME: Bu yer tutucuyu IoT hub'ınızın adıyla değiştirin.

   DEVICE_ID: Bu yer tutucuyu cihazınızın kimliğiyle değiştirin.

   STORAGE_NAME: Bu yer tutucuyu depolama hesabınızın adıyla değiştirin.

   Bu öğreticide değişkeninin containerName değeri zenginleştirilmelidir.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. Kapsayıcıyı depolama hesabınıza eklemek için az storage container create komutunu kullanın.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

İletileri ikinci bir uç noktaya yönlendirme

Zenginleştirilmiş iletiler için ikinci bir uç nokta ve yol oluşturun.

Azure portalı

1. Azure portal IoT hub'ınıza gidin.

2. Merkez ayarları'nın altındaki kaynak menüsünde İleti yönlendirme'yi ve ardından Ekle'yi seçin.

   

3. Uç Nokta sekmesinde, aşağıdaki bilgileri sağlayarak bir Depolama uç noktası oluşturun:

   Parametre	Değer
   Uç nokta türü	Depolama’yı seçin.
   Uç nokta adı	ContosoStorageEndpointEnriched yazın.
   Azure Depolama kapsayıcısı	Kapsayıcı seçin'i seçin. Önceki bölümde oluşturduğunuz depolama hesabını ve zenginleştirilmiş kapsayıcıyı seçmek için istemleri izleyin.
   Kodlama	JSON'ı seçin. Bu alan griyse depolama hesabı bölgeniz JSON'u desteklemez. Bu durumda varsayılan AVRO ile devam edin.

   

4. Parametrelerin geri kalanı için varsayılan değerleri kabul edin ve Oluştur + İleri'yi seçin.

5. Depolama uç noktasını eklediğinize göre yeni yolu oluşturmaya devam edin. Yeni yol için aşağıdaki bilgileri sağlayın:

   Parametre	Değer
   Ad	ContosoStorageRouteEnriched
   Veri kaynağı	Açılan listeden Cihaz Telemetri İletileri'nin seçili olduğunu doğrulayın.
   Yolu etkinleştir	Bu alanın olarak enabledayarlandığını doğrulayın.
   Yönlendirme sorgusu	Sorgu dizesi olarak girin level="storage" .

   

6. Oluştur + zenginleştirme ekle'yi seçin.

Azure CLI

1. Uç nokta ve yol komutlarının değişkenlerini sırasıyla ContosoStorageEndpointEnriched ve ContosoStorageRouteEnriched değerlerini kullanacak şekilde yapılandırın.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Önceki bölümde yaptığınız depolama kapsayıcısına işaret eden özel bir uç nokta oluşturmak için az iot hub routing-endpoint create komutunu kullanın.

   az iot hub routing-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --endpoint-resource-group $resourceGroup \
     --endpoint-subscription-id $(az account show --query id -o tsv) \
     --endpoint-type azurestoragecontainer
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Herhangi bir iletiyi level=storage depolama kapsayıcısı uç noktasına geçiren bir yol oluşturmak için az iot hub route create komutunu kullanın.

   az iot hub route create \
     --name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Yeni uç noktaya ileti zenginleştirmesi ekleme

Zenginleştirilmiş depolama kapsayıcısına yönlendirilecek üç ileti zenginleştirmesi oluşturun.

Azure portalı

1. Yol ekleme sihirbazının Zenginleştirme sekmesinde, zenginleştirilmiş adlı depolama kapsayıcısının uç noktasına giden iletiler için üç ileti zenginleştirmesi ekleyin.

   Bu değerleri ContosoStorageEndpointEnriched uç noktası için ileti zenginleştirmeleri olarak ekleyin:

   Name	Değer
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (cihaz ikizi bir konum etiketine sahip olduğunu varsayar)
   Customerıd	6ce345b8-1e4a-411e-9398-d34587459a3a

   İşiniz bittiğinde zenginleştirmeleriniz şu görüntüye benzer görünmelidir:

   

2. İleti zenginleştirmelerini eklemek için Ekle'yi seçin.

Azure CLI

Daha önce oluşturulan uç noktaya giden yola ileti zenginleştirmeleri eklemek için az iot hub message-enrichment create komutuna üç çağrı yapın.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

Artık zenginleştirilmiş iletiler için oluşturduğunuz uç noktaya yönlendirilen tüm iletiler için ileti zenginleştirmeleri ayarlandı. Cihaz ikizine konum etiketi eklemek istemiyorsanız öğreticiye devam etmek için İleti zenginleştirmelerini test etme bölümüne atlayabilirsiniz.

Cihaz ikizine konum etiketi ekleme

IoT hub'ınız üzerinde yapılandırılan ileti zenginleştirmelerinden biri , deviceLocation anahtarının değerini şu cihaz ikizi yolu tarafından belirlenen değerle belirtir: $twin.tags.location. Cihaz ikizinizin konum etiketi yoksa, ileti zenginleştirmelerinde ikizi yolu $twin.tags.location, DeviceLocation anahtarı için bir dize olarak damgalanır.

Cihazınızın ikizi için bir konum etiketi eklemek için şu adımları izleyin:

Azure portalı

1. Azure portal IoT hub'ınıza gidin.

2. IoT hub'ının gezinti menüsünde Cihazlar'ı ve ardından cihazınızı seçin.

3. Cihaz sayfasının üst kısmındaki Cihaz ikizi sekmesini seçin ve cihaz ikizi altındaki kapanış ayracından hemen önce aşağıdaki satırı ekleyin. Sonra Kaydet'i seçin.

     , "tags": {"location": "Plant 43"}
   

   

Azure CLI

Cihaz ikizini yeni bir etiket anahtarı ve değeriyle güncelleştirmek için az iot hub device-twin update komutunu kullanın.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

İpucu

Sonraki bölüme geçmeden önce yaklaşık beş dakika bekleyin. Cihaz ikizi güncelleştirmelerinin ileti zenginleştirme değerlerine yansıtılması bu kadar sürebilir.

Cihaz ikizi yollarının ileti zenginleştirmeleriyle nasıl işlenmeleri hakkında daha fazla bilgi edinmek için bkz. İleti zenginleştirme sınırlamaları. Cihaz ikizleri hakkında daha fazla bilgi edinmek için bkz. IoT Hub'de cihaz ikizlerini anlama ve kullanma.

İleti zenginleştirmelerini test etme

İleti zenginleştirmeleri ContosoStorageEndpointEnriched uç noktası için yapılandırıldığına göre, IoT hub'ına ileti göndermek için sanal cihaz uygulamasını çalıştırın. Bu noktada, ileti yönlendirme aşağıdaki gibi ayarlanmıştır:

• Öğreticinin ilk bölümünde oluşturduğunuz depolama uç noktasına yönlendirilen iletiler zenginleştirilmeyecek ve daha sonra oluşturduğunuz depolama kapsayıcısında depolanacaktır.

• ContosoStorageEndpointEnriched depolama uç noktasına yönlendirilen iletiler zenginleştirilir ve zenginleştirilmiş depolama kapsayıcısında depolanır.

Bu öğreticinin ilk bölümünden SimulatedDevice konsol uygulamasını hala çalıştırmıyorsanız yeniden çalıştırın:

İpucu

Bu öğretici için Azure CLI adımlarını izliyorsanız örnek kodu ayrı bir oturumda çalıştırın. Bu şekilde, CLI adımlarının geri kalanını izlerken örnek kodun çalışmaya devam etmesi için izin vekleyebilirsiniz.

1. Örnek klasörde klasörüne /iot-hub/Tutorials/Routing/SimulatedDevice/ gidin.

2. Daha önce güncelleştirdiğiniz değişken tanımları hala geçerli olmalıdır, ancak geçerli değilse bunları dosyada Program.cs düzenleyin:

   1. Program sınıfının en üstünde değişken tanımlarını bulun. Aşağıdaki değişkenleri kendi bilgilerinizle güncelleştirin:

      • s_myDeviceId: Cihazı IoT hub'ınıza kaydederken atadığınız cihaz kimliği.
      • s_iotHubUri: Biçimini IOTHUB_NAME.azure-devices.netalan IoT hub'ınızın ana bilgisayar adı.
      • s_deviceKey: Cihaz kimliği bilgilerinde bulunan cihaz birincil anahtarı.

   2. Dosyayı kaydedin ve kapatın.

3. Örnek kodu çalıştırın:

   dotnet run
   

Konsol uygulamasından birkaç dakika boyunca çalışacak şekilde çıktıktan sonra verileri görüntüleyin:

1. Azure portalında depolama hesabınıza gidin.

2. Gezinti menüsünden Depolama tarayıcısı'nı seçin. Bu öğreticiler boyunca oluşturduğunuz iki kapsayıcıyı görmek için Blob kapsayıcıları'nı seçin.

   

Kapsayıcıdaki zenginleştirilmiş adlı iletiler, ileti zenginleştirmelerine sahiptir. Daha önce oluşturduğunuz kapsayıcıdaki iletiler, zenginleştirme içermeyen ham iletilere sahiptir. En alta gelene kadar zenginleştirilmiş kapsayıcıda detaya gidin ve ardından en son ileti dosyasını açın. Ardından bir kapsayıcının zenginleştirildiğini ve zenginleştirildiğini doğrulamak için diğer kapsayıcı için de aynı işlemi yapın.

Zenginleştirilmiş iletilere baktığınızda hub adı, konum ve müşteri kimliği ile şunu görmeniz "myIotHub" gerekir:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Kaynakları temizleme

Bu öğreticinin her iki bölümünde oluşturduğunuz tüm kaynakları kaldırmak için kaynak grubunu silin. Bu eylem grubun içerdiği tüm kaynakları siler. Kaynak grubunun tamamını silmek istemiyorsanız, silmek için içindeki kaynakları tek tek seçebilirsiniz.

Azure portalı

1. Azure portal, bu öğreticinin IoT hub'ını ve depolama hesabını içeren kaynak grubuna gidin.
2. Hangilerini temizlemek istediğinizi belirlemek için kaynak grubundaki tüm kaynakları gözden geçirin.
   • Tüm kaynağı silmek istiyorsanız Kaynak grubunu sil'i seçin.
   • Yalnızca belirli bir kaynağı silmek istiyorsanız, silmek istediklerinizi seçmek için her kaynak adının yanındaki onay kutularını kullanın. Ardından Sil’i seçin.

Azure CLI

1. Kaynak grubunuzdaki tüm kaynakları görüntülemek için az resource list komutunu kullanın.

   az resource list --resource-group $resourceGroup --output table
   

2. Hangilerini temizlemek istediğinizi belirlemek için kaynak grubundaki tüm kaynakları gözden geçirin.

   • Tüm kaynakları silmek istiyorsanız az group delete komutunu kullanın.

     az group delete --name $resourceGroup
     

   • Yalnızca belirli kaynakları silmek istiyorsanız az resource delete komutunu kullanın. Örneğin:

     az resource delete --resource-group $resourceGroup --name $storageName
     

Sonraki adımlar

Bu öğreticide, bir uç noktaya yönlendirilen IoT Hub iletileri için ileti zenginleştirmelerini yapılandırıp test ettiniz.

İleti zenginleştirmeleri hakkında daha fazla bilgi için bkz. İleti zenginleştirmelerine genel bakış.

IoT Hub hakkında daha fazla bilgi edinmek için sonraki öğreticiye geçin.

Öğretici: IoT hub'ı ile ölçümleri ve günlükleri ayarlama ve kullanma