Configurar pontos de extremidade de fluxo de dados para o Azure Data Explorer

Para enviar dados para o Azure Data Explorer no Azure IoT Operations Preview, você pode configurar um ponto de extremidade de fluxo de dados. Essa configuração permite especificar o ponto de extremidade de destino, o método de autenticação, a tabela e outras configurações.

Pré-requisitos

• Uma instância do Azure IoT Operations Preview
• Um perfil de fluxo de dados configurado
• Um cluster do Azure Data Explorer. Siga as etapas completas do cluster no Guia de início rápido: criar um cluster e um banco de dados do Azure Data Explorer. A opção de cluster livre não funciona para este cenário.

Criar um banco de dados do Azure Data Explorer

1. No portal do Azure, crie um banco de dados em seu cluster completo do Azure Data Explorer.

2. Crie uma tabela em seu banco de dados para os dados. Você pode usar o portal do Azure e criar colunas manualmente ou pode usar o KQL na guia de consulta. Por exemplo, para criar uma tabela para dados de termostato de exemplo, execute o seguinte comando:

   .create table thermostat (
       externalAssetId: string,
       assetName: string,
       CurrentTemperature: real,
       Pressure: real,
       MqttTopic: string,
       Timestamp: datetime
   )
   

3. Habilite a ingestão de streaming em sua tabela e banco de dados. Na guia consulta, execute o seguinte comando, substituindo <DATABASE_NAME> pelo nome do banco de dados:

   .alter database ['<DATABASE_NAME>'] policy streamingingestion enable
   

   Como alternativa, habilite a ingestão de streaming em todo o cluster. Consulte Habilitar a ingestão de streaming em um cluster existente.

4. No portal do Azure, vá para o cluster Kubernetes conectado ao Arc e selecione Extensões de Configurações>. Na lista de extensões, localize o nome da sua extensão Azure IoT Operations. Copie o nome da extensão.

5. Em seu banco de dados do Azure Data Explorer (não cluster), em Visão geral, selecione Permissões>Adicionar>Ingestor. Procure o nome da extensão Azure IoT Operations e adicione-o.

Criar um ponto de extremidade de fluxo de dados do Azure Data Explorer

Crie o recurso de ponto de extremidade de fluxo de dados com suas informações de cluster e banco de dados. Sugerimos usar a identidade gerenciada do cluster Kubernetes habilitado para Azure Arc. Esta abordagem é segura e elimina a necessidade de gestão secreta. Substitua os valores de espaço reservado como <ENDPOINT_NAME> os seus.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param endpointName string = '<ENDPOINT_NAME>'
param hostName string = 'https://<CLUSTER>.<region>.kusto.windows.net'
param databaseName string = '<DATABASE_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {
  name: aioInstanceName
}
resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}
resource adxEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-09-15-preview' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'DataExplorer'
    dataExplorerSettings: {
      host: hostName
      database: databaseName
      authentication: {
        method: 'SystemAssignedManagedIdentity'
        systemAssignedManagedIdentitySettings: {}
      }
    }
  }
}

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

apiVersion: connectivity.iotoperations.azure.com/v1beta1
kind: DataflowEndpoint
metadata:
  name: <ENDPOINT_NAME>
  namespace: azure-iot-operations
spec:
  endpointType: DataExplorer
  dataExplorerSettings:
    host: 'https://<CLUSTER>.<region>.kusto.windows.net'
    database: <DATABASE_NAME>
    authentication:
      method: SystemAssignedManagedIdentity
      systemAssignedManagedIdentitySettings: {}

kubectl apply -f <FILE>.yaml

Métodos de autenticação disponíveis

Os seguintes métodos de autenticação estão disponíveis para pontos de extremidade do Azure Data Explorer. Para obter mais informações sobre como habilitar configurações seguras configurando um Cofre de Chaves do Azure e habilitando identidades de carga de trabalho, consulte Habilitar configurações seguras na implantação do Azure IoT Operations Preview.

Permissões

Para usar esses métodos de autenticação, a extensão Azure IoT Operations Arc deve receber permissão Ingestor no banco de dados do Azure Data Explorer. Para obter mais informações, consulte Gerenciar permissões de banco de dados do Azure Data Explorer.

Identidade gerida atribuída pelo sistema

Usar a identidade gerenciada atribuída ao sistema é o método de autenticação recomendado para as Operações do Azure IoT. O Azure IoT Operations cria a identidade gerenciada automaticamente e a atribui ao cluster Kubernetes habilitado para Azure Arc. Ele elimina a necessidade de gerenciamento de segredos e permite a autenticação perfeita.

No recurso DataflowEndpoint, especifique o método de autenticação de identidade gerenciada. Na maioria dos casos, não é necessário especificar outras configurações. Essa configuração cria uma identidade gerenciada com o público https://api.kusto.windows.netpadrão.

dataExplorerSettings: {
  authentication: {
    method: 'SystemAssignedManagedIdentity'
    systemAssignedManagedIdentitySettings: {}
  }
}

dataExplorerSettings:
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings: {}

Se você precisar substituir o público de identidade gerenciado atribuído ao sistema, poderá especificar a audience configuração.

dataExplorerSettings: {
  authentication: {
    method: 'SystemAssignedManagedIdentity'
    systemAssignedManagedIdentitySettings: {
      audience: 'https://<AUDIENCE_URL>'    
    }
  }
}

dataExplorerSettings:
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings:
      audience: https://<AUDIENCE_URL>

Identidade gerida atribuída pelo utilizador

Para usar a identidade gerenciada pelo usuário para autenticação, você deve primeiro implantar as Operações do Azure IoT com configurações seguras habilitadas. Para saber mais, consulte Habilitar configurações seguras na implantação do Azure IoT Operations Preview.

Em seguida, especifique o método de autenticação de identidade gerenciada atribuído pelo usuário juntamente com a ID do cliente, a ID do locatário e o escopo da identidade gerenciada.

dataExplorerSettings: {
  authentication: {
    method: 'UserAssignedManagedIdentity'
    userAssignedManagedIdentitySettings: {
      clientId: '<ID>'
      tenantId: '<ID>'
      // Optional, defaults to 'https://api.kusto.windows.net/.default'
      // scope: 'https://<SCOPE_URL>'
    }
  }
}

dataExplorerSettings:
  authentication:
    method: UserAssignedManagedIdentity
    userAssignedManagedIdentitySettings:
      clientId: <ID>
      tenantId: <ID>
      # Optional, defaults to 'https://api.kusto.windows.net/.default'
      # scope: https://<SCOPE_URL>

Aqui, o escopo é opcional e o padrão é .https://api.kusto.windows.net/.default Se você precisar substituir o escopo padrão, especifique a scope configuração via Bicep ou Kubernetes.

Definições avançadas

Você pode definir configurações avançadas para o ponto de extremidade do Azure Data Explorer, como a latência em lote e a contagem de mensagens.

Use as batching configurações para configurar o número máximo de mensagens e a latência máxima antes que as mensagens sejam enviadas para o destino. Essa configuração é útil quando você deseja otimizar a largura de banda da rede e reduzir o número de solicitações para o destino.

Por exemplo, para configurar o número máximo de mensagens para 1000 e a latência máxima para 100 segundos, use as seguintes configurações:

dataExplorerSettings: {
  batching: {
    latencySeconds: 100
    maxMessages: 1000
  }
}

dataExplorerSettings:
  batching:
    latencySeconds: 100
    maxMessages: 1000

Próximos passos

Para saber mais sobre fluxos de dados, consulte Criar um fluxo de dados.