Enviar dados para o Azure Data Explorer de um pipeline do processador de dados
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.
Você precisará implantar uma nova instalação do Azure IoT Operations quando uma versão geralmente disponível for disponibilizada, você não poderá atualizar uma instalação de visualizaçã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 do Azure Data Explorer para gravar dados em uma tabela no Azure Data Explorer de um pipeline de processador de dados. 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:
- Uma instância implantada do processador de dados.
- Um cluster do Azure Data Explorer.
- Um banco de dados no seu cluster do Azure Data Explorer.
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:
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>
O resultado desse comando inclui uma
appId
,displayName
,password
etenant
. 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:
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>
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 dados em lote no processador de dados antes de enviá-los, o Azure Data Explorer tem sua própria política de envio em lote de ingestão padrão. Portanto, talvez você não veja seus dados no Azure Data Explorer imediatamente depois que o processador de dados os grava 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 | - | MQTT broker 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"
}