Spłaszczanie, ucieczka i obsługa tablic w formacie JSON

Artykuł
01/21/2021

Notatka

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 zaniechania i migracji, zapoznaj się z 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 wprowadzeniu zdarzenia, zestaw reguł jest stosowany do danych 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 & B pokazują również, jak można wydajnie wsadować wiele szeregów czasowych w tablicy.

Ważny

Zapoznaj się z poniższymi regułami przed wybraniem właściwości identyfikatora szeregów czasowych i/lub właściwości znacznika czasu dla źródła zdarzeń . Jeśli identyfikator TS lub znacznik czasu znajduje się w zagnieżdżonym obiekcie lub ma co najmniej jeden ze specjalnych znaków 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`
Źródło zdarzeń właściwość znacznika czasu zostanie zapisana w usłudze Azure Time Series Insights Gen2 jako "znacznik czasu" w magazynie, a wartość będzie przechowywana w UTC. Możesz konfigurować właściwość znacznika czasu źródeł zdarzeń, aby zaspokoić potrzeby rozwiązania, ale nazwa kolumny w pamięci ciepłej i zimnej to "znacznik czasu". 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ą escapowane przy użyciu [' i ']	`"id.wasp": "6A3090FD337DE6B"`	`$event['id.wasp'].String`	`['id.wasp']_string`
W obrębie [' i '] następuje dodatkowe escape apostrofów i ukośników odwrotnych. Pojedynczy cudzysłów zostanie zapisany jako \’ i backslash 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łaszczane przy użyciu kropki jako separatora. Zagnieżdżanie do 10 poziomów jest obsługiwane.	`"series": {"value" : 316 }`	`$event.series.value.Long`, `$event['series']['value'].Long` lub `$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 rozwinięta tak, aby początkowe dane JSON generowały 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 są , a nie, w tablicy, to zostaną zapisane w całości jako typ dynamiczny.	Zobacz przykłady A, Bi 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 i "_<"hashCode">" jest dołączana. Uwaga, że dotyczy to również nazw właściwości uzyskanych z obiektu spłaszczonego, co oznacza zagnieżdżoną ścieżkę 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`

Zrozumienie 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ń w paczkach i unikać powtarzania właściwości telemetrii zdefiniowanych na poziomie głównego obiektu. Przetwarzanie wsadowe może być korzystne, ponieważ prowadzi do wysłania mniejszej liczby komunikatów z usługi Event Hubs lub IoT Hub.

Jednak w niektórych przypadkach tablice zawierające obiekty mają znaczenie tylko w kontekście innych wartości. Utworzenie wielu zdarzeń spowoduje, że dane staną się bez znaczenia. Aby upewnić się, że tablica obiektów jest przechowywana as-is jako typ dynamiczny, postępuj zgodnie ze wskazówkami dotyczącymi modelowania danych poniżej i zapoznaj się z Przykład 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, które podałeś dla identyfikatorów TS i/lub timestampu, powinny być zgodne z powyższymi regułami spłaszczania, a zatem będą wskazywać kształt twojego JSON-a. Zapoznaj się z poniższymi przykładami i zapoznaj się z przewodnikiem dotyczącym wybierania właściwości identyfikatora szeregów czasowych.

Przykład A

Identyfikator szeregów czasowych w katalogu głównym obiektu i zagnieżdżony znacznik czasu
ID szeregów czasowych środowiskowych :"id"
znacznik czasu źródła zdarzenia :"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ń

Sygnatura czasowa	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żoną właściwością
identyfikator szeregów czasowych środowiska :"plantId" i "telemetry.tagId"
Znacznik czasu źródła zdarzenia :"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ń

Znacznik czasu	plantId_string	telemetry.tagId_string	telemetry.wartość_doublowa
`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 korzeniu obiektu
identyfikator szeregów czasowych środowiska :"id"
Znak czasu źródła zdarzenia: "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

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

Następne kroki

Zrozumienie ograniczeń przepływności środowiska

Udostępnij za pośrednictwem