Simplificação, Escape e Processamento de Matriz do JSON

Artigo
10/26/2023

Nota

O serviço Time Series Insights (TSI) deixará de ser suportado após março de 2025. Ponderar, o mais rapidamente possível, a migração dos ambientes ETI existentes para soluções alternativas. Para obter mais informações sobre a substituição e migração, visite nossa documentação.

Seu ambiente do Azure Time Series Insights Gen2 criará dinamicamente as colunas de suas lojas quentes e frias, seguindo um conjunto específico de convenções de nomenclatura. Quando um evento é ingerido, um conjunto de regras é aplicado à carga JSON e aos nomes de propriedade. Isso inclui escapar de certos caracteres especiais e nivelar objetos JSON aninhados. É importante conhecer essas regras para que você entenda como a forma do seu JSON influenciará como seus eventos são armazenados e consultados. Consulte a tabela abaixo para obter a lista completa de regras. Os exemplos A & B também demonstram como você é capaz de agrupar com eficiência várias séries temporais em uma matriz.

Importante

Analise as regras abaixo antes de selecionar uma propriedade ID de Série Temporal e/ou a(s) propriedade(s) de carimbo de data/hora da origem do evento. Se o ID TS ou carimbo de data/hora estiver dentro de um objeto aninhado ou tiver um ou mais caracteres especiais abaixo, é importante garantir que o nome da propriedade fornecido corresponda ao nome da coluna após a aplicação das regras de ingestão. Ver exemplo B abaixo.

Regra	Exemplo JSON	Sintaxe da expressão de séries temporais	Nome da coluna da propriedade no Parquet
O tipo de dados Azure Time Series Insights Gen2 é anexado ao final do nome da coluna como "_<dataType>"	`"type": "Accumulated Heat"`	`$event.type.String`	`type_string`
A propriedade timestamp de origem do evento será salva no Azure Time Series Insights Gen2 como "carimbo de data/hora" no armazenamento e o valor armazenado em UTC. Você pode personalizar a propriedade de carimbo de data/hora da(s) fonte(s) do evento para atender às necessidades da sua solução, mas o nome da coluna no armazenamento quente e frio é "carimbo de data/hora". Outras propriedades JSON datetime que não são o carimbo de data/hora de origem do evento serão salvas com "_datetime" no nome da coluna, conforme mencionado na regra acima.	`"ts": "2020-03-19 14:40:38.318"`	`$event.$ts`	`timestamp`
Nomes de propriedade JSON que incluem os caracteres especiais. [ \ e ' são escapados usando [' e ']	`"id.wasp": "6A3090FD337DE6B"`	`$event['id.wasp'].String`	`['id.wasp']_string`
Dentro de [' e '] há fuga adicional de aspas simples e barras invertidas. Uma única citação será escrita como \' e uma barra invertida será escrita como \\	`"Foo's Law Value": "17.139999389648"`	`$event['Foo\'s Law Value'].Double`	`['Foo\'s Law Value']_double`
Os objetos JSON aninhados são nivelados com um ponto como separador. Há suporte para aninhamento de até 10 níveis.	`"series": {"value" : 316 }`	`$event.series.value.Long`, `$event['series']['value'].Long` ou `$event.series['value'].Long`	`series.value_long`
Matrizes de tipos primitivos são armazenadas como o tipo dinâmico	`"values": [154, 149, 147]`	Os tipos dinâmicos só podem ser recuperados por meio da API GetEvents	`values_dynamic`
As matrizes que contêm objetos têm dois comportamentos, dependendo do conteúdo do objeto: Se a(s) ID(s) TS ou a(s) propriedade(s) de carimbo de data/hora estiverem dentro dos objetos em uma matriz, a matriz será desenrolada de forma que a carga JSON inicial produza vários eventos. Isso permite que você agrupe vários eventos em uma estrutura JSON. Todas as propriedades de nível superior que são pares à matriz serão salvas com cada objeto não rolado. Se o(s) seu(s) ID(s) TS e o carimbo de data/hora não estiverem dentro da matriz, ele será salvo inteiro como o tipo Dinâmico.	Veja os exemplos A, B e C abaixo
As matrizes que contêm elementos mistos não são achatadas.	`"values": ["foo", {"bar" : 149}, 147]`	Os tipos dinâmicos só podem ser recuperados por meio da API GetEvents	`values_dynamic`
512 caracteres é o limite de nome da propriedade JSON. Se o nome exceder 512 caracteres, ele será truncado para 512 e '_<'hashCode''> será acrescentado. Observe que isso também se aplica a nomes de propriedade que foram concatenados a partir de objeto nivelado, denotando um caminho de objeto aninhado.	`"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`

Entendendo o comportamento duplo para arrays

As matrizes de objetos serão armazenadas inteiras ou divididas em vários eventos, dependendo de como você modelou seus dados. Isso permite que você use uma matriz para eventos em lote e evite repetir propriedades de telemetria definidas no nível do objeto raiz. O envio em lote pode ser vantajoso, pois resulta em menos mensagens enviadas por Hubs de Eventos ou Hub IoT.

No entanto, em alguns casos, matrizes contendo objetos só são significativas no contexto de outros valores. A criação de vários eventos tornaria os dados sem sentido. Para garantir que uma matriz de objetos seja armazenada como um tipo dinâmico, siga as diretrizes de modelagem de dados abaixo e dê uma olhada no Exemplo C

Como saber se minha matriz de objetos produzirá vários eventos

Se uma ou mais de suas propriedades de ID de Série Temporal estiverem aninhadas em objetos em uma matriz, ou se sua propriedade de carimbo de data/hora de origem do evento estiver aninhada, o mecanismo de ingestão a dividirá para criar vários eventos. Os nomes de propriedade que você forneceu para o(s) seu(s) ID(s) TS e/ou carimbo de data/hora devem seguir as regras de nivelamento acima e, portanto, indicarão a forma do seu JSON. Veja os exemplos abaixo e confira o guia sobre como selecionar uma propriedade de ID de série temporal.

Exemplo A

ID da série temporal na raiz do objeto e carimbo de data/hora aninhado
ID da série temporal do ambiente:"id"
Carimbo de data/hora de origem do evento:"values.time"
Carga útil 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
            }
        ]
    }
]

Resultado no arquivo Parquet:
A configuração e a carga útil acima produzirão três colunas e quatro eventos

carimbo de data/hora	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`

Exemplo B

ID de série temporal composta com uma propriedade aninhada
ID da série temporal do ambiente:"plantId" e "telemetry.tagId"
Carimbo de data/hora de origem do evento:"timestamp"
Carga útil 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
            }
        ]
    }
]

Resultado no arquivo Parquet:
A configuração e a carga útil acima produzirão quatro colunas e seis eventos

carimbo de data/hora	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

Exemplo C

O ID da série temporal e o carimbo de data/hora estão na raiz do objeto
ID da série temporal do ambiente:"id"
Carimbo de data/hora de origem do evento:"timestamp"
Carga útil JSON:

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

Resultado no arquivo Parquet:
A configuração e a carga útil acima produzirão três colunas e um evento

carimbo de data/hora	id_string	datapoints_dynamic
`2020-11-01T10:00:00.000Z`	`800500054755`	`[{"value": 120},{"value":124}]`

Próximos passos

Compreender as limitações de taxa de transferência do seu ambiente