Omówienie schematów komunikatów
Rejestr schematów, funkcja udostępniana przez usługę Azure Device Registry, to zsynchronizowane repozytorium w chmurze i na brzegu sieci. Rejestr schematów przechowuje definicje komunikatów pochodzących z zasobów brzegowych, a następnie uwidacznia interfejs API w celu uzyskania dostępu do tych schematów na brzegu sieci.
Łącznik OPC UA może tworzyć schematy komunikatów i dodawać je do rejestru schematów lub klienci mogą przekazywać schematy do internetowego interfejsu użytkownika środowiska operacji lub przy użyciu szablonów ARM/Bicep.
Usługi brzegowe używają schematów komunikatów do filtrowania i przekształcania komunikatów w miarę ich kierowania w scenariuszu na brzegu przemysłowym.
Schematy to dokumenty opisujące format komunikatu i jego zawartości w celu umożliwienia przetwarzania i kontekstyzacji.
Definicje schematu komunikatów
Rejestr schematów oczekuje następujących wymaganych pól w schemacie komunikatu:
| Pole wymagane | Definicja |
|---|---|
$schema |
http://json-schema.org/draft-07/schema# lub Delta/1.0. W przepływach danych schematy JSON są używane dla źródłowych punktów końcowych, a schematy różnicowe są używane dla docelowych punktów końcowych. |
type |
Object |
properties |
Definicja komunikatu. |
Przykładowe schematy
Poniższe przykładowe schematy zawierają przykłady definiowania schematów komunikatów w każdym formacie.
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": {} }
]
}
}
Generowanie schematu
Aby wygenerować schemat na podstawie przykładowego pliku danych, użyj pomocnika generacji schematu.
Aby zapoznać się z samouczkiem korzystającym z generatora schematów, zobacz Samouczek: wysyłanie danych z serwera OPC UA do usługi Azure Data Lake Storage Gen 2.
Jak przepływy danych używają schematów komunikatów
Schematy komunikatów są używane we wszystkich trzech fazach przepływu danych: definiowanie danych wejściowych źródła, stosowanie przekształceń danych i tworzenie docelowych danych wyjściowych.
Schemat wejściowy
Każde źródło przepływu danych może opcjonalnie określić schemat komunikatu. Obecnie przepływy danych nie przeprowadzają walidacji środowiska uruchomieniowego w schematach komunikatów źródłowych.
Źródła zasobów mają wstępnie zdefiniowany schemat komunikatu, który został utworzony przez łącznik dla OPC UA.
Schematy można przekazywać dla źródeł MQTT. Obecnie operacje usługi Azure IoT obsługują kod JSON dla schematów źródłowych, nazywanych również schematami wejściowymi. W środowisku operacji można wybrać istniejący schemat lub przekazać go podczas definiowania źródła MQTT:
Przekształcenie
Środowisko operacji używa schematu wejściowego jako punktu wyjścia dla danych, co ułatwia wybieranie przekształceń w oparciu o znany format komunikatu wejściowego.
Schemat danych wyjściowych
Schematy wyjściowe są skojarzone z miejscami docelowymi przepływu danych.
W portalu środowiska operacji można skonfigurować schematy wyjściowe dla następujących docelowych punktów końcowych obsługujących dane wyjściowe Parquet:
- magazyn lokalny
- Sieć szkieletowa OneLake
- Azure Storage (ADLS Gen2)
- Azure Data Explorer
Uwaga: Format schematu różnicowego jest używany zarówno dla danych wyjściowych Parquet, jak i Delta.
Jeśli używasz Bicep lub Kubernetes, możesz skonfigurować schematy wyjściowe przy użyciu danych wyjściowych JSON dla punktów końcowych docelowych MQTT i Kafka. Miejsca docelowe oparte na MQTT i platformie Kafka nie obsługują formatu różnicowego.
W przypadku tych przepływów danych środowisko operacji stosuje wszelkie przekształcenia do schematu wejściowego, a następnie tworzy nowy schemat w formacie delta. Po utworzeniu zasobu niestandardowego przepływu danych (CR) zawiera wartość wskazującą schemaRef wygenerowany schemat przechowywany w rejestrze schematów.
Aby przekazać schemat wyjściowy, zobacz Przekazywanie schematu.
Przekazywanie schematu
Schemat wejściowy można przekazać w portalu środowiska operacji zgodnie z opisem w sekcji Schemat danych wejściowych w tym artykule. Schemat można również przekazać przy użyciu interfejsu wiersza polecenia platformy Azure lub szablonu Bicep.
Przekazywanie schematu za pomocą interfejsu wiersza polecenia
Grupa poleceń az iot ops schema zawiera polecenia służące do tworzenia, wyświetlania schematów i zarządzania nimi w rejestrze schematów.
Schemat można przekazać, odwołując się do pliku JSON lub dołączając schemat jako zawartość śródliniową.
W poniższym przykładzie użyto minimalnych danych wejściowych do utworzenia schematu wywoływanego myschema z pliku. Jeśli nie określono numeru wersji, wersja schematu to 1.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format json --type message --version-content myschema.json
Poniższy przykład tworzy schemat wywoływany myschema z zawartości wbudowanej i przypisuje numer wersji.
az iot ops schema create -n myschema -g myresourcegroup --registry myregistry --format delta --type message --version-content '{\"hello\": \"world\"}' --ver 14
Napiwek
Jeśli nie znasz nazwy rejestru, użyj schema registry list polecenia , aby wykonać zapytanie dotyczące tej nazwy. Na przykład:
az iot ops schema registry list -g myresourcegroup --query "[].{Name:name}" -o tsv
Po zakończeniu create wykonywania polecenia w kontenerze konta magazynu powinien zostać wyświetlony obiekt blob z zawartością schematu. Nazwa obiektu blob ma format schema-namespace/schema/version.
Więcej opcji można wyświetlić za pomocą polecenia az iot ops schema -hpomocnika .
Przekazywanie schematu przy użyciu szablonu Bicep
Utwórz plik Bicep .bicep i dodaj do niego zawartość schematu u góry jako zmienną. Ten przykład jest schematem różnicowym odpowiadającym danym OPC UA z przewodnika Szybki start.
// 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": {}
}
]
}
}
'''
Następnie w tym samym pliku tuż pod schematem zdefiniuj zasób schematu wraz ze wskaźnikami do istniejącego zasobu rejestru schematów, który pochodzi z wdrażania operacji usługi 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
}
}
Po zdefiniowaniu zawartości schematu i zasobów można wdrożyć szablon Bicep, aby utworzyć schemat w rejestrze schematów.
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep