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

Importante

Esta página inclui instruções para gerenciar componentes do Azure IoT Operations usando manifestos de implantação do Kubernetes, que está em visualização. Esse recurso é fornecido com várias limitações e não deve ser usado para cargas de trabalho de produção.

Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.

Para enviar dados para o Azure Data Explorer no Azure IoT Operations, 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
• 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.

Atribuir permissão à identidade gerenciada

Para configurar um ponto de extremidade de fluxo de dados para o Azure Data Explorer, recomendamos usar uma identidade gerenciada atribuída pelo usuário ou pelo sistema. Essa abordagem é segura e elimina a necessidade de gerenciar credenciais manualmente.

Depois que o banco de dados do Azure Data Explorer for criado, você precisará atribuir uma função à identidade gerenciada do Azure IoT Operations que conceda permissão para gravar no banco de dados.

Se estiver usando a identidade gerenciada atribuída ao sistema, no portal do Azure, vá para sua instância de Operações IoT do Azure e selecione Visão geral. Copie o nome da extensão listada após a extensão Azure IoT Operations Arc. Por exemplo, azure-iot-operations-xxxx7. Sua identidade gerenciada atribuída ao sistema pode ser encontrada usando o mesmo nome da extensão Azure IoT Operations Arc.

1. No seu banco de dados do Azure Data Explorer (não cluster), em Visão geral, selecione Permissões>Adicionar e, em seguida, selecione Ingestor como a função. Isso dá à identidade gerenciada as permissões necessárias para gravar no banco de dados do Azure Data Explorer. Para saber mais, veja Controlo de acesso baseado em funções.
2. Procure o nome da sua identidade gerenciada atribuída pelo usuário configurada para conexões na nuvem ou a identidade gerenciada atribuída ao sistema. Por exemplo, azure-iot-operations-xxxx7.
3. Em seguida, selecione Selecionar.

Criar ponto de extremidade de fluxo de dados para o Azure Data Explorer

Portal

1. Na experiência de operações, selecione a guia Pontos de extremidade de fluxo de dados.

2. Em Criar novo ponto de extremidade de fluxo de dados, selecione Azure Data Explorer>New.

   

3. Insira as seguintes configurações para o ponto de extremidade:

   Definição	Description
   Name	O nome do ponto de extremidade do fluxo de dados.
   Host	O nome do host do ponto de extremidade do Azure Data Explorer no formato <cluster>.<region>.kusto.windows.net.
   Método de autenticação	O método usado para autenticação. Escolha Identidade gerenciada atribuída ao sistema ou Identidade gerenciada atribuída ao usuário.
   ID de Cliente	A ID do cliente da identidade gerenciada atribuída pelo usuário. Obrigatório se estiver usando a identidade gerenciada atribuída ao usuário.
   ID de Inquilino do	A ID do locatário da identidade gerenciada atribuída pelo usuário. Obrigatório se estiver usando a identidade gerenciada atribuída ao usuário.

4. Selecione Aplicar para provisionar o ponto de extremidade.

Bicep

Crie um arquivo Bicep .bicep com o seguinte conteúdo.

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-11-01' existing = {
  name: aioInstanceName
}
resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}
resource adxEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'DataExplorer'
    dataExplorerSettings: {
      host: hostName
      database: databaseName
      authentication: {
        // See available authentication methods section for method types
        // method: <METHOD_TYPE>
      }
    }
  }
}

Em seguida, implante por meio da CLI do Azure.

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

Kubernetes (visualização)

Crie um arquivo de manifesto .yaml do Kubernetes com o seguinte conteúdo.

apiVersion: connectivity.iotoperations.azure.com/v1
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:
      # See available authentication methods section for method types
      # method: <METHOD_TYPE>

Em seguida, aplique o arquivo de manifesto ao cluster do Kubernetes.

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.

Identidade gerida atribuída pelo sistema

Antes de configurar o ponto de extremidade de fluxo de dados, atribua uma função à identidade gerenciada do Azure IoT Operations que conceda permissão para gravar no banco de dados do Azure Data Explorer:

1. No portal do Azure, vá para sua instância de Operações do Azure IoT e selecione Visão geral.
2. Copie o nome da extensão listada após a extensão Azure IoT Operations Arc. Por exemplo, azure-iot-operations-xxxx7.
3. Vá para o banco de dados do Azure Data Explorer (não cluster), em Visão geral, selecione Permissões>Adicionar e, em seguida, selecione uma função apropriada.
4. Procure o nome da identidade gerenciada atribuída ao sistema. Por exemplo, azure-iot-operations-xxxx7.
5. Selecione Selecionar.

Em seguida, configure o ponto de extremidade de fluxo de dados com as configurações de identidade gerenciada atribuídas pelo sistema.

Portal

Na página Configurações do ponto de extremidade do fluxo de dados da experiência de operações, selecione a guia Básico e escolha Método de autenticação>Identidade gerenciada atribuída ao sistema.

Bicep

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

Kubernetes (visualização)

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.

Portal

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.

Bicep

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

Kubernetes (visualização)

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

Identidade gerida atribuída pelo utilizador

Para usar a identidade gerenciada atribuída pelo usuário para autenticação, você deve primeiro implantar as Operações do Azure IoT com configurações seguras habilitadas. Em seguida, você precisa configurar uma identidade gerenciada atribuída pelo usuário para conexões na nuvem. Para saber mais, consulte Habilitar configurações seguras na implantação do Azure IoT Operations.

Antes de configurar o ponto de extremidade de fluxo de dados, atribua uma função à identidade gerenciada atribuída pelo usuário que concede permissão para gravar no banco de dados do Azure Data Explorer:

1. No portal do Azure, vá para o banco de dados do Azure Data Explorer (não cluster), em Visão geral, selecione Permissões>Adicionar e, em seguida, selecione uma função apropriada.
2. Procure o nome da sua identidade gerenciada atribuída pelo usuário.
3. Selecione Selecionar.

Em seguida, configure o ponto de extremidade de fluxo de dados com as configurações de identidade gerenciada atribuídas pelo usuário.

Portal

Na página Configurações do ponto de extremidade do fluxo de dados da experiência de operações, selecione a guia Básico e escolha Método de autenticação>Identidade gerenciada atribuída pelo usuário.

Insira o ID do cliente de identidade gerenciada atribuído ao usuário e o ID do locatário nos campos apropriados.

Bicep

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

Kubernetes (visualização)

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.

Campo	Descrição	Obrigatório
latencySeconds	O número máximo de segundos de espera antes de enviar as mensagens para o destino. O valor padrão é 60 segundos.	Não
maxMessages	O número máximo de mensagens a enviar para o destino. O valor padrão é 100000 mensagens.	Não

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:

Portal

Na experiência de operações, selecione a guia Avançado para o ponto de extremidade de fluxo de dados.

Bicep

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

Kubernetes (visualização)

dataExplorerSettings:
  batching:
    latencySeconds: 100
    maxMessages: 1000

Próximos passos

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