Azure DevOps Task pour Azure Data Explorer

Azure DevOps Services fournit des outils de développement collaboratifs tels que des pipelines haute performance, référentiels Git privés gratuits, tableaux Kanban configurables et fonctionnalités de test continu et automatisé. Azure Pipelines est une fonctionnalité Azure DevOps qui vous permet de gérer CI/CD pour déployer votre code avec des pipelines haute performance fonctionnant avec n'importe quel langage, plateforme ou cloud. Azure Data Explorer - Outils de pipeline est la tâche Azure Pipelines qui vous permet de créer des pipelines de mise en production et de déployer vos modifications de base de données dans vos bases de données Azure Data Explorer. Il est disponible gratuitement dans Visual Studio Marketplace. Cette extension comprend trois tâches de base :

• Commande Azure Data Explorer - Exécuter des commandes d’administration sur un cluster Azure Data Explorer

• Requête Azure Data Explorer - Exécuter des requêtes sur un cluster Azure Data Explorer et analyser les résultats

• Porte de serveur de requête Azure Data Explorer - Tâches sans agent pour contrôler les mises en production en fonction du résultat de la requête

  

Ce document décrit un exemple simple d’utilisation de la tâche Azure Data Explorer – Outils de pipeline pour déployer vos modifications de schéma dans votre base de données. Pour les pipelines CI/CD, consultez la documentation Azure DevOps.

Prérequis

• Un abonnement Azure. Créez un compte Azure gratuit.
• Un cluster et une base de données Azure Data Explorer. Créez un cluster et une base de données.
• Configuration du cluster Azure Data Explorer :
  • Créez Microsoft Entra application en approvisionnant une application Microsoft Entra.
  • Accordez l’accès à votre application Microsoft Entra sur votre base de données Azure Data Explorer en gérant les autorisations de base de données Azure Data Explorer.
• Configuration d'Azure DevOps :
  • Inscrivez-vous pour une organisation gratuite.
  • Créez une organisation.
  • Créez un projet dans Azure DevOps.
  • Écrivez du code avec Git.
• Installation de l’extension :
  • Si vous êtes le propriétaire de l’instance Azure DevOps, installez l’extension à partir de la Place de marché.
  • Si vous n’êtes PAS le propriétaire de l’instance Azure DevOps, contactez son propriétaire et demandez-lui de l’installer.

Préparer votre contenu pour la mise en production

Il existe trois manières d’exécuter des commandes d’administration sur un cluster dans une tâche.

• Utiliser un modèle de recherche pour obtenir plusieurs fichiers de commandes à partir d’un dossier d’agent local (sources de build ou artefacts de mise en production)

  

• Écrire les commandes inline

  

• Spécifier un chemin de fichier pour obtenir les fichiers de commandes directement à partir du contrôle de code source git (recommandé)

  

  Créez les dossiers exemples suivants (Fonctions, Stratégies, Tables) dans votre référentiel Git. Copiez les fichiers disponibles ici dans les dossiers respectifs, comme illustré ci-dessous, et validez les modifications. Les fichiers exemples sont fournis pour exécuter le workflow suivant.

  

  Conseil

  Lorsque vous créez votre propre workflow, nous vous recommandons de rendre votre code idempotent. Par exemple, utilisez .create-merge table au lieu de .create table, et utilisez la fonction .create-or-alter au lieu de la fonction .create.

Créer un pipeline de mise en production

1. Connectez-vous à votre organisation Azure DevOps.

2. Sélectionnez Pipelines>Mises en production dans le menu de gauche, puis Nouveau pipeline.

   

3. La fenêtre Nouveau pipeline de mise en production s'ouvre. Dans l'onglet Pipelines, sous le volet Sélectionner un modèle, sélectionnez Projet vide.

   

4. Sélectionnez le bouton Phase. Dans le volet Phase, ajoutez le nom de la phase. Sélectionnez Enregistrer pour enregistrer votre pipeline.

   

5. Sélectionnez le bouton Ajouter un artefact. Dans le volet Ajouter un artefact, sélectionnez le référentiel où se trouve votre code, renseignez les informations pertinentes, puis cliquez sur Ajouter. Sélectionnez Enregistrer pour enregistrer votre pipeline.

   

6. Dans l'onglet Variables, sélectionnez + Ajouter pour créer une variable pour l'URL de point de terminaison qui sera utilisée dans la tâche. Notez le nom et la valeur du point de terminaison. Sélectionnez Enregistrer pour enregistrer votre pipeline.

   

   Pour rechercher votre Endpoint_URL, la page Vue d’ensemble de votre cluster Azure Data Explorer dans le portail Azure contient l’URI du cluster Azure Data Explorer. Construisez l’URI au format suivant https://<Azure Data Explorer cluster URI>?DatabaseName=<DBName>. Par exemple : https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

Créer des tâches pour déployer les dossiers

1. Dans l'onglet Pipeline, cliquez sur 1 travail, 0 tâche pour ajouter des tâches.

   

2. Répétez les étapes suivantes pour créer des tâches de commande afin de déployer des fichiers à partir des dossiers Tables, FonctionsStratégies :

   

   1. Sous l’onglet Tâches, sélectionnez + par Travail d’agent et recherchez Azure Data Explorer.

   2. Sous Exécuter la commande Azure Data Explorer, sélectionnez Ajouter.

   3. Sélectionnez Commande Kusto et mettez à jour la tâche avec les informations suivantes :

      • Nom d’affichage : nom de la tâche. Par exemple, Deploy <FOLDER> où <FOLDER> est le nom du dossier pour la tâche de déploiement que vous créez.

      • Chemin d’accès au fichier : pour chaque dossier, spécifiez le chemin au format */<FOLDER>/*.csl, où <FOLDER> est le dossier approprié pour la tâche.

      • URL de point de terminaison : spécifiez la variable EndPoint URL créée à l’étape précédente.

      • Utiliser le point de terminaison de service : sélectionnez cette option.

      • Point de terminaison de service : sélectionnez un point de terminaison de service existant ou créez-en un ( + Nouveau) en fournissant les informations suivantes dans la fenêtre Ajouter une connexion au service Azure Data Explorer :

        Paramètre	Valeur suggérée
        Nom de connexion	Entrer un nom pour identifier ce point de terminaison de service
        URL du cluster	La valeur se trouve dans la section Vue d'ensemble de votre cluster Azure Data Explorer dans le portail Azure
        ID de principal de service	Entrez l’ID d’application Microsoft Entra (créé en tant que prérequis)
        Clé d'application du principal de service	Entrez la clé d’application Microsoft Entra (créée en tant que prérequis)
        ID de locataire Microsoft Entra	Entrez votre locataire Microsoft Entra (par exemple, microsoft.com ou contoso.com)

      Cochez la case Autoriser tous les pipelines à utiliser cette connexion, puis sélectionnez OK.

      

3. Sélectionnez Enregistrer puis, sous l’onglet Tâches, vérifiez qu’il existe trois tâches : Déployer Tables, Déployer Fonctions et Déployer Stratégies.

   

Créer une tâche de requête

Si nécessaire, créez une tâche pour exécuter une requête sur le cluster. L’exécution de requêtes dans un pipeline build ou mise en production peut être utilisée pour valider un jeu de données et faire en sorte qu’une étape réussisse ou échoue en fonction des résultats de la requête. Les critères de réussite des tâches peuvent être basés sur un seuil de nombre de lignes ou sur une valeur unique, en fonction de ce que la requête retourne.

1. Sous l’onglet Tâches, sélectionnez + par Travail d’agent et recherchez Azure Data Explorer.

2. Sous Exécuter la requête Azure Data Explorer, sélectionnez Ajouter.

3. Sélectionnez Requête Kusto et mettez à jour la tâche avec les informations suivantes :

   • Nom d’affichage : nom de la tâche. Par exemple, Interroger le cluster.
   • Type : sélectionnez Inline.
   • Requête : entrez la requête que vous souhaitez exécuter.
   • URL du point de terminaison : spécifiez la variable EndPoint URL créée plus tôt.
   • Utiliser le point de terminaison de service : sélectionnez cette option.
   • Point de terminaison de service : sélectionnez un point de terminaison de service.

   

4. Sous Résultats de la tâche, sélectionnez les critères de réussite de la tâche en fonction des résultats de votre requête, comme suit :

   • Si votre requête retourne des lignes, sélectionnez Nombre de lignes et indiquez les critères requis.

     

   • Si votre requête retourne une valeur, sélectionnez Valeur unique et indiquez le résultat attendu.

     

Créer une tâche de porte de serveur de requête

Si nécessaire, créez une tâche pour exécuter une requête sur un cluster et contrôler la progression de la mise en production dans l’attente du nombre de lignes des résultats de la requête. La tâche de porte de serveur de requête est un travail sans agent, ce qui signifie que la requête s’exécute directement sur Azure DevOps Server.

1. Sous l’onglet Tâches, sélectionnez + en regard de Travail sans agent et recherchez Azure Data Explorer.

2. Sous Exécuter la requête Azure Data Explorer - Porte de serveur de requête, sélectionnez Ajouter.

3. Sélectionnez Porte de serveur de requête Kusto, puis Test de porte de serveur.

   

4. Configurez la tâche en fournissant les informations suivantes :

   • Nom d’affichage : nom de la porte
   • Point de terminaison de service : sélectionnez un point de terminaison de service.
   • Nom de la base de données : spécifiez le nom de la base de données.
   • Type : sélectionnez Requête inline.
   • Requête : entrez la requête que vous souhaitez exécuter.
   • Seuil maximal : spécifiez le nombre maximal de lignes pour les critères de réussite de la requête.

   

Notes

Vous devez voir des résultats semblables à ce qui suit lors de l’exécution de la mise en production.

Exécuter la mise en production

1. Sélectionnez + Mise en production>Créer une mise en production pour créer manuellement une mise en production.

   

2. Dans l'onglet Journaux, vérifiez que le déploiement a réussi.

   

Vous avez créé un pipeline de mise en production en vue d’un déploiement en préproduction.

Configuration du pipeline Yaml

Les tâches peuvent être configurées à la fois via l’interface utilisateur web Azure DevOps (comme indiqué ci-dessus) et par le biais du code Yaml dans le schéma de pipeline

Exemple d’utilisation de commande d’administration

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

Exemple d’utilisation de requête

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