Ingerir dados de amostra formatados em JSON no Azure Data Explorer

  • Artigo

Este artigo mostra como ingerir dados JSON formatados em um banco de dados do Azure Data Explorer. Você começará com exemplos simples de JSON bruto e mapeado, continuará para JSON com várias linhas e, em seguida, lidará com esquemas JSON mais complexos que contêm matrizes e dicionários. Os exemplos detalham o processo de ingestão de dados formatados em JSON usando Linguagem de Consulta Kusto (KQL), C#ou Python.

Observação

Não recomendamos usar .ingest comandos de gerenciamento em cenários de produção. Em vez disso, use um conector de dados ou ingera dados programaticamente usando uma das bibliotecas de cliente Kusto.

Pré-requisitos

  • Uma conta da Microsoft ou uma Microsoft Entra identidade do usuário. Uma assinatura do Azure não é necessária.
  • Um cluster e um banco de dados do Azure Data Explorer. Crie um cluster e um banco de dados.

O formato JSON

Azure Data Explorer dá suporte a dois formatos de arquivo JSON:

  • json: JSON separado por linha. Cada linha nos dados de entrada tem exatamente um registro JSON. Esse formato dá suporte à análise de comentários e propriedades de aspas simples. Para obter mais informações, consulte Linhas do JSON.
  • multijson: JSON de várias linhas. O analisador ignora os separadores de linha e lê um registro da posição anterior até o final de um JSON válido.

Observação

Ao ingerir usando o assistente de ingestão, o formato padrão é multijson. O formato pode lidar com registros JSON de várias linhas e matrizes de registros JSON. Quando um erro de análise é encontrado, todo o arquivo é descartado. Para ignorar registros JSON inválidos, selecione a opção para "Ignorar erros de formato de dados.", que alternará o formato para json (Linhas JSON).

Se você estiver usando o formato de linha JSON (json), as linhas que não representam registros JSON válidos serão ignoradas durante a análise.

Ingerir e mapear dados formatados em JSON

A ingestão de dados formatados em JSON exige que você especifique o formato usando a propriedade de ingestão. A ingestão de dados JSON requer mapeamento, que mapeia uma entrada de origem JSON para sua coluna de destino. Ao ingerir dados, use a propriedade IngestionMapping com a propriedade de ingestão ingestionMappingReference (para um mapeamento predefinido) ou a propriedade IngestionMappings. Este artigo usará a propriedade de ingestão ingestionMappingReference, que é predefinida na tabela usada para ingestão. Nos exemplos abaixo, vamos começar ingerindo registros JSON como dados brutos em uma única tabela de colunas. Em seguida, vamos usar o mapeamento para ingerir cada propriedade para sua coluna mapeada.

Exemplo de JSON simples

O exemplo a seguir é um JSON simples, com uma estrutura plana. Os dados têm informações de temperatura e umidade, coletadas por vários dispositivos. Cada registro é marcado com uma ID e um carimbo de data/hora.

{
    "timestamp": "2019-05-02 15:23:50.0369439",
    "deviceId": "2945c8aa-f13e-4c48-4473-b81440bb5ca2",
    "messageId": "7f316225-839a-4593-92b5-1812949279b3",
    "temperature": 31.0301639051317,
    "humidity": 62.0791099602725
}

Ingerir registros JSON brutos

Neste exemplo, você ingere registros JSON como dados brutos em uma única tabela de colunas. A manipulação de dados, usando consultas e a política de atualização é feita depois que os dados são ingeridos.

Use Linguagem de Consulta Kusto para ingerir dados em um formato JSON bruto.

  1. Entrar no https://dataexplorer.azure.com.

  2. Selecione Adicionar cluster.

  3. Na caixa de diálogo Adicionar cluster, insira o URL do cluster no formulário e https://<ClusterName>.<Region>.kusto.windows.net/, selecione Adicionar.

  4. Cole o comando a seguir e selecione Executar para criar uma tabela.

    .create table RawEvents (Event: dynamic)

    Essa consulta cria uma tabela com uma única coluna Event de um tipo de dados dinâmico.

  5. Crie um mapeamento JSON.

    .create table RawEvents ingestion json mapping 'RawEventMapping' '[{"column":"Event","Properties":{"path":"$"}}]'

    Esse comando cria um mapeamento e mapeia o caminho raiz JSON $ para a coluna Event.

  6. Faça a ingestão de dados na tabela RawEvents.

    .ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') with '{"format":"json", "ingestionMappingReference":"RawEventMapping"}'

Ingerir registros JSON mapeados

Neste exemplo, você ingere dados de registros JSON. Cada propriedade JSON é mapeada para uma única coluna na tabela.

  1. Crie uma nova tabela, com um esquema semelhante aos dados de entrada JSON. Vamos usar essa tabela para todos os exemplos e comandos de ingestão a seguir.

    .create table Events (Time: datetime, Device: string, MessageId: string, Temperature: double, Humidity: double)

  2. Crie um mapeamento JSON.

    .create table Events ingestion json mapping 'FlatEventMapping' '[{"column":"Time","Properties":{"path":"$.timestamp"}},{"column":"Device","Properties":{"path":"$.deviceId"}},{"column":"MessageId","Properties":{"path":"$.messageId"}},{"column":"Temperature","Properties":{"path":"$.temperature"}},{"column":"Humidity","Properties":{"path":"$.humidity"}}]'

    Nesse mapeamento, conforme definido pelo esquema de tabela, as entradas timestampserão ingeridas na coluna Time como tipos de dados datetime.

  3. Faça a ingestão da dados na tabela Events.

    .ingest into table Events ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') with '{"format":"json", "ingestionMappingReference":"FlatEventMapping"}'

    O arquivo 'simple.json' tem alguns registros JSON separados por linha. O formato é json e o mapeamento usado no comando de ingestão é o FlatEventMapping que você criou.

Ingerir registros JSON de várias linhas

Neste exemplo, você ingere registros JSON de várias linhas. Cada propriedade JSON é mapeada para uma única coluna na tabela. O arquivo 'multilined.json' tem alguns registros JSON recuados. O formato multijson indica a leitura de registros pela estrutura JSON.

Faça a ingestão da dados na tabela Events.

.ingest into table Events ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/multilined.json') with '{"format":"multijson", "ingestionMappingReference":"FlatEventMapping"}'

Ingerir registros JSON que contêm matrizes

Tipos de dados de matriz são uma coleção ordenada de valores. A ingestão de uma matriz JSON é feita por uma política de atualização. O JSON é ingerido no estado em que se está em uma tabela intermediária. Uma política de atualização executa uma função predefinida na tabela RawEvents, testando novamente os resultados para a tabela de destino. Vamos ingerir dados com a seguinte estrutura:

{
    "records":
    [
        {
            "timestamp": "2019-05-02 15:23:50.0000000",
            "deviceId": "ddbc1bf5-096f-42c0-a771-bc3dca77ac71",
            "messageId": "7f316225-839a-4593-92b5-1812949279b3",
            "temperature": 31.0301639051317,
            "humidity": 62.0791099602725
        },
        {
            "timestamp": "2019-05-02 15:23:51.0000000",
            "deviceId": "ddbc1bf5-096f-42c0-a771-bc3dca77ac71",
            "messageId": "57de2821-7581-40e4-861e-ea3bde102364",
            "temperature": 33.7529423105311,
            "humidity": 75.4787976739364
        }
    ]
}

  1. Crie uma função update policy que expanda a coleção de records para que cada valor na coleção receba uma linha separada, usando o operador mv-expand. Vamos usar a tabela RawEvents como uma tabela de origem e Events como uma tabela de destino.

    .create function EventRecordsExpand() {
    RawEvents
    | mv-expand records = Event.records
    | project
        Time = todatetime(records["timestamp"]),
        Device = tostring(records["deviceId"]),
        MessageId = tostring(records["messageId"]),
        Temperature = todouble(records["temperature"]),
        Humidity = todouble(records["humidity"])
}

  2. O esquema recebido pela função deve corresponder ao esquema da tabela de destino. Use o operador getschema para examinar o esquema.

    EventRecordsExpand() | getschema

  3. Adicione a política de atualização à tabela de destino. Essa política executará a consulta automaticamente nos dados recém-ingeridos na tabela de dados intermediária RawEvents e ingerirá os resultados na tabela Events. Defina uma política de retenção zero para evitar a persistência da tabela intermediária.

    .alter table Events policy update @'[{"Source": "RawEvents", "Query": "EventRecordsExpand()", "IsEnabled": "True"}]'

  4. Faça a ingestão de dados na tabela RawEvents.

    .ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/array.json') with '{"format":"multijson", "ingestionMappingReference":"RawEventMapping"}'

  5. Examine os dados na tabela Events.

    Events

Conteúdo relacionado