Tarefa do Azure DevOps para Data Explorer do Azure

O Azure DevOps Services fornece ferramentas de colaboração de desenvolvimento, tais como pipelines de alto desempenho, repositórios Git privados gratuitos, quadros Kanban configuráveis e capacidades de testes automatizados e contínuos extensivos. O Azure Pipelines é uma capacidade do Azure DevOps que lhe permite gerir CI/CD para implementar o seu código com pipelines de alto desempenho que funcionam com qualquer linguagem, plataforma e cloud. Azure Data Explorer – Ferramentas de Pipeline é a tarefa dos Pipelines do Azure que lhe permite criar pipelines de versão e implementar as alterações da base de dados nas bases de dados do Azure Data Explorer. Está disponível gratuitamente no Visual Studio Marketplace. Esta extensão inclui 3 tarefas básicas:

• Comando Data Explorer do Azure – Executar Comandos de Administração num cluster de Data Explorer do Azure

• Consulta do Azure Data Explorer - Executar Consultas num cluster do Azure Data Explorer e analisar os resultados

• Azure Data Explorer Query Server Gate – versões de tarefas sem agente para Gate, dependendo do resultado da consulta

  

Este documento descreve um exemplo simples sobre a utilização da tarefa Azure Data Explorer – Ferramentas de Pipeline para implementar as alterações de esquema na base de dados. Para obter pipelines ci/CD completos, veja a documentação do Azure DevOps.

Pré-requisitos

• Uma subscrição do Azure. Crie uma conta gratuita do Azure.
• Um cluster e uma base de dados do Azure Data Explorer. Criar um cluster e uma base de dados.
• Configuração do cluster do Azure Data Explorer:
  • Crie Microsoft Entra aplicação ao aprovisionar uma aplicação Microsoft Entra.
  • Conceda acesso à sua Aplicação Microsoft Entra na base de dados do Azure Data Explorer ao gerir as permissões da base de dados do Azure Data Explorer.
• Configuração do Azure DevOps:
  • Inscreva-se numa organização gratuita.
  • Criar uma organização.
  • Criar um projeto no Azure DevOps.
  • Código com Git.
• Instalação da Extensão:
  • Se for o proprietário da instância do Azure DevOps, instale a extensão a partir do Marketplace.
  • Se não for o proprietário da instância do Azure DevOps, contacte o proprietário e peça-lhe para o instalar.

Preparar o seu conteúdo para lançamento

São três formas de executar comandos de administrador no cluster numa tarefa.

• Utilizar um padrão de pesquisa para obter vários ficheiros de comandos a partir de uma pasta de agente local (Origens de compilação ou artefactos de versão)

  

• Escrever comandos inline

  

• Especifique um caminho de ficheiro para obter ficheiros de comandos diretamente a partir do controlo de origem do git (recomendado)

  

  Crie as seguintes pastas de exemplo (Funções, Políticas, Tabelas) no seu repositório Git. Copie os ficheiros daqui para as respetivas pastas, conforme visto abaixo, e consolide as alterações. Os ficheiros de exemplo são fornecidos para executar o fluxo de trabalho seguinte.

  

  Dica

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

Criar um pipeline de versão

1. Inicie sessão na sua organização do Azure DevOps.

2. Selecione Versões> dePipelines no menu esquerdo e selecione Novo pipeline.

   

3. É aberta a janela Novo pipeline de versão . No separador Pipelines , no painel Selecionar um modelo , selecione Esvaziar tarefa.

   

4. Selecione o botão Fase . No painel Fase , adicione o Nome da fase. Selecione Guardar para guardar o pipeline.

   

5. Selecione Adicionar um botão de artefacto . No painel Adicionar um artefacto , selecione o repositório onde o código existe, preencha as informações relevantes e clique em Adicionar. Selecione Guardar para guardar o pipeline.

   

6. No separador Variáveis , selecione + Adicionar para criar uma variável para o URL de Ponto Final que será utilizado na tarefa. Escreva o Nome e o Valor do ponto final. Selecione Guardar para guardar o pipeline.

   

   Para localizar a sua Endpoint_URL, a página de descrição geral do Cluster de Data Explorer do Azure no portal do Azure contém o URI do cluster do Azure Data Explorer. Construa o URI no seguinte formato https://<Azure Data Explorer cluster URI>?DatabaseName=<DBName>. Por exemplo, https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

Criar tarefas para implementar as pastas

1. No separador Pipeline , clique em 1 tarefa, 0 tarefa para adicionar tarefas.

   

2. Repita os seguintes passos para criar tarefas de comando para implementar ficheiros a partir das pastas Tabelas, Funções e Políticas:

   

   1. No separador Tarefas, selecione + por Tarefa do agente e procure Azure Data Explorer.

   2. Em Executar o Comando Data Explorer do Azure, selecione Adicionar.

   3. Selecione Comando Kusto e atualize a tarefa com as seguintes informações:

      • Nome a apresentar: nome da tarefa. Por exemplo, Deploy <FOLDER> onde <FOLDER> está o nome da pasta para a tarefa de implementação que está a criar.

      • Caminho do ficheiro: para cada pasta, especifique o caminho como */<FOLDER>/*.csl onde <FOLDER> está a pasta relevante para a tarefa.

      • URL do ponto final: especifique a EndPoint URL variável criada no passo anterior.

      • Utilizar o Ponto Final de Serviço: selecione esta opção.

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

        Definição	Valor sugerido
        Nome da ligação	Introduza um nome para identificar este ponto final de serviço
        Cluster Url	O valor pode ser encontrado na secção de descrição geral do Cluster de Data Explorer do Azure no portal do Azure
        ID do Principal de Serviço	Introduza o ID da Aplicação Microsoft Entra (criado como pré-requisito)
        Chave de Aplicação principal de serviço	Introduza a Chave de Aplicação Microsoft Entra (criada como pré-requisito)
        ID do inquilino Microsoft Entra	Introduza o seu inquilino de Microsoft Entra (como microsoft.com ou contoso.com)

      Selecione Permitir que todos os pipelines utilizem esta caixa de verificação de ligação e, em seguida, selecione OK.

      

3. Selecione Guardar e, em seguida, no separador Tarefas , verifique se existem três tarefas: Implementar Tabelas, Implementar Funções e Implementar Políticas.

   

Criar uma tarefa de Consulta

Se necessário, crie uma tarefa para executar uma consulta no cluster. A execução de consultas num pipeline de Compilação ou Versão pode ser utilizada para validar um conjunto de dados e ter um passo bem-sucedido ou falhar com base nos resultados da consulta. Os critérios de êxito das tarefas podem basear-se num limiar de contagem de linhas ou num único valor, consoante o que a consulta devolver.

1. No separador Tarefas, selecione + por Tarefa do agente e procure Azure Data Explorer.

2. Em Executar o Azure Data Explorer Consulta, selecione Adicionar.

3. Selecione Consulta Kusto e atualize a tarefa com as seguintes informações:

   • Nome a apresentar: nome da tarefa. Por exemplo, Cluster de consultas.
   • Tipo: selecione Inline.
   • Consulta: introduza a consulta que pretende executar.
   • URL do ponto final: especifique a EndPoint URL variável criada anteriormente.
   • Utilizar Ponto Final de Serviço: selecione esta opção.
   • Ponto Final de Serviço: selecione um ponto final de serviço.

   

4. Em Resultados da Tarefa, selecione os critérios de êxito da tarefa com base nos resultados da consulta, da seguinte forma:

   • Se a consulta devolver linhas, selecione Contagem de Linhas e forneça os critérios necessários.

     

   • Se a consulta devolver um valor, selecione Valor Único e forneça o resultado esperado.

     

Criar uma tarefa da Porta do Servidor de Consultas

Se necessário, crie uma tarefa para executar uma consulta num cluster e controlar o progresso da versão enquanto se aguarda a Contagem de Linhas dos Resultados da Consulta. A tarefa Da Porta de Consulta do Servidor é uma tarefa sem agente, o que significa que a consulta é executada diretamente no Azure DevOps Server.

1. No separador Tarefas, selecione + por Tarefa sem agente e procure Azure Data Explorer.

2. Em Executar o Azure Data Explorer Porta do Servidor de Consultas, selecione Adicionar.

3. Selecione Porta do Servidor de Consulta Kusto e, em seguida, selecione Teste da Porta do Servidor.

   

4. Configure a tarefa que fornece as seguintes informações:

   • Nome a apresentar: nome da porta.
   • Ponto Final de Serviço: selecione um ponto final de serviço.
   • Nome da base de dados: especifique o nome da base de dados.
   • Tipo: selecione Consulta inline.
   • Consulta: introduza a consulta que pretende executar.
   • Limiar máximo: especifique a contagem máxima de linhas para os critérios de êxito da consulta.

   

Executar a versão

1. Selecione + Versão>Criar versão para criar uma versão.

   

2. No separador Registos , verifique se o estado da implementação foi bem-sucedido.

   

Concluiu agora a criação de um pipeline de versão para implementação para pré-produção.

Configuração do Pipeline yaml

As tarefas podem ser configuradas através da IU Web do Azure DevOps (conforme mostrado acima) e através do código Yaml no esquema do pipeline

Utilização do Exemplo de Comando Administração

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

Utilização de Exemplo de Consulta

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@1
  displayName: '<Task Display Name>'
  inputs:
    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=<DataBaneName>'
    customAuth: true
    connectedServiceName: '<Service Endpoint Name>'
  continueOnError: true