Enviar dados para o Azure Data Explorer de um pipeline do Processador de Dados IoT do Azure Versão prévia

  • Artigo

Importante

O recurso Pré-visualização de Operações do Azure IoT — habilitado pelo Azure Arc — está atualmente em VERSÃO PRÉVIA. Você não deve usar esse software em versão prévia em ambientes de produção.

Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Use o destino Azure Data Explorer para gravar dados em uma tabela do Azure Data Explorer de um pipeline do Processador de Dados IoT do Azure Versão prévia. A fase de destino agrupa as mensagens em lote antes de enviá-las para o Azure Data Explorer.

Pré-requisitos

Para configurar e usar uma fase de destino do pipeline do Azure Data Explorer, você precisará do seguinte:

Configurar o Azure Data Explorer

Antes de poder escrever no Azure Data Explorer a partir de um pipeline de dados, é necessário conceder acesso à base de dados a partir do pipeline. Você pode usar uma entidade de serviço ou uma identidade gerenciada para autenticar o pipeline no banco de dados. A vantagem de utilizar uma identidade gerida é que não precisa de gerir o ciclo de vida do principal de serviço. A identidade gerida é gerida automaticamente pelo Azure e está ligada ao ciclo de vida do recurso ao qual está atribuída.

Para criar uma entidade de serviço com um segredo de cliente:

  1. Use o comando da CLI do Azure a seguir para criar uma entidade de serviço.

    az ad sp create-for-rbac --name <YOUR_SP_NAME>

  2. O resultado desse comando inclui uma appId, displayName, password e tenant. Anote esses valores para usá-los ao configurar o acesso a um de seus recursos de nuvem como o Microsoft Fabric, criar um segredo e configurar um destino de pipeline:

    {
    "appId": "<app-id>",
    "displayName": "<name>",
    "password": "<client-secret>",
    "tenant": "<tenant-id>"
}

Para conceder acesso de administrador ao banco de dados do Azure Data Explorer, execute o seguinte comando na guia de consulta do seu banco de dados:

.add database <DatabaseName> admins (<ApplicationId>) <Notes>

Para se conectar ao Azure Data Explorer, a fase de destino precisa de acesso a um segredo que contenha os detalhes da autenticação. Para criar um segredo:

  1. Use o seguinte comando para adicionar um segredo ao seu Azure Key Vault que contém o segredo do cliente no qual você fez uma anotação sobre quando criou a entidade de serviço:

    az keyvault secret set --vault-name <your-key-vault-name> --name AccessADXSecret --value <client-secret>

  2. Adicione a referência secreta ao seu cluster Kubernetes seguindo as etapas em Gerenciar segredos para sua implantação das Operações do Azure IoT Versão prévia.

Separação em lotes

O Processador de Dados grava no Azure Data Explorer em lotes. Enquanto você agrupa seus dados em lote no processador de dados antes de enviá-los, o Azure Data Explorer tem sua própria política de agregação em lotes para ingestão padrão. Portanto, talvez você não veja seus dados no Azure Data Explorer imediatamente após o Processador de Dados gravá-los no destino do Azure Data Explorer.

Para visualizar dados no Azure Data Explorer assim que o pipeline os enviar, você pode definir a contagem da política de lote de ingestão como 1. Para editar a política de agregação em lotes para ingestão, execute o seguinte comando na guia de consulta do seu banco de dados:

.alter database <your-database-name> policy ingestionbatching
```
{
    "MaximumBatchingTimeSpan" : "00:00:30",
    "MaximumNumberOfItems" : 1,
    "MaximumRawDataSizeMB": 1024
}
```

Configurar a fase de destino

A configuração JSON da fase de destino do Azure Data Explorer define os detalhes da fase. Para criar a fase, você pode interagir com a interface do usuário baseada em formulários ou fornecer a configuração JSON na guia Avançado:

Campo Type Descrição Obrigatório Padrão Exemplo
Nome de exibição String Um nome a ser mostrado na interface do usuário do Processador de Dados. Sim - Azure IoT MQ output
Descrição Cadeia de caracteres Uma descrição fácil de entender do que a fase faz. Não Write to topic default/topic1
URL do cluster String O URI (esse valor não é o URI da ingestão de dados). Sim -
Banco de dados String Nome do banco de dados. Sim -
Tabela String O nome da tabela na qual gravar. Sim -
Lote Batch Como enviar dados em lote. Não 60s 10s
Tentar novamente Repetir A política de nova tentativa a ser usada. Não default fixed
Autenticação1 String Os detalhes de autenticação para a conexão com o Azure Data Explorer. Service principal ou Managed identity Entidade de serviço Sim -
Colunas > Nome string O nome da coluna. Sim temperature
Colunas > Caminho Caminho O local dentro de cada registro dos dados nos quais o valor da coluna deve ser lido. Não .{{name}} .temperature

1Autenticação: Atualmente, a fase de destino suporta autenticação baseada em principal de serviço ou identidade gerida quando se conecta ao Azure Data Explorer.

Para configurar a autenticação baseada na entidade de serviço, forneça os valores a seguir. Você anotou esses valores ao criar a entidade de serviço e adicionou a referência secreta ao seu cluster.

Campo Descrição Necessário
TenantId A ID do locatário. Sim
ClientId A ID do aplicativo que você anotou quando criou a entidade de serviço que tem acesso ao banco de dados. Sim
Segredo A referência secreta que você criou no seu cluster. Sim

Exemplo de configuração

O exemplo JSON a seguir mostra uma configuração completa da fase de destino do Azure Data Explorer que grava a mensagem inteira na tabela quickstart no banco de dados:

{
    "displayName": "Azure data explorer - 71c308",
    "type": "output/dataexplorer@v1",
    "viewOptions": {
        "position": {
            "x": 0,
            "y": 784
        }
    },
    "clusterUrl": "https://clusterurl.region.kusto.windows.net",
    "database": "databaseName",
    "table": "quickstart",
    "authentication": {
        "type": "servicePrincipal",
        "tenantId": "tenantId",
        "clientId": "clientId",
        "clientSecret": "secretReference"
    },
    "batch": {
        "time": "5s",
        "path": ".payload"
    },
    "columns": [
        {
            "name": "Timestamp",
            "path": ".Timestamp"
        },
        {
            "name": "AssetName",
            "path": ".assetName"
        },
        {
            "name": "Customer",
            "path": ".Customer"
        },
        {
            "name": "Batch",
            "path": ".Batch"
        },
        {
            "name": "CurrentTemperature",
            "path": ".CurrentTemperature"
        },
        {
            "name": "LastKnownTemperature",
            "path": ".LastKnownTemperature"
        },
        {
            "name": "Pressure",
            "path": ".Pressure"
        },
        {
            "name": "IsSpare",
            "path": ".IsSpare"
        }
    ],
    "retry": {
        "type": "fixed",
        "interval": "20s",
        "maxRetries": 4
    }
}

A configuração define que:

  • As mensagens são agregadas em lote por 5 segundos.
  • Usa o .payload do caminho do lote para localizar os dados para as colunas.

Exemplo

O exemplo a seguir mostra uma amostra de mensagem de entrada de dados para a fase de destino do Azure Data Explorer:

{
  "payload": {
    "Batch": 102,
    "CurrentTemperature": 7109,
    "Customer": "Contoso",
    "Equipment": "Boiler",
    "IsSpare": true,
    "LastKnownTemperature": 7109,
    "Location": "Seattle",
    "Pressure": 7109,
    "Timestamp": "2023-08-10T00:54:58.6572007Z",
    "assetName": "oven"
  },
  "qos": 0,
  "systemProperties": {
    "partitionId": 0,
    "partitionKey": "quickstart",
    "timestamp": "2023-11-06T23:42:51.004Z"
  },
  "topic": "quickstart"
}

Conteúdo relacionado