メッセージスキーマを理解する

[アーティクル]
11/20/2024

Azure デバイスレジストリで提供される機能であるスキーマレジストリは、クラウドとエッジで同期されるリポジトリです。スキーマレジストリは、エッジ資産からのメッセージの定義を格納し、エッジでこれらのスキーマにアクセスするための API を公開します。

OPC UA 用コネクタは、メッセージスキーマを作成してスキーマレジストリにそれを追加できます。または、お客様は、スキーマを操作エクスペリエンス Web UI にアップロードしたり、ARM/Bicep テンプレートを使用したりできます。

エッジサービスは、メッセージスキーマを使って、産業用エッジシナリオでルーティングされるメッセージのフィルター処理と変換を行います。

"スキーマ" は、メッセージを処理してコンテキスト化できるようにその形式と内容が記述されているドキュメントです。

メッセージスキーマの定義

スキーマレジストリでは、メッセージスキーマに次の必須フィールドが含まれることが想定されています。

必須フィールド	Definition
`$schema`	`http://json-schema.org/draft-07/schema#` または `Delta/1.0` のいずれかです。データフローでは、JSON スキーマはソースエンドポイントに使われ、Delta スキーマは宛先エンドポイントに使われます。
`type`	`Object`
`properties`	メッセージの定義。

サンプルスキーマ

次のサンプルスキーマでは、各形式でのメッセージスキーマの定義の例を示します。

JSON:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "name": "foobarbaz",
  "description": "A representation of an event",
  "type": "object",
  "required": [ "dtstart", "summary" ],
  "properties": {
    "summary": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "duration": {
      "type": "string",
      "description": "Event duration"
    }
  }
}

Delta:

{
  "$schema": "Delta/1.0",
  "type": "object",
  "properties": {
    "type": "struct",
    "fields": [
      { "name": "asset_id", "type": "string", "nullable": false, "metadata": {} },
      { "name": "asset_name", "type": "string", "nullable": false, "metadata": {} },
      { "name": "location", "type": "string", "nullable": false, "metadata": {} },
      { "name": "manufacturer", "type": "string", "nullable": false, "metadata": {} },
      { "name": "production_date", "type": "string", "nullable": false, "metadata": {} },
      { "name": "serial_number", "type": "string", "nullable": false, "metadata": {} },
      { "name": "temperature", "type": "double", "nullable": false, "metadata": {} }
    ]
  }
}

スキーマの生成

サンプルデータファイルからスキーマを生成するには、Schema Gen Helper を使用します。

スキーマジェネレーターを使用したチュートリアルについては、「チュートリアル: OPC UA サーバーから Azure Data Lake Storage Gen 2 にデータを送信する」を参照してください。

データフローでのメッセージスキーマの使用方法

メッセージスキーマは、データフローの 3 つのフェーズ (ソース入力の定義、データ変換の適用、宛先出力の作成) のすべてで使われます。

入力スキーマ

各データフローソースでは、必要に応じてメッセージスキーマを指定できます。現在、データフローはソースメッセージスキーマの実行時の検証を行いません。

資産ソースには、OPC UA 用コネクタによって作成された定義済みのメッセージスキーマがあります。

MQTT ソースのスキーマをアップロードできます。現在、Azure IoT Operations では、入力スキーマとも呼ばれるソーススキーマに対して JSON がサポートされています。操作エクスペリエンスでは、既存のスキーマを選ぶか、MQTT ソースの定義の間にアップロードできます。

操作エクスペリエンスポータルでのメッセージスキーマのアップロードを示すスクリーンショット。

変換

操作エクスペリエンスでは、入力スキーマがデータの起点として使われ、既知の入力メッセージ形式に基づいて変換を簡単に選択できます。

出力スキーマ

出力スキーマはデータフローの宛先に関連付けられます。

操作エクスペリエンスポータルでは、Parquet 出力をサポートする次の宛先エンドポイントに対して出力スキーマを構成できます。

ローカルストレージ
Fabric OneLake
Azure Storage (ADLS Gen2)
Azure Data Explorer

注: Delta スキーマ形式は、Parquet と Delta 両方の出力に使われます。

Bicep または Kubernetes を使用する場合は、MQTT と Kafka の宛先エンドポイントに JSON 出力を使用して出力スキーマを構成できます。 MQTT および Kafka ベースの宛先は Delta 形式をサポートしていません。

これらのデータフローでは、操作エクスペリエンスによって入力スキーマに変換が適用されてから、Delta 形式で新しいスキーマが作成されます。作成されたデータフローカスタムリソース (CR) には、スキーマレジストリに格納されている生成されたスキーマを指す schemaRef 値が含まれます。

出力スキーマをアップロードするには、「スキーマのアップロード」を参照してください。

スキーマのアップロード

この記事の入力スキーマセクションで説明したように、入力スキーマは、操作エクスペリエンスポータルでアップロードできます。 Azure CLI または Bicep テンプレートを使用してスキーマをアップロードすることもできます。

CLI を使用したスキーマのアップロード

az iot ops schema コマンドグループには、スキーマレジストリでスキーマを作成、表示、管理するためのコマンドが含まれています。

JSON ファイルを参照するか、スキーマをインラインコンテンツとして含めることで、スキーマをアップロードできます。

次の例では、最小限の入力を使って、ファイルから myschema という名前のスキーマを作成します。バージョン番号を指定しない場合、スキーマバージョンは 1 です。

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

次の例では、インラインコンテンツから myschema という名前のスキーマを作成して、バージョン番号を割り当てます。

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

ヒント

レジストリ名がわからない場合は、schema registry list コマンドを使用してクエリを実行します。次に例を示します。

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

create コマンドが完了すると、スキーマコンテンツを含む BLOB がストレージアカウントコンテナーに表示されます。 BLOB の名前は schema-namespace/schema/version という形式です。

ヘルパーコマンド az iot ops schema -h を使用すると、その他のオプションを確認できます。

Bicep テンプレートを使用したスキーマのアップロード

Bicep .bicep ファイルを作成し、その先頭にスキーマの内容を変数として追加します。この例は、クイックスタートの OPC UA データに対応する Delta スキーマです。

// Delta schema content matching OPC UA data from quickstart
// For ADLS Gen2, ADX, and Fabric destinations
var opcuaSchemaContent = '''
{
  "$schema": "Delta/1.0",
  "type": "object",
  "properties": {
    "type": "struct",
    "fields": [
      {
        "name": "temperature",
        "type": {
          "type": "struct",
          "fields": [
            {
              "name": "SourceTimestamp",
              "type": "string",
              "nullable": true,
              "metadata": {}
            },
            {
              "name": "Value",
              "type": "integer",
              "nullable": true,
              "metadata": {}
            },
            {
              "name": "StatusCode",
              "type": {
                "type": "struct",
                "fields": [
                  {
                    "name": "Code",
                    "type": "integer",
                    "nullable": true,
                    "metadata": {}
                  },
                  {
                    "name": "Symbol",
                    "type": "string",
                    "nullable": true,
                    "metadata": {}
                  }
                ]
              },
              "nullable": true,
              "metadata": {}
            }
          ]
        },
        "nullable": true,
        "metadata": {}
      },
      {
        "name": "Tag 10",
        "type": {
          "type": "struct",
          "fields": [
            {
              "name": "SourceTimestamp",
              "type": "string",
              "nullable": true,
              "metadata": {}
            },
            {
              "name": "Value",
              "type": "integer",
              "nullable": true,
              "metadata": {}
            },
            {
              "name": "StatusCode",
              "type": {
                "type": "struct",
                "fields": [
                  {
                    "name": "Code",
                    "type": "integer",
                    "nullable": true,
                    "metadata": {}
                  },
                  {
                    "name": "Symbol",
                    "type": "string",
                    "nullable": true,
                    "metadata": {}
                  }
                ]
              },
              "nullable": true,
              "metadata": {}
            }
          ]
        },
        "nullable": true,
        "metadata": {}
      }
    ]
  }
}
'''

次に、スキーマのすぐ下にある同じファイルに、Azure IoT Operations のデプロイから取得した既存のスキーマレジストリリソースへのポインターとともに、スキーマリソースを定義します。

// Replace placeholder values with your actual resource names
param schemaRegistryName string = '<SCHEMA_REGISTRY_NAME>'

// Pointers to existing resources from AIO deployment
resource schemaRegistry 'Microsoft.DeviceRegistry/schemaRegistries@2024-09-01-preview' existing = {
  name: schemaRegistryName
}

// Name and version of the schema
param opcuaSchemaName string = 'opcua-output-delta'
param opcuaSchemaVer string = '1'

// Define the schema resource to be created and instantiate a version
resource opcSchema 'Microsoft.DeviceRegistry/schemaRegistries/schemas@2024-09-01-preview' = {
  parent: schemaRegistry
  name: opcuaSchemaName
  properties: {
    displayName: 'OPC UA Delta Schema'
    description: 'This is a OPC UA delta Schema'
    format: 'Delta/1.0'
    schemaType: 'MessageSchema'
  }
}
resource opcuaSchemaVersion 'Microsoft.DeviceRegistry/schemaRegistries/schemas/schemaVersions@2024-09-01-preview' = {
  parent: opcSchema
  name: opcuaSchemaVer
  properties: {
    description: 'Schema version'
    schemaContent: opcuaSchemaContent
  }
}

スキーマの内容とリソースを定義したら、Bicep テンプレートをデプロイしてスキーマレジストリにスキーマを作成できます。

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

次のステップ

データフローを作成する

次の方法で共有

メッセージスキーマを理解する

メッセージスキーマの定義

サンプルスキーマ

スキーマの生成

データフローでのメッセージスキーマの使用方法

入力スキーマ

変換

出力スキーマ

スキーマのアップロード

CLI を使用したスキーマのアップロード

Bicep テンプレートを使用したスキーマのアップロード

次のステップ

フィードバック

その他のリソース

次の方法で共有

メッセージ スキーマを理解する

メッセージ スキーマの定義

サンプル スキーマ

スキーマの生成

データフローでのメッセージ スキーマの使用方法

入力スキーマ

変換

出力スキーマ

スキーマのアップロード

CLI を使用したスキーマのアップロード

Bicep テンプレートを使用したスキーマのアップロード

次のステップ

フィードバック

その他のリソース

メッセージスキーマを理解する

メッセージスキーマの定義

サンプルスキーマ

データフローでのメッセージスキーマの使用方法