Configurar pontos de extremidade de fluxo de dados para o Azure Data Lake Storage Gen2

Artigo
11/20/2024

Importante

Esta página inclui instruções para gerenciar componentes do serviço 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 Lake Storage Gen2 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, método de autenticação, tabela e outras Configurações.

Pré-requisitos

Uma instância das Operações do Azure IoT
Uma conta do Azure Data Lake Storage Gen2
Um contêiner de armazenamento pré-criado na conta de armazenamento

Atribuir permissão à identidade gerenciada

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

Depois que o Azure Data Lake Storage Gen2 for criado, você precisará atribuir uma função à identidade gerenciada das Operações de IoT do Azure que concede permissão para gravar na conta de armazenamento.

Se estiver usando a identidade gerenciada atribuída pelo sistema, no portal do Azure, vá para a instância de Operações de IoT do Azure 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 das Operações de IoT do Azure.

Em seguida, vá para conta de Armazenamento do Microsoft Azure > Controle de Acesso (IAM) >Adicionar atribuição de função.

Na guia Função, selecione uma função apropriada como Storage Blob Data Contributor. Isso fornece à identidade gerenciada as permissões necessárias para gravar nos contêineres de blob do Armazenamento do Microsoft Azure. Para saber mais, confira Autorizar o acesso a blobs usando o Microsoft Entra ID.
Na guia Membros:
1. Se estiver usando a identidade gerenciada atribuída pelo sistema, para Atribuir acesso a, selecione a opção usuário, grupo ou entidade de serviço, selecione + Selecionar membros e pesquise o nome da extensão Arc do serviço Operações do Azure IoT.
2. Se estiver usando a identidade gerenciada atribuída pelo usuário, para atribuir acesso a, selecione a opção Identidade Gerenciada e selecione + Selecionar membros e pesquise sua identidade gerenciada atribuída pelo usuário configurada para conexões de nuvem.

Criar ponto de extremidade de fluxo de dados para o Azure Data Lake Storage Gen2

No portal de Operações de IoT, selecione a guia Pontos de extremidade de fluxo de dados.
Em Criar ponto de extremidade de fluxo de dados, selecione Azure Data Lake Storage (2ª geração)>Novo.

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 Lake Storage Gen2 no formato `<account>.blob.core.windows.net`. Substitua o espaço reservado da conta pelo nome da conta do ponto de extremidade.
Método de autenticação	O método usado para autenticação. Recomendamos que você 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.
Nome do segredo do token de acesso	O nome do segredo do Kubernetes que contém o token SAS. Necessário se estiver usando o Token de acesso.

Selecione Aplicar para provisionar o ponto de extremidade.

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 host string = 'https://<ACCOUNT>.blob.core.windows.net'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}
resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}
resource adlsGen2Endpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'DataLakeStorage'
    dataLakeStorageSettings: {
      host: host
      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

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: DataLakeStorage
  dataLakeStorageSettings:
    host: https://<ACCOUNT>.blob.core.windows.net
    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

Usar autenticação de token de acesso

Siga as etapas na seção token de acesso para obter um token SAS para a conta de armazenamento e armazená-lo em um segredo do Kubernetes.

Em seguida, crie o recurso DataflowEndpoint e especifique o método de autenticação do token de acesso. Aqui, substitua <SAS_SECRET_NAME> pelo nome do segredo que contém o token SAS, bem como outros valores de espaço reservado.

Consulte a seção de token de acesso para obter etapas para criar um segredo no portal de experiência de operações.

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 host string = 'https://<ACCOUNT>.blob.core.windows.net'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}
resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}
resource adlsGen2Endpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-11-01' = {
  parent: aioInstance
  name: endpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    endpointType: 'DataLakeStorage'
    dataLakeStorageSettings: {
      host: host
      authentication: {
        method: 'AccessToken'
        accessTokenSettings: {
          secretRef: '<SAS_SECRET_NAME>'
        }
      }
    }
  }
}

Em seguida, implante via CLI do Azure.

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

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: DataLakeStorage
  dataLakeStorageSettings:
    host: https://<ACCOUNT>.blob.core.windows.net
    authentication:
      method: AccessToken
      accessTokenSettings:
        secretRef: <SAS_SECRET_NAME>

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 Lake Storage Gen2.

Identidade gerenciada atribuída pelo sistema

Antes de configurar o ponto de extremidade de fluxo de dados, atribua uma função à identidade gerenciada de Operações do Azure IoT que concede permissão para gravar na conta de armazenamento:

No portal do Azure, acesse sua instância do Azure IoT Operations 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.
Vá para o recurso de nuvem que você precisa para conceder permissões. Por exemplo, vá para conta de Armazenamento do Microsoft Azure >Controle de Acesso (IAM) >Adicionar atribuição de função.
Na guia Função, selecione uma função apropriada.
Na guia Membros, para Atribuir acesso a, selecione Usuário, grupo ou opção de entidade de serviço e selecione + Selecionar membros e pesquise a identidade gerenciada do serviço Operações do Azure IoT. Por exemplo, azure-iot-operations-xxxx7.

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

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.

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.

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

dataLakeStorageSettings:
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings: {}

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

dataLakeStorageSettings: {
  authentication: {
    method: 'SystemAssignedManagedIdentity'
    systemAssignedManagedIdentitySettings: {
        audience: 'https://<ACCOUNT>.blob.core.windows.net'
    }
  }
}

dataLakeStorageSettings:
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings:
      audience: https://<ACCOUNT>.blob.core.windows.net

Identidade gerenciada atribuída pelo usuário

Para usar a identidade gerenciada atribuída pelo usuário para autenticação, primeiro você precisa implantar as 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 de nuvem. Para saber mais, confira Habilitar configurações seguras na implantação de Operações de IoT do Azure.

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 na conta de armazenamento:

No portal do Azure, vá para o recurso de nuvem que você precisa para conceder permissões. Por exemplo, vá para conta de Armazenamento do Microsoft Azure >Controle de Acesso (IAM) >Adicionar atribuição de função.
Na guia Função, selecione uma função apropriada.
Na guia Membros, para Atribuir acesso a, selecione a opção Identidade Gerenciada e selecione + Selecionar membros e pesquise sua identidade gerenciada atribuída pelo usuário.

Em seguida, defina o ponto de extremidade de fluxo de dados com as configurações de identidade gerenciada atribuídas 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.

dataLakeStorageSettings: {
  authentication: {
    method: 'UserAssignedManagedIdentity'
    userAssignedManagedIdentitySettings: {
      clientId: '<ID>'
      tenantId: '<ID>'
      // Optional, defaults to 'https://storage.azure.com/.default'
      // scope: 'https://<SCOPE_URL>'
    }
  }
}

dataLakeStorageSettings:
  authentication:
    method: UserAssignedManagedIdentity
    userAssignedManagedIdentitySettings:
      clientId: <ID>
      tenantId: <ID>
      # Optional, defaults to 'https://storage.azure.com/.default'
      # scope: https://<SCOPE_URL>

Aqui, o escopo é opcional e o padrão é https://storage.azure.com/.default. Se você precisar substituir o escopo padrão, especifique a configuração scope por meio do manifesto do Bicep ou Kubernetes.

Token de acesso

Usar um token de acesso é um método de autenticação alternativo. Este método exige que você crie um segredo do Kubernetes com o token SAS e faça referência ao segredo no recurso DataflowEndpoint.

Obtenha um token SAS para uma conta do Azure Data Lake Storage Gen2 (ADLSv2). Por exemplo, use o portal do Azure para navegar até sua conta de armazenamento. No menu à esquerda, escolha Segurança + rede>Assinatura de acesso compartilhado. Use a tabela a seguir para definir as permissões necessárias.

Parâmetro	Configuração habilitada
Serviços permitidos	Blob
Tipos de recursos permitidos	Objeto, Contêiner
Permissões aceitas	Ler, Gravar, Excluir, Listar, Criar

Para aumentar a segurança e seguir o princípio do menor privilégio, você pode gerar um token SAS para um contêiner específico. Para evitar erros de autenticação, certifique-se de que o contêiner especificado no token SAS corresponda à configuração de destino do fluxo de dados.

Importante

Para usar o portal de experiência de operações para gerenciar segredos, primeiro, as Operações do Azure IoT precisam ser habilitadas com as configurações seguras por meio da definição de um cofre de chaves do Azure e da habilitação de identidades de carga de trabalho. Para saber mais, confira Habilitar configurações seguras na implantação de Operações de IoT do Azure.

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>Token de acesso.

Aqui, em nome do segredo sincronizado, insira um nome para o segredo. Esse nome é usado para fazer referência ao segredo nas configurações do ponto de extremidade do fluxo de dados e é o nome do segredo, conforme armazenado no cluster do Kubernetes.

Em seguida, no nome do segredo do token do Access, selecione Adicionar referência para adicionar o segredo do Azure Key Vault. Na próxima página, selecione o segredo do Azure Key Vault com Adicionar do Azure Key Vault ou Criar novo segredo.

Se você selecionar Criar, insira as seguintes configurações:

Configuração	Descrição
Nome do segredo	O nome do segredo no Azure Key Vault. Escolha um nome que seja fácil de lembrar para selecionar o segredo posteriormente na lista.
Valor do segredo	O token SAS no formato de `'sv=2022-11-02&ss=b&srt=c&sp=rwdlax&se=2023-07-22T05:47:40Z&st=2023-07-21T21:47:40Z&spr=https&sig=<signature>'`.
Definir data de ativação	Se ativada, a data em que o segredo se torna ativo.
Definir a data de validade	Se ativada, a data em que o segredo vence.

Para saber mais sobre segredos, confira Criar e gerenciar segredos nas Operações do Azure IoT.

dataLakeStorageSettings: {
  authentication: {
    method: 'AccessToken'
    accessTokenSettings: {
      secretRef: '<SAS_SECRET_NAME>'
    }
  }
}

Crie um segredo do Kubernetes com o token SAS.

kubectl create secret generic <SAS_SECRET_NAME> -n azure-iot-operations \
--from-literal=accessToken='sv=2022-11-02&ss=b&srt=c&sp=rwdlax&se=2023-07-22T05:47:40Z&st=2023-07-21T21:47:40Z&spr=https&sig=<signature>'

dataLakeStorageSettings:
  authentication:
    method: AccessToken
    accessTokenSettings:
      secretRef: <SAS_SECRET_NAME>

Configurações avançadas

Você pode definir configurações avançadas para o ponto de extremidade do Azure Data Lake Storage Gen2, 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:

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

Captura de tela usando a experiência de operações para definir as configurações avançadas do ADLS V2.

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

dataLakeStorageSettings:
  batching:
    latencySeconds: 100
    maxMessages: 1000

Próximas etapas

Para saber mais sobre fluxos de dados, confira Criar um fluxo de dados.
Para ver um tutorial sobre como usar um fluxo de dados para enviar dados para o Azure Data Lake Storage Gen2, consulte Tutorial: Enviar dados para o Azure Data Lake Storage Gen2.

Compartilhar via