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

Importante

A Versão Prévia das Operações da Internet das Coisas do Azure – habilitadas 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 das Operações do Azure IoT quando uma versão estiver disponibilidade geral. Você não poderá atualizar uma instalação de versão prévia.

Para os 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, confira os Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

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

Pré-requisitos

• Uma instância da Versão prévia de Operações do Azure IoT
• Um perfil de fluxo de dados configurado
• 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.

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

5. No seu banco de dados do Azure Data Explorer (não no cluster), em Visão geral, selecione Permissões>Adicionar>Ingestor. Procure o nome da extensão do 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 do fluxo de dados com as informações do seu cluster e banco de dados. Sugerimos usar a identidade gerenciada do cluster Kubernetes habilitado para Azure Arc. Essa abordagem é segura e elimina a necessidade de gerenciamento secreto. Substitua os valores de espaço reservado como <ENDPOINT_NAME> pelos seus próprios.

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. SelecioneIdentidade 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.

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-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: {}
      }
    }
  }
}

Em seguida, implante via CLI do Azure.

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

Kubernetes

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

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: {}

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. Para obter mais informações sobre como habilitar configurações seguras configurando um Azure Key Vault e habilitando identidades de carga de trabalho, veja 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 Arc das Operações do Azure IoT deve receber permissão de Ingestor no banco de dados do Azure Data Explorer. Para obter mais informações, confira Gerenciar permissões do banco de dados do Azure Data Explorer.

Identidade gerenciada atribuída pelo sistema

Usar a identidade gerenciada atribuída pelo sistema é o método de autenticação recomendado para Operações do Azure IoT. O Operações do Azure IoT cria automaticamente a identidade gerenciada e a atribui ao cluster Kubernetes habilitado para Azure Arc. Com ele, não é necessário gerenciar secretos e é possível autenticar-se com facilidade.

No recurso DataflowEndpoint, especifique o método de autenticação de identidade gerenciada. 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.

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

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 um público-alvo do serviço. Não especificar um público cria uma identidade gerenciada com o público padrão limitado à sua conta de armazenamento.

Bicep

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

Kubernetes

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

Identidade gerenciada atribuída pelo usuário

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

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

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

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

dataExplorerSettings:
  batching:
    latencySeconds: 100
    maxMessages: 1000

Próximas etapas

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