Nivelamento, escape e matriz de JSON

Artigo
10/26/2023

Observação

O serviço TSI (Time Series Insights) não terá mais suporte após março de 2025. Considere migrar os ambientes existentes do TSI para soluções alternativas assim que possível. Para obter mais informações sobre a substituição e a migração, visite nossa documentação.

Seu ambiente Azure Time Series Insights Gen2 criará dinamicamente as colunas de seus armazenamentos quentes e frios, seguindo um conjunto específico de convenções de nomenclatura. Quando um evento é ingerido, um conjunto de regras é aplicado à carga JSON, bem como aos nomes de propriedade. Isso abrange o escape de determinados caracteres especiais e o nivelamento de objetos JSON aninhados. É importante ter conhecimento sobre dessas regras para compreender de que maneira a forma do JSON influenciará como os eventos são armazenados e consultados. Veja na tabela abaixo uma lista completa de configurações. Exemplos A & B também demonstram como você é capaz de fazer o lote de várias séries temporais com eficiência em uma matriz.

Importante

Revise as regras abaixo antes de selecionar uma propriedade de ID da Série Temporal e/ou a(s) propriedade(s) do carimbo de data/hora de origem do evento. Se a ID do TS ou o carimbo de data/hora estiver dentro de um objeto aninhado ou tiver um ou mais caracteres especiais abaixo, será importante garantir que o nome da propriedade que você fornece corresponde ao nome da coluna depois que as regras de ingestão foram aplicadas. Veja o exemplo B abaixo.

Regra	JSON de exemplo	Sintaxe e Expressão de Série Temporal	Nome da coluna de propriedade no Parquet
Os tipos de dados do Azure Time Series Insights Gen2 estão anexados ao final do nome da coluna como "_< tipo de dados> "	`"type": "Accumulated Heat"`	`$event.type.String`	`type_string`
A propriedade carimbo de data/hora da 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 sua propriedade de data/hora de origem do evento para atender às necessidades da solução, mas o nome da coluna no armazenamento quente e frio é "carimbo de data/hora". Outras propriedades JSON de 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 propriedades JSON que abrangem os caracteres especiais. [ \ e ' têm os escapes [' e ']	`"id.wasp": "6A3090FD337DE6B"`	`$event['id.wasp'].String`	`['id.wasp']_string`
Em [' e '], há o escape adicional de aspas simples e barras invertidas. A aspa simples é escrita como \’, e a barra invertida 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 o 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`
As matrizes de tipos primitivos são armazenadas como um 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) de TS ou a(s) Propriedade(es) de carimbo de data/hora estiver(em) dentro dos objetos em uma matriz, a matriz será desregistrada de forma que o conteúdo JSON inicial produza vários eventos. Isso permite que você lote vários eventos em uma estrutura JSON. Todas as propriedades de nível superior que são pares da matriz serão salvas com cada objeto não registrado. Se a(s) IDs de TS e carimbo de data/hora não estiverem dentro da matriz, ele(s) é(são) salvo(s) como se fossem tipo dinâmico.	Veja os exemplos A, Be C abaixo
Matrizes contendo 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 é aplicável a nomes de propriedade que foram concatenados do objeto achatado, 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`

Compreendendo o comportamento dual para matrizes

As matrizes de objetos serão armazenadas por inteiro ou divididas em vários eventos, dependendo de como você modelar 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 Hubs de Eventos ou mensagens de Hub IoT enviadas.

No entanto, em alguns casos, matrizes que contêm objetos só são significativas no contexto de outros valores. A criação de vários eventos renderiza os dados sem significado. Para garantir que uma matriz de objetos seja armazenada no estado em que se encontra 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 IDs de Série Temporal estiverem aninhadas dentro de objetos em uma matriz ou se a propriedade de carimbo de data/hora de origem do evento estiver aninhada, o mecanismo de ingestão irá dividi-lo para criar vários eventos. Os nomes de propriedade fornecidos para suas IDs de TS e/ou carimbo de data/hora devem seguir as regras de mesclagem acima e, portanto, indicarão a forma do JSON. Consulte os exemplos abaixo e confira o guia sobre como selecionar uma propriedade ID da Série Temporal.

Exemplo A

ID da Série Temporal na raiz do objeto e no carimbo de data/hora aninhado
ID da série temporal do ambiente:"id"
Carimbo de data/hora da origem do evento:"values.time"
conteúdo 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 do Parquet:
A configuração e o conteúdo acima produzirão três colunas e quatro eventos

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`

Exemplo B

ID da série temporal composta com uma propriedade aninhada
ID do Ambiente da Série Temporal:"plantId" e "telemetry.tagId"
Carimbo de data/hora da origem do evento:"timestamp"
conteúdo 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 do Parquet:
A configuração e o conteúdo acima produzirão três colunas e quatro eventos

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

Exemplo C

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 da origem do evento:"timestamp"
conteúdo JSON:

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

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

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

Próximas etapas

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

Nivelamento, escape e matriz de JSON

Compreendendo o comportamento dual para matrizes

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

Exemplo A

Exemplo B

Exemplo C

Próximas etapas

Recursos adicionais