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

Importante

Esta página inclui instruções para gerenciar os componentes de Operações do Azure IoT usando manifestos de implantação do Kubernetes, que estão em versão prévia. Esse recurso é fornecido com várias limitações e não deve ser usado para cargas de trabalho 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.

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

Pré-requisitos

• Uma instância do Operações do Azure IoT
• Um cluster do Azure Data Explorer. Siga as etapas de Cluster completo em Início Rápido: Criar um cluster do Azure Data Explorer e um banco de dados. A opção cluster gratuito não funciona nesse cenário.

Criar um banco de dados do Azure Data Explorer

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

2. Crie uma tabela no seu banco de dados para os dados. Você pode usar o portal do Azure e criar colunas manualmente ou usar o KQL na guia de consulta. Por exemplo, para criar uma tabela para dados de termostato de amostra, 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 de 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. Veja Habilitar 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.

Após a criação do banco de dados do Azure Data Explorer, você precisará atribuir uma função à identidade gerenciada do Operações do Azure IoT que conceda permissão para gravar no banco de dados.

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

1. No banco de dados do Azure Data Explorer (não no cluster), em Visão geral selecione Permissões>Adicionar e depois 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, confira Controle de acesso baseado em função.
2. Procure o nome da sua identidade gerenciada atribuída pelo usuário configurada para conexões em nuvem ou a identidade gerenciada atribuída pelo sistema. Por exemplo, azure-iot-operations-xxxx7.
3. Em seguida, selecione Selecionar.

Crie um 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 do fluxo de dados.

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

   

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

   Configuração	Descrição
   Nome	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 pelo sistema ou Identidade gerenciada atribuída pelo usuário.
   ID do Cliente	A ID do cliente da identidade gerenciada atribuída pelo usuário. Necessário se estiver usando a Identidade gerenciada atribuída pelo usuário.
   ID do locatário	A ID do locatário de uma identidade gerenciada atribuída pelo usuário. Necessário se estiver usando a Identidade gerenciada atribuída pelo 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 via CLI do Azure.

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

Kubernetes (versão prévia)

Crie um arquivo manifesto do Kubernetes .yaml 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 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 gerenciada atribuída pelo sistema

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

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

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

Portal

Na página de 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 sistema.

Bicep

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

Kubernetes (versão prévia)

dataExplorerSettings:
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings: {}

Se precisar substituir o público-alvo da identidade gerenciada atribuída pelo sistema, você pode especificar a configuração audience.

Portal

Na maioria dos casos, você não precisa especificar outras configurações. Essa configuração cria uma identidade gerenciada com o público padrão https://api.kusto.windows.net.

Bicep

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

Kubernetes (versão prévia)

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

Identidade gerenciada atribuída pelo usuário

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

Antes de configurar o ponto de extremidade de fluxo de dados, atribua uma função à identidade gerenciada atribuída pelo usuário que conceda 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 no cluster), em Visão geral selecione Permissões>Adicionar e depois selecione uma função apropriada.
2. Procure o nome da sua identidade gerenciada atribuída pelo usuário.
3. Escolha Selecionar.

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

Portal

Na página de 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 a ID do cliente de identidade gerenciada atribuída pelo usuário e a 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 (versão prévia)

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 por meio do Bicep ou do Kubernetes.

Configurações avançadas

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

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

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

Por exemplo, para configurar o número máximo de mensagens para 1.000 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 do ponto de extremidade do fluxo de dados.

Bicep

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

Kubernetes (versão prévia)

dataExplorerSettings:
  batching:
    latencySeconds: 100
    maxMessages: 1000

Próximas etapas

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