메시지 스키마 이해

아티클
11/20/2024

Azure Device Registry에서 제공하는 기능인 스키마 레지스트리는 클라우드 및 에지의 동기화된 리포지토리입니다. 스키마 레지스트리는 에지 자산에서 들어오는 메시지의 정의를 저장한 다음 에지에서 해당 스키마에 액세스하기 위해 API를 노출합니다.

OPC UA용 커넥터는 메시지 스키마를 만들어 스키마 레지스트리에 추가하거나 고객이 작업 환경 웹 UI 또는 ARM/Bicep 템플릿을 사용하여 스키마를 업로드할 수 있습니다.

Edge 서비스는 메시지 스키마를 사용하여 산업용 에지 시나리오에서 라우팅될 때 메시지를 필터링하고 변환합니다.

스키마는 처리 및 컨텍스트화를 가능하게 하는 메시지의 형식과 해당 내용을 설명하는 문서입니다.

메시지 스키마 정의

스키마 레지스트리에는 메시지 스키마에 다음과 같은 필수 필드가 필요합니다.

필수 필드	정의
`$schema`	`http://json-schema.org/draft-07/schema#` 또는 `Delta/1.0` 중 하나입니다. 데이터 흐름에서 JSON 스키마는 원본 엔드포인트에 사용되고 델타 스키마는 대상 엔드포인트에 사용됩니다.
`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"
    }
  }
}

삼각주:

{
  "$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": {} }
    ]
  }
}

스키마 생성

샘플 데이터 파일에서 스키마를 생성하려면 스키마 Gen 도우미를 사용합니다.

스키마 생성기를 사용하는 자습서는 자습서: OPC UA 서버에서 Azure Data Lake Storage Gen 2로 데이터 보내기를 참조하세요.

데이터 흐름에서 메시지 스키마를 사용하는 방법

메시지 스키마는 원본 입력 정의, 데이터 변환 적용 및 대상 출력 만들기의 세 가지 데이터 흐름 단계에서 모두 사용됩니다.

입력 스키마

각 데이터 흐름 원본은 필요에 따라 메시지 스키마를 지정할 수 있습니다. 현재 데이터 흐름은 원본 메시지 스키마에서 런타임 유효성 검사를 수행하지 않습니다.

자산 원본에는 OPC UA용 커넥터에서 만든 미리 정의된 메시지 스키마가 있습니다.

MQTT 원본에 대해 스키마를 업로드할 수 있습니다. 현재 Azure IoT Operations는 입력 스키마라고도 하는 원본 스키마에 대해 JSON을 지원합니다. 작업 환경에서 MQTT 원본을 정의하는 동안 기존 스키마를 선택하거나 업로드할 수 있습니다.

작업 환경 포털에서 메시지 스키마 업로드를 보여 주는 스크린샷

변환

작업 환경에서는 입력 스키마를 데이터의 시작점으로 사용하여 알려진 입력 메시지 형식에 따라 변환을 더 쉽게 선택할 수 있습니다.

출력 스키마

출력 스키마는 데이터 흐름 대상과 연결됩니다.

작업 환경 포털에서 Parquet 출력을 지원하는 다음 대상 엔드포인트에 대한 출력 스키마를 구성할 수 있습니다.

로컬 스토리지
Fabric OneLake
Azure Storage(ADLS Gen2)
Azure Data Explorer

참고: 델타 스키마 형식은 Parquet 및 Delta 출력 모두에 사용됩니다.

Bicep 또는 Kubernetes를 사용하는 경우 MQTT 및 Kafka 대상 엔드포인트에 JSON 출력을 사용하여 출력 스키마를 구성할 수 있습니다. MQTT 및 Kafka 기반 대상은 델타 형식을 지원하지 않습니다.

이러한 데이터 흐름의 경우 작업 환경은 입력 스키마에 모든 변환을 적용한 다음 델타 형식으로 새 스키마를 만듭니다. CR(데이터 흐름 사용자 지정 리소스)을 만들 때 스키마 레지스트리에 저장된 생성된 스키마를 가리키는 값이 포함 schemaRef 됩니다.

출력 스키마를 업로드하려면 스키마 업로드를 참조하세요.

스키마 업로드

이 문서의 입력 스키마 섹션에 설명된 대로 작업 환경 포털에서 입력 스키마를 업로드할 수 있습니다. Azure CLI 또는 Bicep 템플릿을 사용하여 스키마를 업로드할 수도 있습니다.

CLI를 사용하여 스키마 업로드

az iot ops 스키마 명령 그룹에는 스키마 레지스트리에서 스키마를 만들고 보고 관리하는 명령이 포함되어 있습니다.

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

다음 단계

데이터 흐름 만들기

다음을 통해 공유