Spłaszczanie danych JSON, ucieczka i obsługa tablic

Artykuł
06/14/2024

Uwaga

Usługa Time Series Insights zostanie wycofana 7 lipca 2024 r. Rozważ migrację istniejących środowisk do alternatywnych rozwiązań tak szybko, jak to możliwe. Aby uzyskać więcej informacji na temat wycofywania i migracji, odwiedź naszą dokumentację.

Środowisko usługi Azure Time Series Insights Gen2 dynamicznie tworzy kolumny ciepłych i zimnych magazynów zgodnie z określonym zestawem konwencji nazewnictwa. Po pozyskiwaniu zdarzenia zestaw reguł jest stosowany do ładunku JSON i nazw właściwości. Obejmują one ucieczkę niektórych znaków specjalnych i spłaszczanie zagnieżdżonych obiektów JSON. Ważne jest, aby znać te reguły, aby zrozumieć, w jaki sposób kształt kodu JSON będzie miał wpływ na sposób przechowywania zdarzeń i wykonywania zapytań. Zapoznaj się z poniższą tabelą, aby uzyskać pełną listę reguł. Przykłady A i B pokazują również, jak można wydajnie wsadować wiele szeregów czasowych w tablicy.

Ważne

Zapoznaj się z poniższymi regułami przed wybraniem właściwości identyfikatora szeregów czasowych i/lub znacznikiem czasu źródła zdarzeń propert(ies). Jeśli identyfikator lub sygnatura czasowa TS znajduje się w zagnieżdżonym obiekcie lub ma co najmniej jeden znak specjalny poniżej, należy upewnić się, że podana nazwa właściwości jest zgodna z nazwą kolumny po zastosowaniu reguł pozyskiwania. Zobacz przykład B poniżej.

Reguła	Przykładowy kod JSON	Składnia wyrażenia szeregów czasowych	Nazwa kolumny właściwości w Parquet
Typ danych usługi Azure Time Series Insights Gen2 jest dołączany na końcu nazwy kolumny jako "_<dataType>"	`"type": "Accumulated Heat"`	`$event.type.String`	`type_string`
Właściwość sygnatury czasowej źródła zdarzeń zostanie zapisana w usłudze Azure Time Series Insights Gen2 jako "sygnatura czasowa" w magazynie i wartość przechowywana w formacie UTC. Możesz dostosować właściwość sygnatury czasowej źródeł zdarzeń, aby zaspokoić potrzeby rozwiązania, ale nazwa kolumny w ciepłym i zimnym magazynie to "sygnatura czasowa". Inne właściwości JSON daty/godziny, które nie są znacznikiem czasu źródła zdarzeń, zostaną zapisane za pomocą ciągu "_datetime" w nazwie kolumny, jak wspomniano w powyższej regule.	`"ts": "2020-03-19 14:40:38.318"`	`$event.$ts`	`timestamp`
Nazwy właściwości JSON, które zawierają znaki specjalne. [ \ i ' są ucieczki przy użyciu [" i "]	`"id.wasp": "6A3090FD337DE6B"`	`$event['id.wasp'].String`	`['id.wasp']_string`
W ciągu [" i "] istnieje dodatkowe ucieczki od pojedynczych cudzysłowów i ukośników odwrotnych. Pojedynczy cudzysłów zostanie zapisany jako \" i ukośnik odwrotny zostanie zapisany jako \\	`"Foo's Law Value": "17.139999389648"`	`$event['Foo\'s Law Value'].Double`	`['Foo\'s Law Value']_double`
Zagnieżdżone obiekty JSON są spłaszczone kropką jako separatorem. Zagnieżdżanie do 10 poziomów jest obsługiwane.	`"series": {"value" : 316 }`	`$event.series.value.Long`lub `$event['series']['value'].Long$event.series['value'].Long`	`series.value_long`
Tablice typów pierwotnych są przechowywane jako typ dynamiczny	`"values": [154, 149, 147]`	Typy dynamiczne można pobierać tylko za pośrednictwem interfejsu API GetEvents	`values_dynamic`
Tablice zawierające obiekty mają dwa zachowania w zależności od zawartości obiektu: Jeśli identyfikatory TS lub właściwości sygnatury czasowej znajdują się w obiektach w tablicy, tablica zostanie wyrejestrowana tak, aby początkowy ładunek JSON generuje wiele zdarzeń. Dzięki temu można podzielić wiele zdarzeń na jedną strukturę JSON. Wszystkie właściwości najwyższego poziomu, które są elementami równorzędnymi do tablicy, zostaną zapisane przy użyciu każdego obiektu wyrejestrowanego. Jeśli identyfikatory TS i sygnatura czasowa nie znajdują się w tablicy, zostaną zapisane jako typ dynamiczny.	Zobacz przykłady A, B i C poniżej
Tablice zawierające elementy mieszane nie są spłaszczone.	`"values": ["foo", {"bar" : 149}, 147]`	Typy dynamiczne można pobierać tylko za pośrednictwem interfejsu API GetEvents	`values_dynamic`
Limit nazw właściwości JSON to 512 znaków. Jeśli nazwa przekracza 512 znaków, zostanie obcięta do 512, a element "_<'hashCode>" zostanie dołączony. Należy pamiętać , że dotyczy to również nazw właściwości połączonych z spłaszczonego obiektu, oznaczając zagnieżdżonych ścieżki obiektu.	`"data.items.datapoints.values.telemetry<...continuing to over 512 chars>" : 12.3440495`	`"$event.data.items.datapoints.values.telemetry<...continuing to include all chars>.Double"`	`data.items.datapoints.values.telemetry<...continuing to 512 chars>_912ec803b2ce49e4a541068d495ab570_double`

Opis podwójnego zachowania tablic

Tablice obiektów będą przechowywane w całości lub podzielone na wiele zdarzeń w zależności od sposobu modelowania danych. Dzięki temu można używać tablicy do przetwarzania zdarzeń wsadowych i unikać powtarzania właściwości telemetrii zdefiniowanych na poziomie obiektu głównego. Przetwarzanie wsadowe może być korzystne, ponieważ powoduje to wysłanie mniejszej liczby komunikatów usługi Event Hubs lub usługi IoT Hub.

Jednak w niektórych przypadkach tablice zawierające obiekty mają znaczenie tylko w kontekście innych wartości. Utworzenie wielu zdarzeń spowoduje renderowanie danych bez znaczenia. Aby upewnić się, że tablica obiektów jest przechowywana jako typ dynamiczny, postępuj zgodnie z poniższymi wskazówkami dotyczącymi modelowania danych i zapoznaj się z przykładem C

Jak sprawdzić, czy moja tablica obiektów będzie generować wiele zdarzeń

Jeśli co najmniej jedna właściwość identyfikatora szeregów czasowych jest zagnieżdżona w obiektach w tablicy lub jeśli właściwość sygnatury czasowej źródła zdarzeń jest zagnieżdżona, aparat pozyskiwania podzieli go, aby utworzyć wiele zdarzeń. Nazwy właściwości podane dla identyfikatorów TS i/lub znacznika czasu powinny być zgodne z powyższymi regułami spłaszczania i dlatego będą wskazywać kształt kodu JSON. Zapoznaj się z poniższymi przykładami i zapoznaj się z przewodnikiem dotyczącym wybierania właściwości Identyfikator szeregów czasowych.

Przykład A

Identyfikator szeregów czasowych w katalogu głównym obiektu i zagnieżdżony znacznik czasu
Identyfikator szeregów czasowych środowiska: "id"
Sygnatura czasowa źródła zdarzeń: "values.time"
Ładunek JSON:

[
    {
        "id": "caaae533-1d6c-4f58-9b75-da102bcc2c8c",
        "values": [
            {
                "time": "2020-05-01T00:59:59.000Z",
                "value": 25.6073
            },
            {
                "time": "2020-05-01T01:00:29.000Z",
                "value": 43.9077
            }
        ]
    },
    {
        "id": "1ac87b74-0865-4a07-b512-56602a3a576f",
        "values": [
            {
                "time": "2020-05-01T00:59:59.000Z",
                "value": 0.337288
            },
            {
                "time": "2020-05-01T01:00:29.000Z",
                "value": 4.76562
            }
        ]
    }
]

Wynik w pliku Parquet:
Powyższa konfiguracja i ładunek spowodują wygenerowanie trzech kolumn i czterech zdarzeń

timestamp	id_string	values.value_double
`2020-05-01T00:59:59.000Z`	`caaae533-1d6c-4f58-9b75-da102bcc2c8c`	`25.6073`
`2020-05-01T01:00:29.000Z`	`caaae533-1d6c-4f58-9b75-da102bcc2c8c`	`43.9077`
`2020-05-01T00:59:59.000Z`	`1ac87b74-0865-4a07-b512-56602a3a576f`	`0.337288`
`2020-05-01T01:00:29.000Z`	`1ac87b74-0865-4a07-b512-56602a3a576f`	`4.76562`

Przykład B

Identyfikator złożonej serii czasowej z jedną zagnieżdżonym właściwością
Identyfikator szeregów czasowych środowiska: "plantId" i "telemetry.tagId"
Sygnatura czasowa źródła zdarzeń: "timestamp"
Ładunek JSON:

[
    {
        "plantId": "9336971",
        "timestamp": "2020-01-22T16:38:09Z",
        "telemetry": [
            {
                "tagId": "100231-A-A6",
                "tagValue": -31.149018
            },
            {
                "tagId": "100231-A-A1",
                "tagValue": 20.560796
            },
            {
                "tagId": "100231-A-A9",
                "tagValue": 177
            },
            {
                "tagId": "100231-A-A8",
                "tagValue": 420
            },
        ]
    },
    {
        "plantId": "9336971",
        "timestamp": "2020-01-22T16:42:14Z",
        "telemetry": [
            {
                "tagId": "103585-A-A7",
                "value": -30.9918
            },
            {
                "tagId": "103585-A-A4",
                "value": 19.960796
            }
        ]
    }
]

Wynik w pliku Parquet:
Powyższa konfiguracja i ładunek spowodują wygenerowanie czterech kolumn i sześciu zdarzeń

timestamp	plantId_string	telemetry.tagId_string	telemetry.value_double
`2020-01-22T16:38:09Z`	`9336971`	`100231-A-A6`	-31.149018
`2020-01-22T16:38:09Z`	`9336971`	`100231-A-A1`	20.560796
`2020-01-22T16:38:09Z`	`9336971`	`100231-A-A9`	177
`2020-01-22T16:38:09Z`	`9336971`	`100231-A-A8`	420
`2020-01-22T16:42:14Z`	`9336971`	`100231-A-A7`	-30.9918
`2020-01-22T16:42:14Z`	`9336971`	`100231-A-A4`	19.960796

Przykład C

Identyfikator szeregów czasowych i znacznik czasu znajdują się w katalogu głównym obiektu
Identyfikator szeregów czasowych środowiska: "id"
Sygnatura czasowa źródła zdarzeń: "timestamp"
Ładunek JSON:

{
    "id": "800500054755",
    "timestamp": "2020-11-01T10:00:00.000Z",
    "datapoints": [{
            "value": 120
        },
        {
            "value": 124
        }
    ]
}

Wynik w pliku Parquet:
Powyższa konfiguracja i ładunek będą generować trzy kolumny i jedno zdarzenie

timestamp	id_string	datapoints_dynamic
`2020-11-01T10:00:00.000Z`	`800500054755`	`[{"value": 120},{"value":124}]`

Następne kroki

Omówienie ograniczeń przepływności środowiska

Udostępnij za pośrednictwem