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

İleti zenginleştirmeleri , Azure IoT Hub'ın 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 eklemektir. Örneğin, cihaz iletilerini bir cihaz ikizi etiketiyle zenginleştirmek, bu bilgiler için cihaz ikizi API çağrıları yapmak için 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ın nasıl oluşturulacağını ve iletilerin diğer Azure hizmetlerine nasıl yönlendirdiğini gördünüz. Bu öğreticide, IoT hub'ına yönelik ileti zenginleştirmelerini test etmek için gereken ek kaynakların nasıl oluşturulacağını ve yapılandıracağını göreceksiniz. 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 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.

Önkoş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önlendirmesini kullanarak cihaz verilerini Azure Depolama'ya gönderme ve bunun için oluşturduğunuz kaynakların bakımını yapmış 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 protokollerini 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'a (MQTT) Bağlanma.

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'yı 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 . Docker kapsayıcısında Azure CLI'yi ç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ında 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ı enrichedadlandı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ı istiyoruz. 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 kaynaklar için 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.

Önemli

Bu makale, paylaşılan erişim imzası kullanarak hizmete bağlanma adımlarını içerir. Bu kimlik doğrulama yöntemi test ve değerlendirme için uygundur, ancak Microsoft Entra ID veya yönetilen kimliklerle bir hizmette kimlik doğrulaması yapmak daha güvenli bir yaklaşımdır. Daha fazla bilgi edinmek için bkz . En iyi güvenlik yöntemleri > Bulut güvenliği.

Azure portalı

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

2. Hub 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	Value
   Uç nokta türü	Depolama’yı seçin.
   Uç nokta adı	ContosoStorageEndpointEnriched girin.
   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'yi 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	Value
   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 message-endpoint create komutunu kullanın.

   az iot hub message-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --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 message-route create komutunu kullanın.

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type 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 ekle 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:

   Veri Akışı Adı	Değer
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (cihaz ikizi bir konum etiketine sahip olduğunu varsayar)
   customerID	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 ayarlanmıştır. Cihaz ikizi için konum etiketi eklemek istemiyorsanız öğreticiye devam etmek için İleti zenginleştirmelerini test et bölümüne atlayabilirsiniz.

Cihaz ikizi için konum etiketi ekleme

IoT hub'ınızda yapılandırılan ileti zenginleştirmelerinden biri, aşağıdaki cihaz ikizi yolu tarafından belirlenen değeriyle deviceLocation anahtarını belirtir: $twin.tags.location. Cihaz ikizinizin konum etiketi yoksa, ikiz yolu, $twin.tags.locationileti zenginleştirmelerinde DeviceLocation anahtarı için bir dize olarak damgalanır.

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

Azure portalı

1. Azure portalında 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. Ardından 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 ikizindeki güncelleştirmelerin ileti zenginleştirme değerlerine yansıtılması bu kadar sürebilir.

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

İleti zenginleştirmelerini test etme

ContosoStorageEndpointEnriched uç noktası için ileti zenginleştirmeleri 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ştirilecek ve zenginleştirilmiş depolama kapsayıcısında depolanacaktı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öre /iot-hub/Tutorials/Routing/SimulatedDevice/ gidin.

2. Daha önce güncelleştirdiğiniz değişken tanımları geçerli olmaya devam etmeli ancak değilse bunları dosyada Program.cs düzenlemelisiniz:

   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ı kaydedip kapatın

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

   dotnet run
   

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

1. Azure portalda 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ı iletilerde ileti zenginleştirmeleri iletilere eklenir. Daha önce oluşturduğunuz kapsayıcıdaki iletilerde zenginleştirme içermeyen ham iletiler bulunur. En alta gelene kadar zenginleştirilmiş kapsayıcıda detaya gidin ve en son ileti dosyasını açın. Ardından diğer kapsayıcı için de aynı işlemi gerçekleştirerek birinin zenginleştirildiğini ve zenginleştirilip zenginleştirilenin olmadığını doğrulayın.

Zenginleştirilmiş iletilere baktığınızda, hub adı, konum ve müşteri kimliğiyle ş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ında, 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, IoT Hub iletileri için ileti zenginleştirmelerini bir uç noktaya yönlendirildikçe 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