Co jsou výrazy cesty jq v Azure IoT Data Processor Preview?
Důležité
Azure IoT Operations Preview – Služba Azure Arc je aktuálně ve verzi PREVIEW. Tento software ve verzi Preview byste neměli používat v produkčních prostředích.
Právní podmínky, které platí pro funkce Azure, které jsou ve verzi beta, verzi Preview nebo které zatím nejsou veřejně dostupné, najdete v Dodatečných podmínkách použití pro Microsoft Azure verze Preview.
Mnoho fází kanálu v Azure IoT Data Processor Preview využívá výrazy cest jq. Pokaždé, když potřebujete načíst informace ze zprávy nebo umístit nějaké informace do zprávy, použijte cestu. Cesty jq umožňují:
- Vyhledejte část informací ve zprávě.
- Určete, kam umístit informace do zprávy.
Oba případy používají stejnou syntaxi a určují umístění vzhledem ke kořenové struktuře zprávy.
Cesty jq podporované zpracovatelem dat jsou syntakticky správné pro jq, ale mají zjednodušenou sémantiku, aby se usnadnilo jejich používání a pomohlo snížit chyby v pipleline zpracovatele dat. Konkrétně zpracovatel dat nepoužívá ? syntaxi k potlačení chyb u chybně zarovnaných datových struktur. Tyto chyby jsou při práci s cestami automaticky potlačeny.
Příklady přístupu k datům v rámci kanálu zpracovatele dat zahrnují inputPath agregační a poslední známé fáze hodnot. Vzor přístupu k datům použijte vždy, když potřebujete získat přístup k některým datům ve zprávě zpracovatele dat.
Aktualizace dat používá stejnou syntaxi jako přístup k datům, ale v konkrétních scénářích aktualizace existují určitá zvláštní chování. Mezi příklady aktualizace dat v rámci kanálu zpracovatele dat patří outputPath fáze agregace a poslední známé fáze kanálu hodnot . Vzor aktualizace dat použijte vždy, když potřebujete umístit výsledek operace do zprávy Zpracovatel dat.
Poznámka:
Zpráva zpracovatele dat obsahuje víc než jen text zprávy. Zpráva zpracovatele dat obsahuje všechny vlastnosti a metadata, která jste odeslali, a další relevantní systémové informace. Primární datová část obsahující data odesílaná do kanálu zpracování se umístí do payload pole v kořenovém adresáři zprávy. Proto mnoho příkladů v této příručce obsahuje cesty, které začínají .payload.
Syntaxe
Každá cesta jq se skládá z posloupnosti jednoho nebo více následujících segmentů:
- Kořenová cesta:
.. - Pole v mapě nebo objektu, které používá jednu z těchto možností:
.<identifier>pro alfanumerické klíče objektů. Například.temperature.."<identifier>"pro libovolné klíče objektů. Například."asset-id".["<identifier>"]nebo libovolné klíče objektů. Například["asset-id"].
- Index pole:
[<index>]. Například[2].
Cesty musí vždy začínat na .. I když máte na začátku cesty klíč mapování pole nebo komplexního objektu, musí existovat . před ním. Cesty .["complex-key"] a .[1].value jsou platné. Cesty ["complex-key"] a [1].value jsou neplatné.
Ukázková zpráva
Následující příklady přístupu k datům a aktualizací dat používají následující zprávu k ilustraci použití různých výrazů cesty:
{
"systemProperties": {
"partitionKey": "slicer-3345",
"partitionId": 5,
"timestamp": "2023-01-11T10:02:07Z"
},
"qos": 1,
"topic": "assets/slicer-3345",
"properties": {
"responseTopic": "assets/slicer-3345/output",
"contentType": "application/json"
},
"payload": {
"Timestamp": 1681926048,
"Payload": {
"dtmi:com:prod1:slicer3345:humidity": {
"sourceTimestamp": 1681926048,
"value": 10
},
"dtmi:com:prod1:slicer3345:lineStatus": {
"sourceTimestamp": 1681926048,
"value": [1, 5, 2]
},
"dtmi:com:prod1:slicer3345:speed": {
"sourceTimestamp": 1681926048,
"value": 85
},
"dtmi:com:prod1:slicer3345:temperature": {
"sourceTimestamp": 1681926048,
"value": 46
}
},
"DataSetWriterName": "slicer-3345",
"SequenceNumber": 461092
}
}
Kořenová cesta pro přístup k datům
Nejzásadnější cestou je kořenová cesta, která odkazuje na kořen zprávy a vrací celou zprávu. Vzhledem k následující cestě jq:
.
Výsledkem je:
{
"systemProperties": {
"partitionKey": "slicer-3345",
"partitionId": 5,
"timestamp": "2023-01-11T10:02:07Z"
},
"qos": 1,
"topic": "assets/slicer-3345",
"properties": {
"responseTopic": "assets/slicer-3345/output",
"contentType": "application/json"
},
"payload": {
"Timestamp": 1681926048,
"Payload": {
"dtmi:com:prod1:slicer3345:humidity": {
"sourceTimestamp": 1681926048,
"value": 10
},
"dtmi:com:prod1:slicer3345:lineStatus": {
"sourceTimestamp": 1681926048,
"value": [1, 5, 2]
},
"dtmi:com:prod1:slicer3345:speed": {
"sourceTimestamp": 1681926048,
"value": 85
},
"dtmi:com:prod1:slicer3345:temperature": {
"sourceTimestamp": 1681926048,
"value": 46
}
},
"DataSetWriterName": "slicer-3345",
"SequenceNumber": 461092
}
}
Jednoduchý identifikátor pro přístup k datům
Další nejjednodušší cesta zahrnuje jeden identifikátor, v tomto případě payload pole. Vzhledem k následující cestě jq:
.payload
Tip
."payload" a .["payload"] jsou také platné způsoby zadání této cesty. Identifikátory, které obsahují a-zpouze , A-Z0-9 a _ nevyžadují složitější syntaxi.
Výsledkem je:
{
"Timestamp": 1681926048,
"Payload": {
"dtmi:com:prod1:slicer3345:humidity": {
"SourceTimestamp": 1681926048,
"Value": 10
},
"dtmi:com:prod1:slicer3345:lineStatus": {
"SourceTimestamp": 1681926048,
"Value": [1, 5, 2]
},
"dtmi:com:prod1:slicer3345:speed": {
"SourceTimestamp": 1681926048,
"Value": 85
},
"dtmi:com:prod1:slicer3345:temperature": {
"SourceTimestamp": 1681926048,
"Value": 46
}
},
"DataSetWriterName": "slicer-3345",
"SequenceNumber": 461092
}
Vnořená pole pro přístup k datům
Segmenty cesty můžete zkombinovat a načíst data vnořená hluboko do zprávy, například jednu hodnotu typu list. Na základě jedné z následujících dvou cest jq:
.payload.Payload.["dtmi:com:prod1:slicer3345:temperature"].Value
.payload.Payload."dtmi:com:prod1:slicer3345:temperature".Value
Výsledkem je:
46
Prvky pole pro přístup k datům
Prvky pole fungují stejným způsobem jako klíče mapování s tím rozdílem, že v řetězci[] použijete číslo. Na základě jedné z následujících dvou cest jq:
.payload.Payload.["dtmi:com:prod1:slicer3345:lineStatus"].Value[1]
.payload.Payload."dtmi:com:prod1:slicer3345:lineStatus".Value[1]
Výsledkem je:
5
Neexistující a neplatné cesty v přístupu k datům
Pokud cesta jq identifikuje umístění, které neexistuje nebo není kompatibilní se strukturou zprávy, nebude vrácena žádná hodnota.
Důležité
Některé fáze zpracování vyžadují, aby byla k dispozici určitá hodnota a pokud se nenašla žádná hodnota, může selhat. Ostatní jsou navrženy tak, aby pokračovaly ve zpracování normálně a buď přeskočí požadovanou operaci, nebo pokud se v cestě nenajde žádná hodnota, proveďte jinou akci.
Vzhledem k následující cestě jq:
.payload[1].temperature
Výsledkem je:
Žádná hodnota
Kořenová cesta pro aktualizaci dat
Nejzásadnější cestou je kořenová cesta, která odkazuje na kořen zprávy a nahrazuje celou zprávu. Vzhledem k následující nové hodnotě pro vložení a cestu jq:
{ "update": "data" }
.
Výsledkem je:
{ "update": "data" }
Aktualizace nejsou hluboko sloučeny s předchozími daty, ale místo toho nahraďte data na úrovni, ve které se aktualizace provede. Pokud se chcete vyhnout přepsání dat, nastavte obor aktualizace na nejžádnější cestu, kterou chcete změnit nebo aktualizovat samostatné pole na stranu primárních dat.
Jednoduchý identifikátor aktualizace dat
Další nejjednodušší cesta zahrnuje jeden identifikátor, v tomto případě payload pole. Vzhledem k následující nové hodnotě pro vložení a cestu jq:
{ "update": "data" }
.payload
Tip
."payload" a .["payload"] jsou také platné způsoby zadání této cesty. Identifikátory, které obsahují a-zpouze , A-Z0-9 a _ nevyžadují složitější syntaxi.
Výsledkem je:
{
"systemProperties": {
"partitionKey": "slicer-3345",
"partitionId": 5,
"timestamp": "2023-01-11T10:02:07Z"
},
"qos": 1,
"topic": "assets/slicer-3345",
"properties": {
"responseTopic": "assets/slicer-3345/output",
"contentType": "application/json"
},
"payload": { "update": "data" }
}
Vnořená pole pro aktualizaci dat
Segmenty cesty můžete zkombinovat a načíst data vnořená hluboko do zprávy, například jednu hodnotu typu list. Pokud chcete vložit následující novou hodnotu, a jednu z následujících dvou cest jq:
{ "update": "data" }
.payload.Payload.["dtmi:com:prod1:slicer3345:temperature"].Value
.payload.Payload."dtmi:com:prod1:slicer3345:temperature".Value
Výsledkem je:
{
"systemProperties": {
"partitionKey": "slicer-3345",
"partitionId": 5,
"timestamp": "2023-01-11T10:02:07Z"
},
"qos": 1,
"topic": "assets/slicer-3345",
"properties": {
"responseTopic": "assets/slicer-3345/output",
"contentType": "application/json"
},
"payload": {
"Timestamp": 1681926048,
"Payload": {
"dtmi:com:prod1:slicer3345:humidity": {
"sourceTimestamp": 1681926048,
"value": 10
},
"dtmi:com:prod1:slicer3345:lineStatus": {
"sourceTimestamp": 1681926048,
"value": [1, 5, 2]
},
"dtmi:com:prod1:slicer3345:speed": {
"sourceTimestamp": 1681926048,
"value": 85
},
"dtmi:com:prod1:slicer3345:temperature": {
"sourceTimestamp": 1681926048,
"value": { "update": "data" }
}
},
"DataSetWriterName": "slicer-3345",
"SequenceNumber": 461092
}
}
Prvky pole pro aktualizaci dat
Prvky pole fungují stejným způsobem jako klíče mapování s tím rozdílem, že v řetězci[] použijete číslo. Pokud chcete vložit následující novou hodnotu, a jednu z následujících dvou cest jq:
{ "update": "data" }
.payload.Payload.["dtmi:com:prod1:slicer3345:lineStatus"].Value[1]
.payload.Payload."dtmi:com:prod1:slicer3345:lineStatus".Value[1]
Výsledkem je:
{
"systemProperties": {
"partitionKey": "slicer-3345",
"partitionId": 5,
"timestamp": "2023-01-11T10:02:07Z"
},
"qos": 1,
"topic": "assets/slicer-3345",
"properties": {
"responseTopic": "assets/slicer-3345/output",
"contentType": "application/json"
},
"payload": {
"Timestamp": 1681926048,
"Payload": {
"dtmi:com:prod1:slicer3345:humidity": {
"sourceTimestamp": 1681926048,
"value": 10
},
"dtmi:com:prod1:slicer3345:lineStatus": {
"sourceTimestamp": 1681926048,
"value": [1, { "update": "data" }, 2]
},
"dtmi:com:prod1:slicer3345:speed": {
"sourceTimestamp": 1681926048,
"value": 85
},
"dtmi:com:prod1:slicer3345:temperature": {
"sourceTimestamp": 1681926048,
"value": 46
}
},
"DataSetWriterName": "slicer-3345",
"SequenceNumber": 461092
}
}
Neexistující cesty a cesty neshody typů v aktualizaci dat
Pokud cesta jq identifikuje umístění, které neexistuje nebo není kompatibilní se strukturou zprávy, použije se následující sémantika:
- Pokud některé segmenty cesty neexistují, vytvoří se:
- U klíčů objektů se klíč přidá do objektu.
- U indexů pole se pole prodloužuje hodnotami
null, aby bylo dostatečně dlouhé, aby měl požadovaný index, a pak se index aktualizuje. - U záporných indexů pole se provede stejná procedura prodloužení, ale první prvek se nahradí.
- Pokud má segment cesty jiný typ než to, co potřebuje, výraz změní typ a zahodí všechna existující data v tomto umístění cesty.
Následující příklady používají stejnou vstupní zprávu jako předchozí příklady a vloží následující novou hodnotu:
{ "update": "data" }
Vzhledem k následující cestě jq:
.payload[1].temperature
Výsledkem je:
{
"systemProperties": {
"partitionKey": "slicer-3345",
"partitionId": 5,
"timestamp": "2023-01-11T10:02:07Z"
},
"qos": 1,
"topic": "assets/slicer-3345",
"properties": {
"responseTopic": "assets/slicer-3345/output",
"contentType": "application/json"
},
"payload": [null, { "update": "data" }]
}
Vzhledem k následující cestě jq:
.payload.nested.additional.data
Výsledkem je:
{
"systemProperties": {
"partitionKey": "slicer-3345",
"partitionId": 5,
"timestamp": "2023-01-11T10:02:07Z"
},
"qos": 1,
"topic": "assets/slicer-3345",
"properties": {
"responseTopic": "assets/slicer-3345/output",
"contentType": "application/json"
},
"payload": {
"Timestamp": 1681926048,
"Payload": {
"dtmi:com:prod1:slicer3345:humidity": {
"sourceTimestamp": 1681926048,
"value": 10
},
"dtmi:com:prod1:slicer3345:lineStatus": {
"sourceTimestamp": 1681926048,
"value": [1, 5, 2]
},
"dtmi:com:prod1:slicer3345:speed": {
"sourceTimestamp": 1681926048,
"value": 85
},
"dtmi:com:prod1:slicer3345:temperature": {
"sourceTimestamp": 1681926048,
"value": 46
}
},
"DataSetWriterName": "slicer-3345",
"SequenceNumber": 461092,
"nested": {
"additional": {
"data": { "update": "data" }
}
}
}
}
Vzhledem k následující cestě jq:
.systemProperties.partitionKey[-4]
Výsledkem je:
{
"systemProperties": {
"partitionKey": [{"update": "data"}, null, null, null],
"partitionId": 5,
"timestamp": "2023-01-11T10:02:07Z"
},
"qos": 1,
"topic": "assets/slicer-3345",
"properties": {
"responseTopic": "assets/slicer-3345/output",
"contentType": "application/json"
},
"payload": {
"Timestamp": 1681926048,
"Payload": {
"dtmi:com:prod1:slicer3345:humidity": {
"sourceTimestamp": 1681926048,
"value": 10
},
"dtmi:com:prod1:slicer3345:lineStatus": {
"sourceTimestamp": 1681926048,
"value": [1, 5, 2]
},
"dtmi:com:prod1:slicer3345:speed": {
"sourceTimestamp": 1681926048,
"value": 85
},
"dtmi:com:prod1:slicer3345:temperature": {
"sourceTimestamp": 1681926048,
"value": 46
}
},
"DataSetWriterName": "slicer-3345",
"SequenceNumber": 461092,
}
Související obsah
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro