Compartilhar via

Configurar um estágio de origem do SQL Server na versão prévia do Processador de Dados do Azure IoT

  • Artigo

Importante

O recurso Pré-visualização de Operações do Azure IoT — habilitado 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.

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.

A fase de origem é a primeira fase necessária em um pipeline de versão prévia do Processador de Dados do Azure IoT. O estágio de origem obtém dados no pipeline de processamento de dados e os prepara para processamento adicional. O estágio de origem do SQL Server permite ler dados de um banco de dados do Microsoft SQL Server em um intervalo definido pelo usuário.

No estágio de origem, você define:

  • Detalhes da conexão para o SQL Server.
  • O intervalo no qual consultar o banco de dados do SQL Server. O estágio aguarda um resultado antes de redefinir o temporizador de intervalo.
  • Uma configuração de particionamento com base em seus requisitos específicos de processamento de dados.

Pré-requisitos

  • Uma instância implantada da Versão Prévia do Processador de Dados do Azure IoT que inclui o componente opcional do Processador de Dados.
  • Um banco de dados do SQL Server com todos os dados brutos necessários disponíveis está operacional e acessível.

Preparar o banco de dados do SQL Server

Antes de ler do banco de dados do SQL Server, você precisa conceder acesso ao banco de dados no pipeline. Você pode usar Username/Password, Managed identity ou Service principal para autenticar o pipeline no banco de dados. A vantagem de usar uma identidade gerenciada é que você não precisa gerenciar o ciclo de vida da entidade de serviço ou os detalhes da senha. A identidade gerenciada é gerenciada automaticamente pelo Azure e está vinculada ao ciclo de vida do recurso ao qual está atribuída.

Para criar uma entidade de serviço com um segredo de cliente:

  1. Use o comando da CLI do Azure a seguir para criar uma entidade de serviço.

    az ad sp create-for-rbac --name <YOUR_SP_NAME>

  2. O resultado desse comando inclui uma appId, displayName, password e tenant. Anote esses valores para usá-los ao configurar o acesso a um de seus recursos de nuvem como o Microsoft Fabric, criar um segredo e configurar um destino de pipeline:

    {
    "appId": "<app-id>",
    "displayName": "<name>",
    "password": "<client-secret>",
    "tenant": "<tenant-id>"
}

Para conceder acesso à ID da entidade de segurança no banco de dados do SQL Server, execute o seguinte comando no banco de dados:

CREATE USER processor FROM EXTERNAL PROVIDER WITH OBJECT_ID=<principalId>;

Observação

Para executar o comando anterior, você deve usar a ID do Entra listada como admin no SQL Server.

Para que o estágio da origem conecte seu banco de dados do SQL Server, ele precisa de acesso a um segredo que contenha os detalhes da autenticação. Para criar um segredo:

  1. Use o seguinte comando para adicionar um segredo ao seu Azure Key Vault que contém o segredo do cliente no qual você fez uma anotação sobre quando criou a entidade de serviço:

    az keyvault secret set --vault-name <your-key-vault-name> --name AccessADXSecret --value <client-secret>

  2. Adicione a referência secreta ao seu cluster do Kubernetes seguindo as etapas em Gerenciar segredos para sua implantação das Operações do Azure IoT.

Configurar a origem do SQL Server

Para configurar a origem do SQL Server:

  • Forneça detalhes do banco de dados do SQL Server. Essa configuração inclui o nome do servidor e uma consulta para recuperar os dados.
  • Especifique o método de autenticação. Atualmente limitado à autenticação baseada em nome de usuário/senha ou entidade de serviço.

A tabela a seguir descreve os parâmetros de configuração de origem do SQL Server:

Campo Type Descrição Obrigatório Padrão Exemplo
Nome String Um nome visível para o cliente para o estágio de origem. Obrigatório NA erp-database
Descrição Cadeia de caracteres Uma descrição visível do cliente do estágio de origem. Opcional NA Enterprise database
Host do servidor String A URL a ser usada para se conectar ao servidor. Obrigatório NA https://contoso.com/some/url/path
Porta do servidor Inteiro O número da porta ao qual se conectar no servidor. Obrigatório 1433 1433
Autenticação Tipo de autenticação O método de autenticação para se conectar ao servidor. Uma opção entre None, Username/Password, Managed identity ou Service principal. Opcional NA Username/Password
Nome de usuário/Senha > Nome de usuário String O nome de usuário para a autenticação de nome de usuário/senha Sim NA myuser
Nome de usuário/senha > segredo String Referência à senha armazenada no Azure Key Vault. Sim Yes AKV_USERNAME_PASSWORD
ID do locatário da entidade de serviço > String A ID do locatário da entidade de serviço. Sim NA <Tenant ID>
ID do cliente da entidade de serviço > String A ID do cliente da entidade de serviço. Sim NA <Client ID>
Segredo da entidade de serviço > String Referência ao segredo do cliente da entidade de serviço armazenado no Azure Key Vault. Sim NA AKV_SERVICE_PRINCIPAL
Banco de dados String O nome do banco de dados do SQL Server a ser consultado. Obrigatório NA erp_db
Consulta de dados String A consulta a ser executada no banco de dados. Obrigatório NA SELECT * FROM your_table WHERE column_name = foo
Intervalo de consulta Duration Representação de cadeia de caracteres do tempo a aguardar antes da próxima chamada à API. Obrigatório 10s 24h
Formato de dados Formato Formato de dados dos dados de entrada Obrigatório NA {"type": "json"}
Particionamento Particionamento Configuração de particionamento para o estágio de origem. Obrigatório NA Consulte particionamento

Para saber mais sobre segredos, confira Gerenciar segredos para sua implantação da versão prévia das Operações do Azure IoT.

Observação

Solicita o tempo limite em 30 segundos se não houver resposta do SQL Server.

Selecionar formato de dados

Em um pipeline do Processador de Dados, o campo de formato no estágio de origem especifica como desserializar os dados de entrada. Por padrão, o pipeline do Processador de Dados usa o formato raw que significa que ele não converte os dados de entrada. Para usar muitos recursos do Processador de Dados, como Filter ou Enrich estágios em um pipeline, você deve desserializar seus dados no estágio de entrada. Você pode optar por desserializar seus dados de entrada de formatos JSON, jsonStream, MessagePack, CBOR, CSV ou Protobuf em uma mensagem legível do Processador de Dados para usar a funcionalidade completa do Processador de Dados.

As tabelas a seguir descrevem as diferentes opções de configuração de desserialização:

Campo Descrição Obrigatório Padrão Valor
Formato de Dados O tipo do formato de dados. Sim Raw Raw JSON jsonStream MessagePack CBOR CSV Protobuf

O campo Data Format é obrigatório e seu valor determina os outros campos necessários.

Para desserializar mensagens CSV, você também precisa especificar os seguintes campos:

Campo Descrição Obrigatório Valor Exemplo
Cabeçalho Se os dados CSV incluem uma linha de cabeçalho. Sim Yes No No
Nome Nome da coluna no CSV Sim - temp, asset
Caminho O caminho jq na mensagem em que as informações da coluna são adicionadas. Não - O caminho jq padrão é o nome da coluna
Tipo de Dados O tipo de dados dos dados na coluna e como eles são representados dentro do pipeline do Processador de Dados. Não String, Float, Integer, Boolean, Bytes Padrão: String

Para desserializar mensagens Protobuf, você também precisa especificar os seguintes campos:

Campo Descrição Obrigatório Valor Exemplo
Descritor O descritor codificado em base64 para a definição de Protobuf. Sim - Zhf...
Message O nome do tipo de mensagem usado para formatar os dados. Sim - pipeline
Pacote O nome do pacote no descritor em que o tipo é definido. Sim - schedulerv1

Observação

O Processador de Dados dá suporte a apenas um tipo de mensagem em cada arquivo .proto.

Configurar particionamento

O particionamento em um pipeline divide os dados de entrada em partições separadas. O particionamento permite o paralelismo de dados no pipeline, o que pode melhorar a taxa de transferência e reduzir a latência. As estratégias de particionamento afetam a forma como os dados são processados nos outros estágios do pipeline. Por exemplo, o último estágio de valor conhecido e o estágio de agregação operam em cada partição lógica.

Para particionar seus dados, especifique uma estratégia de particionamento e o número de partições a serem usadas:

Campo Descrição Obrigatório Padrão Exemplo
Tipo de partição O tipo de particionamento a ser usado: partição ID ou partição Key Obrigatório ID ID
Expressão de partição A expressão jq a ser usada na mensagem de entrada para calcular a partição ID ou partição Key Obrigatório 0 .payload.header
Número of partições O número de partições em um pipeline do Processador de Dados. Obrigatório 1 1

O Processador de Dados adiciona metadados à mensagem de entrada. Confira a visão geral da estrutura de mensagens do Processador de Dados para entender como especificar corretamente a expressão de particionamento executada na mensagem de entrada. Por padrão, a expressão de particionamento é definida como 0 com o tipo de partição como ID para enviar todos os dados de entrada para uma única partição.

Para obter recomendações e saber mais, consulte O que é particionamento?.

Conteúdo relacionado