你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

了解消息架构

项目
11/20/2024

架构注册表（Azure 设备注册表提供的一项功能）是云中和边缘的同步存储库。架构注册表能够存储来自边缘资产的消息的定义，然后公开 API 以访问边缘上的这些架构。

OPC UA 连接器可以创建消息架构并将其添加到架构注册表，客户也可以将架构上传到操作体验 Web UI，或者使用 ARM/Bicep 模板。

边缘服务使用消息架构来筛选和转换跨工业边缘场景路由的消息。

架构是描述消息及其内容的格式以便启用处理和上下文化的文档。

消息架构定义

架构注册表需要消息架构中包含以下必填字段：

必填字段	定义
`$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。

数据流如何使用消息架构

消息架构用于数据流的所有三个阶段：定义源输入、应用数据转换、创建目标输出。

输入架构

每个数据流源可以选择指定一个消息架构。目前，数据流不会对源消息架构执行运行时验证。

资产源具有由 OPC UA 连接器创建的预定义消息架构。

可以为消息代理源上传架构。目前，Azure IoT 操作支持源架构（也称为输入架构）的 JSON。在操作体验中，可以选择现有架构或在定义消息代理源时上传一个架构：

屏幕截图显示了如何在操作体验门户中上传消息架构。

转换

操作体验使用输入架构作为数据的起点，因而更容易根据已知的输入消息格式选择转换。

输出架构

输出架构与数据流目标相关联。

在操作体验门户中，可以为支持 Parquet 输出的以下目标终结点配置输出架构：

本地存储
Fabric OneLake
Azure 存储 (ADLS Gen2)
Azure 数据资源管理器

注意：Delta 架构格式用于 Parquet 和 Delta 输出。

如果使用 Bicep 或 Kubernete，则可以使用 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 操作时获得的。

// 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

后续步骤

创建数据流

通过