Tarefa Azure DevOps para o Azure Data Explorer

Os Serviços de DevOps do Azure fornecem ferramentas de colaboração de desenvolvimento, como pipelines de alto desempenho, repositórios Git privados gratuitos, quadros Kanban configuráveis e amplos recursos de testes automatizados e contínuos. O Azure Pipelines é um recurso de DevOps do Azure que permite gerenciar CI/CD para implantar seu código com pipelines de alto desempenho que funcionam com qualquer idioma, plataforma e nuvem. Azure Data Explorer - Ferramentas de Pipeline é a tarefa do Azure Pipelines que permite criar pipelines de liberação e implantar suas alterações de banco de dados em seus bancos de dados do Azure Data Explorer. Ele está disponível gratuitamente no Visual Studio Marketplace. A extensão inclui as seguintes tarefas básicas:

Comando Azure Data Explorer - Execute comandos admin em um cluster do Azure Data Explorer
Consulta do Azure Data Explorer - Execute consultas em um cluster do Azure Data Explorer e analise os resultados
Porta do servidor de consulta do Azure Data Explorer - Tarefa sem agente para controlar lançamentos, dependendo do resultado da consulta

Este documento descreve um exemplo simples de como usar a tarefa Azure Data Explorer - Ferramentas de Pipeline para implantar alterações de esquema em seu banco de dados. Para obter pipelines de CI/CD completos, consulte a documentação do Azure DevOps.

Pré-requisitos

Uma assinatura do Azure. Crie uma conta do Azure gratuita.
Um cluster e um banco de dados do Azure Data Explorer. Crie um cluster e um banco de dados.
Configuração do cluster do Azure Data Explorer:
- Crie o aplicativo Microsoft Entra provisionando um aplicativo Microsoft Entra.
- Conceda acesso ao seu Aplicativo Microsoft Entra em seu banco de dados do Azure Data Explorer gerenciando as permissões do banco de dados do Azure Data Explorer.
Configuração do Azure DevOps:
Instalação de extensão:
- Se você for o proprietário da instância do Azure DevOps, instale a extensão do Marketplace, caso contrário, entre em contato com o proprietário da instância do Azure DevOps e peça que ele a instale.

Prepare seu conteúdo para lançamento

Você pode usar os seguintes métodos para executar comandos admin em um cluster dentro de uma tarefa:

Captura de tela mostrando as opções de controle do código-fonte do comando.

Use um padrão de pesquisa para obter vários arquivos de comando de uma pasta do agente local (criar fontes ou liberar artefatos).
Escreva comandos em linha.
Especifique um caminho de arquivo para obter arquivos de comando diretamente do controle de origem do Git (recomendado).

Crie as seguintes pastas de exemplo (Funções, Políticas, Tabelas) no repositório Git. Copie os arquivos do repositório de amostras para as respetivas pastas e confirme as alterações. Os arquivos de exemplo são fornecidos para executar o fluxo de trabalho a seguir.

Sugestão

Ao criar seu próprio fluxo de trabalho, recomendamos tornar seu código idempotente. Por exemplo, use .create-merge table em vez de .create table, e use a .create-or-alter função em vez da .create função.

Criar um pipeline de lançamento

Entre na sua organização do Azure DevOps.
Selecione Pipelines>Releases no menu à esquerda e, em seguida, selecione New pipeline.
A janela Novo pipeline de liberação é aberta. Na guia Pipelines , no painel Selecionar um modelo , selecione Trabalho vazio.
Selecione o botão Etapa. No painel Palco , adicione o Nome do palco e selecione Salvar para salvar o pipeline.
Selecione o botão Adicionar um artefato. No painel Adicionar um artefato , selecione o repositório onde o código existe, preencha as informações relevantes e selecione Adicionar. Selecione Salvar para salvar seu pipeline.
Na guia Variáveis , selecione + Adicionar para criar uma variável para a URL do Ponto Final usada na tarefa. Insira o Nome e o Valor do ponto de extremidade e selecione Salvar para salvar seu pipeline.

Para localizar a URL do ponto final, vá para a página de visão geral do cluster do Azure Data Explorer no portal do Azure e copie o URI do cluster. Construa a variável URI no seguinte formato https://<ClusterURI>?DatabaseName=<DBName>. Por exemplo, https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

Criar uma tarefa para implantar as pastas

Na guia Pipeline , selecione 1 trabalho, 0 tarefa para adicionar tarefas.

Repita as seguintes etapas para criar tarefas de comando para implantar arquivos das pastas Tabelas, Funções e Políticas :

Captura de ecrã a mostrar como adicionar um comando de administração do Azure Data Explorer.

Na guia Tarefas , selecione + por trabalho do agente e procure o Azure Data Explorer.
Em Executar Comando do Azure Data Explorer, selecione Adicionar.

Selecione Kusto Command e atualize a tarefa com as seguintes informações:

Nome para exibição: nome da tarefa. Por exemplo, Deploy <FOLDER> onde <FOLDER> é o nome da pasta para a tarefa de implantação que você está criando.
Caminho do arquivo: Para cada pasta, especifique o caminho como */<FOLDER>/*.csl onde <FOLDER> está a pasta relevante para a tarefa.
URL do ponto de extremidade: especifique a EndPoint URL variável criada na etapa anterior.
Usar ponto de extremidade de serviço: selecione esta opção.

Ponto de extremidade de serviço: selecione um ponto de extremidade de serviço existente ou crie um novo (+ Novo) fornecendo as seguintes informações na janela Adicionar conexão de serviço do Azure Data Explorer :

Configuração	Valor sugerido
Método de autenticação	Configurar Credenciais de Identidade Federada (FIC) (recomendado) ou selecionar Autenticação de Principal de Serviço (SPA).
Nome da conexão	Insira um nome para identificar esse ponto de extremidade de serviço
Cluster Url	O valor pode ser encontrado na seção de visão geral do seu Cluster do Azure Data Explorer no portal do Azure
ID do principal de serviço	Insira a ID do aplicativo Microsoft Entra (criada como pré-requisito)
Chave do aplicativo principal do serviço	Insira a chave do aplicativo Microsoft Entra (criada como pré-requisito)
ID do locatário Microsoft Entra	Insira seu locatário do Microsoft Entra (como microsoft.com ou contoso.com)

Marque a caixa de seleção Permitir que todos os pipelines usem esta conexão e selecione OK.

Captura de ecrã a mostrar como adicionar uma ligação de serviço.

Selecione Salvar e, na guia Tarefas , verifique se há três tarefas: Implantar Tabelas, Implantar Funções e Implantar Políticas.

Criar uma tarefa de Consulta

Se necessário, crie uma tarefa para executar uma consulta no cluster. A execução de consultas em um pipeline de compilação ou liberação pode ser usada para validar um conjunto de dados e fazer com que uma etapa seja bem-sucedida ou falhada com base nos resultados da consulta. Os critérios de sucesso das tarefas podem ser baseados em um limite de contagem de linhas ou em um único valor, dependendo do que a consulta retorna.

Na guia Tarefas , selecione + por trabalho do agente e procure o Azure Data Explorer.
Em Executar Consulta do Azure Data Explorer, selecione Adicionar.
Selecione Kusto Query e atualize a tarefa com as seguintes informações:
- Nome para exibição: nome da tarefa. Por exemplo, cluster de consulta.
- Tipo: Selecione Inline.
- Consulta: introduza a consulta que pretende executar.
- URL do ponto de extremidade: especifique a EndPoint URL variável criada anteriormente.
- Usar ponto de extremidade de serviço: selecione esta opção.
- Ponto de extremidade de serviço: selecione um ponto de extremidade de serviço.
Em Resultados da Tarefa, selecione os critérios de sucesso da tarefa com base nos resultados da sua consulta, da seguinte forma:
- Se sua consulta retornar linhas, selecione Contagem de linhas e forneça os critérios necessários.
- Se a consulta retornar um valor, selecione Valor único e forneça o resultado esperado.

Criar uma tarefa de Gateway do Servidor de Consultas

Se necessário, crie uma tarefa para executar uma consulta em um cluster e condicione o progresso da liberação à contagem de linhas dos resultados da consulta pendentes. A tarefa Porta de Consulta do Servidor é um trabalho sem agente, o que significa que a consulta é executada diretamente no Servidor de DevOps do Azure.

Na guia Tarefas , selecione + por trabalho sem agente e procure o Azure Data Explorer.
Na opção Executar Gateway do Servidor de Consultas do Azure Data Explorer, selecione Adicionar.
Selecione Kusto Query Server Gate e, em seguida, selecione Server Gate Test.
Configure a tarefa fornecendo as seguintes informações:
- Nome para exibição: Nome do portão.
- Ponto de extremidade de serviço: selecione um ponto de extremidade de serviço.
- Nome do banco de dados: especifique o nome do banco de dados.
- Tipo: Selecione Consulta embutida.
- Consulta: introduza a consulta que pretende executar.
- Limite máximo: especifique a contagem máxima de linhas para os critérios de êxito da consulta.

Observação

Você deve ver resultados como os seguintes ao executar a versão.

Captura de ecrã a mostrar um exemplo de resultados de tarefas da Porta de Consulta.

Executar o lançamento

Selecione + Versão>Criar versão para iniciar uma versão.
Na guia Logs , verifique se o status da implantação foi bem-sucedido.

A criação de um pipeline de lançamento para implantação na pré-produção está concluída.

Suporte de autenticação sem chave para tarefas de DevOps do Azure Data Explorer

A extensão dá suporte à autenticação sem chave para clusters do Azure Data Explorer. A autenticação sem chave permite autenticar em clusters do Azure Data Explorer sem usar uma chave. É mais seguro e mais fácil de gerir.

Usar a autenticação FIC (Federated Identity Credentials) em uma conexão de serviço do Azure Data Explorer

Na sua instância de DevOps, vá para Configurações> do ProjetoConexões> de serviçoNova conexão>de serviço Azure Data Explorer.
Selecione Credenciais de Identidade Federada, insira a URL do cluster, a ID da entidade de serviço, a ID do locatário, um nome de conexão de serviço e selecione Salvar.
No portal do Azure, abra o aplicativo Microsoft Entra para a entidade de serviço especificada.
Em Certificados e segredos, selecione Credenciais federadas.
Selecione Adicionar credencial e, em seguida, para Cenário de credenciais federadas, selecione Outro emissor e preencha as configurações usando as seguintes informações:
- Emissor: <https://vstoken.dev.azure.com/{System.CollectionId}> onde {System.CollectionId} é a ID de coleção da sua organização do Azure DevOps. Você pode encontrar o ID da coleção das seguintes maneiras:
  - No pipeline de versão clássica do Azure DevOps, selecione Inicializar trabalho. O ID da coleção é exibido nos logs.
- Identificador de assunto: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> onde {DevOps_Org_name} é o nome da organização do Azure DevOps, {Project_Name} é o nome do projeto e {Service_Connection_Name} é o nome da conexão de serviço que você criou anteriormente.
  
  Observação
  
  Se houver espaço no nome da conexão de serviço, você poderá usá-lo com o espaço no campo. Por exemplo: sc://MyOrg/MyProject/My Service Connection.
- Nome: insira um nome para a credencial.
Selecione Adicionar.

Usar credenciais de identidade federada ou identidade gerenciada em uma conexão de serviço do Azure Resource Manager (ARM)

Na sua instância de DevOps, vá para Configurações> do ProjetoConexões> de serviçoNova conexão> de serviçoAzure Resource Manager.
Em Método de autenticação, selecione Federação de Identidades de Carga de Trabalho (automática) para continuar. Você também pode usar a opção manual Workload Identity Federation (manual) para especificar os detalhes da Workload Identity Federation ou a opção Managed Identity . Saiba mais sobre como configurar uma identidade gerenciada usando o Gerenciamento de Recursos do Azure em Conexões de Serviço do Azure Resource Manager (ARM).
Preencha os detalhes necessários, selecione Verificar e, em seguida, selecione Guardar.

Configuração de pipeline YAML

Você pode configurar tarefas usando a interface do usuário da Web do Azure DevOps ou o código YAML dentro do esquema de pipeline.

Exemplo de comando Admin

steps:
- task: Azure-Kusto.PublishToADX.PublishToADX.PublishToADX@4
  displayName: '<Task Name>'
  inputs:
    targetType: 'inline'
    script: '<inline Script>'
    waitForOperation: true
    kustoUrls: '$(CONNECTIONSTRING):443?DatabaseName=""'
    authType: 'armserviceconn'
    connectedServiceARM: '<ARM Service Endpoint Name>'
    serialDelay: 1000
  `continueOnError: true`
  condition: ne(variables['ProductVersion'], '') ## Custom condition Sample

Exemplo de consulta

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@4
  displayName: '<Task Display Name>'
  inputs:
    targetType: 'inline'
    script: |
     let badVer=
     RunnersLogs | where Timestamp > ago(30m)
         | where EventText startswith "$$runnerresult" and Source has "ShowDiagnostics"
         | extend State = extract(@"Status='(.*)', Duration.*",1, EventText)
         | where State == "Unhealthy"
         | extend Reason = extract(@'"NotHealthyReason":"(.*)","IsAttentionRequired.*',1, EventText)
         | extend Cluster = extract(@'Kusto.(Engine|DM|CM|ArmResourceProvider).(.*).ShowDiagnostics',2, Source)
         | where Reason != "Merge success rate past 60min is < 90%"
         | where Reason != "Ingestion success rate past 5min is < 90%"
         | where Reason != "Ingestion success rate past 5min is < 90%, Merge success rate past 60min is < 90%"
         | where isnotempty(Cluster)
         | summarize max(Timestamp) by Cluster,Reason
         | order by  max_Timestamp desc
         | where Reason startswith "Differe"
         | summarize by Cluster
     ;
      DimClusters | where Cluster in (badVer)
     | summarize by Cluster , CmConnectionString , ServiceConnectionString ,DeploymentRing
     | extend ServiceConnectionString = strcat("#connect ", ServiceConnectionString)
     | where DeploymentRing == "$(DeploymentRing)"
    kustoUrls: 'https://<ClusterName>.kusto.windows.net?DatabaseName=<DatabaseName>'
    authType: 'kustoserviceconn'
    connectedServiceName: '<connection service name>'
    minThreshold: '0'
    maxThreshold: '10'
  continueOnError: true

Feedback

Esta página foi útil?

Last updated on 2025-10-10