Veri akışları için WASM modülleri oluşturma

Azure IoT İşlemleri'daki özel WebAssembly (WASM) veri işleme özelliği, Azure IoT İşlemleri kümenizde gerçek zamanlı telemetri verileri işlemeye olanak tanır. Özel WASM modülleri dağıtarak veri akış grafınızın, HTTP/REST bağlayıcısının veya MQTT bağlayıcısının bir parçası olarak veri dönüştürmeleri tanımlayabilir ve yürütebilirsiniz.

Bu makalede, WASM modüllerinizi Azure IoT İşlemleri kümenize dağıtmadan önce yerel olarak geliştirmek ve test etmek için ortamınızda yüklü Azure IoT İşlemleri Veri Akışı VS Code uzantısı, dataflow-dev CLI veya standart araçların nasıl kullanılacağı açıklanır. Nasıl yapılacağını öğreneceksiniz:

  • Temel iş akışını anlamak için örnek verilerle önceden oluşturulmuş bir graf yürüterek bir grafik uygulamasını yerel olarak çalıştırın.
  • Harita ve filtre işlevselliğiyle Python ve Rust'ta yeni işleçler oluşturarak özel WASM modülleri oluşturun.

İşleçler ve grafikler oluştururken bir iç geliştirme döngüsü için VS Code uzantısını kullanın; örneğin: kod yazma, derleme, hataları gözden geçirme, hata ayıklama, değişiklik yapma, grafı güncelleştirme ve yayımlama.

dataflow-dev CI/CD odaklı graf kalitesi iş akışları için CLI'yı kullanın; örneğin: mevcut kodu derleyin, grafiği çalıştırın, bilinen iyi sonuçlara karşı çıkışı test edin ve zaman içinde kaliteyi izleyin.

Derleme ve test süreci üzerinde daha fazla denetim sahibi olmak istediğiniz senaryolar veya diğer geliştirme araçları ve iş akışlarıyla tümleştirmeniz gerektiğinde ortamınızda yüklü olan standart araçları kullanın.

Bu makalede WASM modüllerinizi yerel olarak derleme ve test etme işlemleri açıklanmaktadır. Bunları Azure IoT İşlemleri veri akışlarında ve bağlayıcılarda kullanmak için bunları Azure IoT İşlemleri kümenize dağıtmanız ve graf veya bağlayıcı yapılandırmanızda bunlara başvurmanız gerekir:

Daha gelişmiş senaryolar için bkz . Durum deposuyla durum bilgisi olan WASM grafikleri oluşturma, WASM modülleriyle şema kayıt defteri kullanma, WASM modüllerinde hata ayıklama ve WASM modüllerini test edin.

Uzantı ve CLI aracı aşağıdaki platformlarda desteklenir:

  • Linux
  • Linux için Windows Alt Sistemi (WSL)
  • Windows (Windows uzantı komutlarını çalıştırırken PowerShell veya Komut İstemi gibi bir Windows kabuğu kullandığınızdan emin olun)

Azure IoT İşlemleri'de grafikler ve WASM hakkında daha fazla bilgi edinmek için bkz:

Önkoşullar

Geliştirme ortamı:

Docker görüntüleri:

docker pull mcr.microsoft.com/azureiotoperations/processor-app:1.1.8
docker tag mcr.microsoft.com/azureiotoperations/processor-app:1.1.8 host-app

docker pull mcr.microsoft.com/azureiotoperations/devx-runtime:0.1.10
docker tag mcr.microsoft.com/azureiotoperations/devx-runtime:0.1.10 devx

docker pull mcr.microsoft.com/azureiotoperations/statestore-cli:0.0.3
docker tag mcr.microsoft.com/azureiotoperations/statestore-cli:0.0.3 statestore-cli

docker pull eclipse-mosquitto

Grafik uygulamasını yerel olarak çalıştırma

Bu örnekte, VS Code uzantısını kullanarak yerel olarak graf uygulaması oluşturmak ve çalıştırmak için gerekli tüm kaynakları içeren örnek bir çalışma alanı kullanılmaktadır.

Örnek çalışma alanını VS Code'da açma

Henüz yapmadıysanız Explore IoT İşlemleri deposunu kopyalayın.

Visual Studio Code'da samples/wasm klasörünü açmak için Dosya > Klasör Aç'yı seçin ve samples/wasm klasörüne gidin.

İşleçleri oluşturma

Ctrl+Shift+P tuşlarına basarak komut paletini açın ve Azure IoT İşlemleri: Tüm İşleçleri Derle araması yapın. Derleme modu olarak Sürüm'ü seçin.

Bu komut, çalışma alanındaki tüm operatörleri oluşturur ve .wasm dosyalarını operators klasöründe oluşturur. .wasm dosyalarını grafik uygulamasını yerel olarak çalıştırmak için kullanırsınız.

Grafik uygulamasını yerel olarak çalıştırma

Yerel yürütme ortamını başlatmak için Ctrl+Shift+P tuşlarına basarak komut paletini açın ve Azure IoT İşlemleri: Geliştirme Ortamını Başlat araması yapın. Çalıştırma modu olarak yayın'ı seçin.

Yerel yürütme ortamı çalışırken Ctrl+Shift+P tuşlarına basarak komut paletini açın ve Azure IoT İşlemleri: Application Graph öğesini arayın. Çalıştırma modu olarak yayın'ı seçin. Bu komut, çalışma alanında dosyayla graph.dataflow.yaml yerel yürütme ortamını kullanarak grafik uygulamasını yerel olarak çalıştırır.

hostapp.env.list'den okuyarak veri akışı operatörü yapılandırma parametreleri için ortam değişkeni TK_CONFIGURATION_PARAMETERS'i ayarlar.

Giriş verileri istendiğinde çalışma alanında klasörü seçin data-and-images . Bu klasör, sıcaklık ve nem verileri ve anlık görüntü modülü için bazı görüntüler de dahil olmak üzere grafik uygulaması için giriş veri dosyalarını içerir.

Günlüklerin hazır olduğuna ilişkin bir VS Code bildirimi görene kadar bekleyin: Log files for the run can be found at ...\wasm\data-and-images\output\logs.

Çıkış, output klasörünün altındaki data-and-images klasöründe bulunur. Çıktı dosyalarını görmek için çalışma alanında klasörü açabilirsiniz output . .txt Dosya adının tarih ve saatini içeren dosya, işlenen verileri içerir ve aşağıdaki örneğe benzer:

{"tst":"2025-09-19T04:19:13.530381+0000","topic":"sensors","qos":0,"retain":0,"payloadlen":312,"properties":{"payload-format-indicator":1,"message-expiry-interval":10,"correlation-data":"...","user-properties":{"__ts":"001758255553528:00000:...","__protVer":"1.0","__srcId":"mqtt-source"},"content-type":"application/json"},"payload":{"temperature":[{"count":2,"max":653.888888888889,"min":204.44444444444449,"average":429.16666666666669,"last":204.44444444444449,"unit":"C","overtemp":true}],"humidity":[{"count":3,"max":85,"min":45,"average":69.666666666666671,"last":79}],"object":[{"result":"notebook, notebook computer; sliding door"}]}}

Çıkış, graf uygulamasının giriş verilerini işlediğini ve çıkışı oluşturduğunu gösterir. Çıkış, sıcaklık ve nem verilerini ve görüntülerde algılanan nesneleri içerir.

Özel WASM modülleriyle yeni grafik oluşturma

Bu senaryoda, özel WASM modülleriyle yeni bir graf uygulamasının nasıl oluşturulacağı gösterilir. Graf uygulaması iki işleçten oluşur: map Sıcaklık değerlerini Fahrenheit'ten Santigrat'a dönüştüren bir operatör ve sıcaklık değerleri 500°C'nin üzerinde olan iletileri filtreleyen bir filter operatör.

Şu anda işleç adlarında kısa çizgi (-) veya alt çizgi (_) kullanmayın. VS Code uzantısı bu gereksinimi zorunlu bırakır, ancak modülleri el ile oluşturur veya yeniden adlandırırsanız sorunlara neden olur. , filter, mapveya stateenrichgibi schemafiltermodüller için basit alfasayısal adlar kullanın.

Mevcut bir örnek çalışma alanını kullanmak yerine sıfırdan yeni bir çalışma alanı oluşturursunuz. Bu işlem, yeni bir graf uygulaması oluşturmayı ve Python ve Rust'taki işleçleri programlamayı öğrenmenizi sağlar.

Python'de yeni bir grafik uygulaması projesi oluşturma

VS Code komut paletini açmak için Ctrl+Shift+P tuşuna basın ve Azure IoT İşlemleri: Uygulama Oluştur arayın.

  1. Klasör için projeyi oluşturmak istediğiniz klasörü seçin. Bu proje için yeni bir klasör oluşturabilirsiniz.
  2. Ad olarak girin my-graph .
  3. Dil olarak Python seçin.
  4. Tür olarak Harita'yı seçin.
  5. Ad olarak girin map .

Artık temel proje yapısına ve başlangıç dosyalarına sahip yeni bir VS Code çalışma alanınız var. Başlangıç dosyaları dosyayı graph.dataflow.yaml ve harita işleci şablon kaynak kodunu içerir.

Önemli

Dağıtılan bir Azure IoT İşlemleri örneğinde Python modülü kullanmak için, aracı bellek profili Medium veya High olarak ayarlanmış örneği dağıtmanız gerekir. Bellek profilini Low veya Tiny olarak ayarlarsanız, örnek Python modülünü çekemez.

Harita işleci modülü için Python kodu ekleme

operators/map/map.py Fahrenheit'ten Santigrat'a gelen sıcaklık değerini dönüştürmek için dosyasını açın ve içeriğini aşağıdaki kodla değiştirin:

import json
from map_impl import exports
from map_impl import imports
from map_impl.imports import types

class Map(exports.Map):
    def init(self, configuration) -> bool:
        imports.logger.log(imports.logger.Level.INFO, "module4/map", "Init invoked")
        return True

    def process(self, message: types.DataModel) -> types.DataModel:
        # TODO: implement custom logic for map operator
        imports.logger.log(imports.logger.Level.INFO, "module4/map", "processing from python")

        # Ensure the input is of the expected type
        if not isinstance(message, types.DataModel_Message):
            raise ValueError("Unexpected input type: Expected DataModel_Message")

        # Extract and decode the payload
        payload_variant = message.value.payload
        if isinstance(payload_variant, types.BufferOrBytes_Buffer):
            # It's a Buffer handle - read from host
            imports.logger.log(imports.logger.Level.INFO, "module4/map", "Reading payload from Buffer")
            payload = payload_variant.value.read()
        elif isinstance(payload_variant, types.BufferOrBytes_Bytes):
            # It's already bytes
            imports.logger.log(imports.logger.Level.INFO, "module4/map", "Reading payload from Bytes")
            payload = payload_variant.value
        else:
            raise ValueError("Unexpected payload type")

        decoded = payload.decode("utf-8")

        # Parse the JSON data
        json_data = json.loads(decoded)

        # Check and update the temperature value
        if "temperature" in json_data and "value" in json_data["temperature"]:
            temp_f = json_data["temperature"]["value"]
            if isinstance(temp_f, int):
                # Convert Fahrenheit to Celsius
                temp_c = round((temp_f - 32) * 5.0 / 9.0)

                # Update the JSON data
                json_data["temperature"]["value"] = temp_c
                json_data["temperature"]["unit"] = "C"

                # Serialize the updated JSON back to bytes
                updated_payload = json.dumps(json_data).encode("utf-8")

                # Update the message payload
                message.value.payload = types.BufferOrBytes_Bytes(value=updated_payload)

        return message

Docker'ın çalıştığından emin olun. Ardından Ctrl+Shift+P tuşlarına basarak komut paletini açın ve Azure IoT İşlemleri: Tüm İşleçleri Derle araması yapın. Bir yayın modülü oluşturun.

Derleme işlemi, map.wasm işleci için map dosyasını operators/map/bin/release klasörüne yerleştirir.

Filtre işleci modülü için Rust kodu ekleme

komut paletini açmak ve Ctrl+Shift+P araması yapmak için tuşlarına basarak yeni bir işleç oluşturun:

  1. Dil olarak Rust'ı seçin.
  2. İşleç türü olarak Filtre'yi seçin.
  3. Ad olarak girin filter .

Dosyayı açın ve sıcaklığın operators/filter/src/lib.rs 500°C'nin üzerinde olduğu değerleri filtrelemek için içeriği aşağıdaki kodla değiştirin:

mod filter_operator {
    use wasm_graph_sdk::macros::filter_operator;
    use serde_json::Value;

    fn filter_init(_configuration: ModuleConfiguration) -> bool {
        // Add code here to process the module init properties and module schemas from the configuration

        true
    }

    #[filter_operator(init = "filter_init")]
    fn filter(input: DataModel) -> Result<bool, Error> {

        // Extract payload from input to process
        let payload = match input {
            DataModel::Message(Message {
                payload: BufferOrBytes::Buffer(buffer),
                ..
            }) => buffer.read(),
            DataModel::Message(Message {
                payload: BufferOrBytes::Bytes(bytes),
                ..
            }) => bytes,
            _ => return Err(Error { message: "Unexpected input type".to_string() }),
        };

        // ... perform filtering logic here and return boolean
        if let Ok(payload_str) = std::str::from_utf8(&payload) {
            if let Ok(json) = serde_json::from_str::<Value>(payload_str) {
                if let Some(temp_c) = json["temperature"]["value"].as_i64() {
                    // Return true if temperature is above 500°C
                    return Ok(temp_c > 500);
                }
            }
        }

        Ok(false)
   }
}

operators/filter/Cargo.toml Dosyayı açın ve aşağıdaki bağımlılıkları ekleyin:

[dependencies]
# ...
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Docker'ın çalıştığından emin olun. Ardından Ctrl+Shift+P tuşlarına basarak komut paletini açın ve Azure IoT İşlemleri: Tüm İşleçleri Derle araması yapın. Bir yayın modülü oluşturun.

Derleme işlemi, filter.wasm işleci için filter dosyasını operators/filter/bin/release klasörüne yerleştirir.

Graf uygulamasını örnek verilerle yerel olarak çalıştırma

graph.dataflow.yaml Dosyasını açın ve içeriğini aşağıdaki kodla değiştirin:

metadata:
    $schema: "https://www.schemastore.org/aio-wasm-graph-config-1.0.0.json"
    name: "Temperature Monitoring"
    description: "A graph that converts temperature from Fahrenheit to Celsius, if temperature is above 500°C, then sends the processed data to the sink."
    version: "1.0.0"
    vendor: "Microsoft"
moduleRequirements:
    apiVersion: "1.1.0"
    runtimeVersion: "1.1.0"
operations:
  - operationType: source
    name: source
  - operationType: map
    name: map
    module: map
  - operationType: filter
    name: filter
    module: filter
  - operationType: sink
    name: sink
connections:
  - from:
      name: source
    to:
      name: map
  - from:
      name: map
    to:
      name: filter
  - from:
      name: filter
    to:
      name: sink

data Kopyalanan örnek deposundaki explore-iot-operations\samples\wasm\data örnek verileri içeren klasörü geçerli çalışma alanına kopyalayın. klasör, data örnek giriş sıcaklığı verilerini içeren üç JSON dosyası içerir.

Yerel yürütme ortamını daha önce durdurduysanız Ctrl+Shift+P tuşlarına basarak komut paletini açın ve Azure IoT İşlemleri: Geliştirme Ortamını Başlat araması yapın. Çalıştırma modu olarak yayın'ı seçin.

tuşlarına basarak komut paletini açın ve Azure IoT İşlemleri: Application Graph:

  1. graph.dataflow.yaml Grafik dosyasını seçin.
  2. Çalıştırma modu olarak yayın'ı seçin.
  3. Çalışma alanına data kopyaladığınız klasörü seçin.

DevX kapsayıcısı grafiği çalıştırmak için başlatılır. İşlenen sonuç klasöre data/output kaydedilir. Klasördeki output metin dosyası, sıcaklığın Santigrat'a dönüştürüldüğü ve eşiğe göre filtrelendiği işlenmiş verileri içerir.

Özel WASM modüllerinizi ve grafınızı Azure IoT İşlemleri örneğinize dağıtmayı öğrenmek için bkz. WASM modüllerini ve veri akışı graflarını dağıtma.

WASM modüllerinizi derleyip graf uygulamanızı yapılandırdığınızda, bunları Azure IoT İşlemleri kümenize dağıtabilir ve grafik veya bağlayıcı yapılandırmanızda bunlara başvurabilirsiniz:

Troubleshoot

Derleme hataları

Error Nedeni Düzelt
error[E0463]: can't find crate for std WASM hedefi eksik rustup target add wasm32-wasip2 komutunu çalıştırın
error: no matching package found için wasm_graph_sdk Eksik kargo kayıt defteri [registries] bloğunu .cargo/config.toml olarak Graf uygulamasını yerel olarak çalıştırma bölümünde gösterildiği gibi ekleyin.
componentize-py WIT dosyalarını bulamıyorum Şema yolu yanlış Schema dizininin tam yolu ile -d bayrağını kullanın. Birbirlerine başvuracakları için tüm .wit dosyaların mevcut olması gerekir.
componentize-py sürüm uyuşmazlığı Farklı sürümle oluşturulan bağlamalar Oluşturulan bağlamalar dizinini silin ve aynı componentize-py sürümle yeniden oluşturun
wasm-tools bileşen denetimi başarısız oluyor Yanlış hedef veya eksik bileşen bağdaştırıcısı Kullandığınızın wasm32-wasip2 olduğundan (veya wasm32-wasi veya wasm32-unknown-unknown olmadığından) emin olun

Çalışma zamanı hataları

Belirti Nedeni Düzelt
Operatör WASM backtrace ile kilitleniyor Eksik veya geçersiz yapılandırma parametreleri Varsayılanlarla birlikte init konumuna hata önleyici ayrıştırma ekleyin. Bkz . Modül yapılandırma parametreleri.
init döndürür false, veri akışı başlamayacak Yapılandırma doğrulaması başarısız oldu Hata iletileri için veri akışı günlüklerini denetleyin. Adların kodunuzla eşleştiğinden emin olun moduleConfigurations .
Modül yüklenir ancak çıkış üretmez process hataları döndürme veya her şeyi düşüren filtre Veri akışını izlemek için oturum açmayı process ekleyin.
Unexpected input type Modül yanlış data-model değişken aldı process başına bir tür denetimi ekleyin ve beklenmeyen varyantları işleyin.
Modül tek başına çalışır ancak karmaşık grafikte kilitlenir Düğümler arasında yeniden kullanıldığında yapılandırma eksik Her grafik düğümü kendi moduleConfigurations girdisine ihtiyaç duyar.

Yaygın tuzaklar

  • ORAS gönderiminde unutma --artifact-type . Bu olmadan, işlem deneyimi kullanıcı arabirimi modülünüzü doğru şekilde görüntülemez.
  • name moduleConfigurations içinde eşleşmedi. Ad, graf tanımının <module>/<operator> bölümüne uygun olmalı ve module-temperature/filter (örneğin, operations) şeklinde eşleşmelidir.
  • wasm32-wasi yerine wasm32-wasip2 kullanma. Azure IoT İşlemleri WASI Preview 2 hedefini gerektirir.
  • Python: Şema dizinini kopyalamadan örnek deposunun dışında çalışma. Tüm .wit dosyalar birbirine başvuracakları için birlikte bulunmalıdır.

Bilinen sorunlar

  • YAML'deki Boole değerleri: Doğrulama hatalarından kaçınmak için Boole değerleri dize olarak tırnak içine alınmalıdır. Örneğin, "True" ve "False" yerine true ve false kullanın.

    Alıntılanmamış boolean'lar kullanılırken bir örnek hata:

    * spec.connections[2].from.arm: Invalid value: "boolean": spec.connections[2].from.arm in body must be of type string: "boolean"
* spec.connections[2].from.arm: Unsupported value: false: supported values: "False", "True"

  • Python modül gereksinimleri: Python modülleri kullanmak için Azure IoT İşlemleri Medium veya High bellek profilini kullanacak şekilde yapılandırılmış MQTT aracısı ile dağıtılmalıdır. bellek profili Low veya Tiny olarak ayarlandığında Python modülleri çekilemiyor.

  • Modül dağıtım zamanlaması: WASM modüllerini çekmek ve uygulamak, ağ koşullarına ve modül boyutuna bağlı olarak genellikle yaklaşık bir dakika sürebilir.

  • Derleme hatası ayrıntıları: Derleme başarısız olduğunda, açılır bildirimdeki hata iletisi yeterli ayrıntı sağlamayabilir. Daha ayrıntılı hata bilgileri için terminal çıkışını denetleyin.

  • Windows uyumluluğu: Windows ilk kez bir grafik uygulaması çalıştırdığınızda, "komut çıkış kodu 1 ile başarısız oldu" hatasıyla karşılaşabilirsiniz. Bu hata oluşursa işlemi yeniden deneyin ve düzgün çalışması gerekir.

  • Konak uygulaması kararlılığı: Yerel yürütme ortamı zaman zaman çalışmayı durdurabilir ve kurtarmak için yeniden başlatmayı gerektirebilir.

  • Remote hata ayıklama sınırlamaları: Şu anda uyumsuz LLDB sürümleri nedeniyle Azure Linux 3.0'da çalışan WASM modüllerinde uzaktan hata ayıklayamazsınız.

Kurtarma yordamları

VS Code uzantısı sıfırlama: VS Code uzantısı beklenmedik şekilde davranırsa, kaldırmayı ve yeniden yüklemeyi deneyin, ardından VS Code'u yeniden başlatın.

İlgili içerik

  • Last updated on