İleti şemalarını anlama

Azure Cihaz Kayıt Defteri'nin bir özelliği olan şema kayıt defteri, bulutta ve uçta eşitlenmiş bir depodur. Uç varlıklarından gelen iletilerin tanımlarını depolar ve uçta bu şemalara erişmek için bir API'yi kullanıma sunar.

Veri akışları şemaları üç yerde kullanır:

• Kaynak: İsteğe bağlı olarak, gelen iletileri açıklamak için bir şema belirtin. İşlem deneyimi, kullanılabilir alanları görüntülemek için bunu kullanır.
• Dönüştürme: İşlem deneyimi, dönüştürmeleri oluştururken başlangıç noktası olarak kaynak şemayı kullanır.
• Hedef: Depolama uç noktalarına veri gönderirken bir çıkış şeması ve serileştirme biçimi belirtin.

Uyarı

Veri akışı grafikleri için şemalar farklı yapılandırılır. Bkz. Veri akışı grafiklerinde şemaları kullanma.

Şema biçimleri

Şema kayıt defteri iki biçimi destekler:

Biçim	$schema değer	Kullanım amacı
JSON	http://json-schema.org/draft-07/schema#	Kaynak uç noktalar (MQTT, Kafka)
Delta	Delta/1.0	Hedef uç noktalar (depolama: ADLS, Fabric, ADX, yerel)

Her iki biçim de type: "object" ve ileti yapısını tanımlayan bir properties alanı gerektirir.

JSON şema örneği

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "temperature": { "type": "number" },
    "humidity": { "type": "number" },
    "deviceId": { "type": "string" },
    "timestamp": { "type": "string" }
  }
}

Delta şeması örneği

{
  "$schema": "Delta/1.0",
  "type": "object",
  "properties": {
    "type": "struct",
    "fields": [
      { "name": "asset_id", "type": "string", "nullable": true, "metadata": {} },
      { "name": "temperature", "type": "double", "nullable": true, "metadata": {} },
      { "name": "timestamp", "type": "string", "nullable": true, "metadata": {} }
    ]
  }
}

Bu örnek her alanı nullable: true olarak işaretler. Bir alanı, yalnızca eşlemeniz her zaman bir değer üretiyorsa nullable: false olarak işaretleyin. Parquet ve Delta ile, bir alan nullable: false ancak bir kayıtta yoksa, tüm toplu işlem başarısız olur ve düşürülür. Daha fazla bilgi için bkz . Depolama serileştirme davranışı.

Şema oluşturma

Örnek veri dosyasından şema oluşturmak için Şema Nesil Yardımcısı'nı kullanın.

Şema oluşturucuyu kullanan bir öğretici için bkz . Öğretici: OPC UA sunucusundan Azure Data Lake Storage 2. Nesil'e veri gönderme.

Kaynak şema yapılandırma

Her veri akışı kaynağı isteğe bağlı olarak bir ileti şeması belirtebilir. Şu anda veri akışları kaynak şemalarda çalışma zamanı yük doğrulaması gerçekleştirmemektedir. İşlem deneyimi, dönüştürmeleri oluştururken kullanılabilir alanları görüntülemek için şemayı kullanır.

İki ilgili davranışı kolayca kaçırabilirsiniz:

• İletideki bir şema referansı kaydı engelleyebilir. Kaynak ileti bir şema başvurusu (MQTT dataschema özelliği) taşıyorsa ve kaynağı şema bilgileriyle yapılandırırsanız, veri akışı ikisini karşılaştırır. Çakıştıklarında, mesaj onaylanır ve herhangi bir çıktı üretilmeden göz ardı edilir; çalışma zamanı conflicting schema ifadesini günlüğe kaydeder. Bu denetim, yükün doğrulanmasından ayrıdır: ileti içeriği şemaya göre doğrulanmaz, ancak uyuşmayan bir referans kaydın işlenmesini yine de durdurur.
• Yapılandırılan JSON şemaları çalışma zamanı doğrulayıcıları değildir. JSON çıktısında, yapılandırılmış bir şema serileştirme sırasında uygulanmaz. Veri akışı, çalışma zamanı değeri şeklini doğrudan çıkarımlı türlerle serileştirir. JSON şemalarını tasarım zamanı belgeleri olarak kullanın, çıkışın şemaya uygun olduğunu garanti etmek için değil.

Varlık kaynakları, OPC UA için bağlayıcı tarafından oluşturulmuş önceden tanımlanmış bir şemaya sahiptir. İleti aracısı kaynakları için, işlem deneyiminde bir JSON şeması yükleyebilir veya yapılandırmanızda bir şemaya başvurabilirsiniz.

Veri akışı kaynak yapılandırmanızdaki bir şemaya başvurmak için schemaRef alanını kullanın. Daha fazla bilgi için bkz. Veri akışı kaynağı yapılandırma.

Çıkış şeması yapılandırma

Çıkış şemaları, verilerin hedefe ulaşmadan önce nasıl seri hale getirilişini denetler. Depolama uç noktaları (ADLS 2. Nesil, Doku OneLake, Azure Veri Gezgini, yerel depolama) bir şema gerektirir ve Parquet ve Delta serileştirme biçimlerini destekler. MQTT ve Kafka hedefleri varsayılan olarak JSON kullanır.

İşlem deneyiminde, bir depolama hedefi seçtiğinizde kullanıcı arabirimi kaynak şemaya tüm dönüştürmeleri uygular ve otomatik olarak bir Delta şeması oluşturur. Oluşturulan şema, şema kayıt defterinde depolanır ve veri akışı tarafından başvurulur.

Bicep veya Kubernetes dağıtımları için dönüştürme ayarlarında şema ve serileştirme biçimini belirtin. Daha fazla bilgi için bkz . Veri akışı hedefi yapılandırma.

Depolama serileştirme davranışı

Veri akışı Parquet veya Delta serileştirme kullanarak bir depolama uç noktasına (ADLS 2. Nesil, Fabric OneLake, Azure Veri Gezgini veya yerel depolama) yazdığında, çıkış şeması kayıtların nasıl yazıldığından emin olur. Aşağıdaki davranışlar kayıtların beklenmedik değerlerle bırakılmasına veya yazılmasına neden olabilir. Şema veya eşleme tasarlamadan önce bunları gözden geçirin.

Boş değer alamayan alanlar, tüm toplu işlemi düşürebilir. Yazma zamanında kodlayıcı, çıkış şemasındaki her alanı denetler. Bir alan nullable: false ise ve bir kayıtta bu alan için bir değer yoksa (çünkü alan eşlenmemiş, yanlış yazılmış veya kaynakta eksikse), kaydetme işlemi başarısız olur ve veri akışı yalnızca o kaydı değil, bekleyen toplu işlemin tamamını düşürür. Çalışma zamanı, ParquetEncoding found missing property that is not Nullable: <field> benzeri bir hatayı, ardından failed to commit record into a batch, dropping it gelecek şekilde günlüğe kaydeder. Veri akışı çalışmaya devam eder, bu nedenle günlükleri denetlemediğiniz sürece kayıp sessiz olur. Bu sorunu önlemek için, bir alanı nullable: false olarak yalnızca eşlemeniz bu alan için her zaman bir değer üretiyorsa işaretleyin. Aksi takdirde kullanın nullable: true. nullable: false alanına eşlenen açık bir null değeri, Cannot set null value. Reason: field '<field>' is not nullable. hatasıyla aynı şekilde başarısız olur.

Eşlemeyi nesnenin tamamına değil, her yaprak alana yapın. Parquet ve Delta için, yalnızca şemada bildirilen yaprak alanda bir değer ayarlayabilirsiniz. Bir yapının veya nesnenin tamamını bir üst yoluna eşlemek, iç içe geçmiş değerleri yazmaz ve ParquetEncoding could not set a field <path>, it does not exist by the schema benzeri bir hatayla kaydı düşürür. Şemanın tanımladığı her çıktı yaprağını eşleyin.

Joker karakterler, şemanın genişletilen her alanı tanımlamasını gerektirir. * -> * eşlemesi (veya düzleştirme ve yeniden yapılandırma desenleri dahil herhangi bir joker karakter), çalışma zamanı yükündeki her bir yaprağa genişler. Parquet ve Delta için çıkış şeması bu yaprakların her birini bildirmelidir. Veri yükü, şemanın tanımlamadığı bir yaprak içeriyorsa kayıt atılır. Şemayı temsili örnek verilerden oluşturarak veri akışının ürettiği her alanı içermesini sağlayın.

Bir şema tek başına değerleri doldurmaz. Şema çıkış şeklini açıklar, ancak verileri taşımaz. Eşleme olmadan, veri akışı tüm null değerlerin kayıtlarını yazar (null atanabilir alanlar için) veya bunları bırakır (null atanamayan alanlar için). Değerleri doldurmak için genellikle * -> * bir eşleme ekleyin ve bir değer olmayabileceğinde alanların nullable: true olduğundan emin olun.

Sayısal dönüştürmeler sessizdir ve duyarlığı kaybedebilir. Eşlenen bir değerin türü şema sütununun türüyle eşleşmediğinde, Parquet ve Delta bunu hata vermeden zorla dönüştürür. Kayan noktalı sayıdan tamsayıya dönüşümler kesirli kısmı atar ve daraltıcı dönüşümler hassasiyet kaybına veya taşmaya neden olabilir. Yuvarlama gerekiyorsa, yuvarlama işlemini eşlemede açıkça yapın. Kullanılabilir işlevler için bkz . Ölçeklendirme ve yuvarlama işlevleri.

Eksik ve null aynı değildir. Serileştirme sırasında kayıtta bulunmayan (eksik) alan atlanırken, biçim izin verdiğinde açıkça olarak ayarlanmış null bir alan yazılır. Parquet ve Delta için, nullable: true alanındaki eksik bir değer null olarak yazılır, nullable: false alanındaki eksik bir değer toplu işleme alınmaz ve nullable: false alanındaki açık bir null değeri de hata verir. Bu farkı göz önünde bulundurarak eşlemelerinizi ve null atanabilirlik durumunu tasarlayın.

Karmaşık türler her biçimde farklı şekilde dönüştürülür. Nesneler, haritalar, bayt değerleri ve diziler, biçimler arasında aynı şekilde serileştiremez:

• Haritalar (dize olmayan anahtarlara sahip nesneler): Parquet ve Delta, hatasını Currently maps are not supportediçeren haritaları reddeder. JSON yalnızca anahtarlar dize olduğunda eşlemeleri destekler. Avro, eşleme anahtarlarını dizelere dönüştürür ve dönüştürmeden sonra iki anahtar çakışırsa son değer geçerli olur.
• Bayt değerleri: JSON baytları base64 dizesi olarak kodlar. Parquet ve Delta, şema sütun türüne bağlı olarak baytları ikili, base64 dizesi veya liste olarak yazabilir.
• Dizi: Parquet ve Delta, sütun türüne bağlı olarak dizileri liste veya ikili olarak yazar. Sabit boyutlu ikili sütun, dizi uzunluğu eşleşmiyorsa başarısız olur.

Karmaşık bir değer için öngörülebilir bir şekle ihtiyacınız varsa, tam nesne geçişine güvenmek yerine tek tek yaprak alanlarını açıkça eşleyin.

Şemayı karşıya yükle

Operasyon deneyimi kullanıcı arabirimi, Azure CLI veya Bicep dağıtımı ile şemaları karşıya yükleyebilirsiniz.

Azure CLI ile yükleme işlemi

Şemaları oluşturmak ve yönetmek için az iot ops schema komut grubunu kullanın.

Bir dosyadan şema oluşturma:

az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format json --type message --version-content myschema.json

Belirli bir sürüme sahip satır içi içerikten şema oluşturma:

az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format delta --type message --version-content '{"hello": "world"}' --ver 14

Tavsiye

Kayıt defterinizin adını bilmiyorsanız komutunu kullanın schema registry list :

az iot ops schema registry list -g myresourcegroup --query "[].{Name:name}" -o tsv

Komut tamamlandıktan sonra, depolama hesabı kapsayıcınızda şema içeriğiyle birlikte bir blob görüntülenir. Blob adı schema-namespace/schema/version biçimini izler.

Bicep ile karşıya yükleme

Şema içeriğini değişken olarak tanımlayın ve şema kaynağını oluşturun:

param schemaRegistryName string = '<SCHEMA_REGISTRY_NAME>'
param schemaName string = 'sensor-data-delta'
param schemaVersion string = '1'

var schemaContent = '''
{
  "$schema": "Delta/1.0",
  "type": "object",
  "properties": {
    "type": "struct",
    "fields": [
      { "name": "temperature", "type": "double", "nullable": true, "metadata": {} },
      { "name": "humidity", "type": "double", "nullable": true, "metadata": {} },
      { "name": "deviceId", "type": "string", "nullable": true, "metadata": {} }
    ]
  }
}
'''

resource schemaRegistry 'Microsoft.DeviceRegistry/schemaRegistries@2026-04-01' existing = {
  name: schemaRegistryName
}

resource schema 'Microsoft.DeviceRegistry/schemaRegistries/schemas@2026-04-01' = {
  parent: schemaRegistry
  name: schemaName
  properties: {
    displayName: 'Sensor Data Delta Schema'
    description: 'Delta schema for sensor telemetry'
    format: 'Delta/1.0'
    schemaType: 'MessageSchema'
  }
}

resource version 'Microsoft.DeviceRegistry/schemaRegistries/schemas/schemaVersions@2026-04-01' = {
  parent: schema
  name: schemaVersion
  properties: {
    description: 'Initial version'
    schemaContent: schemaContent
  }
}

Bicep dosyasının dağıtımını gerçekleştirin.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file schema.bicep

İlgili içerik

• Veri akışı grafiklerinde şemaları kullanma
• Veri akışı kaynağını yapılandırma
• Veri akışı hedefi yapılandırma
• Veri akışı oluşturma