Tâche Azure DevOps 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. L’extension inclut les tâches de base suivantes :

• 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 verrouillage du serveur de requêtes Azure Data Explorer - Tâche sans agent pour contrôler les publications 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 - Pipeline Tools pour déployer des modifications de schéma dans votre base de données. Pour des pipelines CI/CD complètes, 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 d'un cluster Azure Data Explorer :
  • Créez une application Microsoft Entra en approvisionnant une application Microsoft Entra.
  • Accordez l’accès à votre application Microsoft Entra sur votre base de données Azure Data Explorer via la gestion des autorisations de la 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é, sinon contactez le propriétaire de votre instance Azure DevOps et demandez-lui de l’installer.

    

    

Préparer votre contenu pour la mise en production

Vous pouvez utiliser les méthodes suivantes pour exécuter des commandes d’administration sur un cluster au sein d’une tâche :

• Utilisez un modèle de recherche pour obtenir plusieurs fichiers de commande à partir d’un dossier d’agent local (sources de build ou artefacts de mise en production). L’option à ligne unique prend en charge plusieurs fichiers avec une commande par fichier.

  

• Écrire des commandes en ligne.

  

• Spécifiez un chemin d’accès de fichier pour obtenir des fichiers de commande 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 du référentiel d’exemples dans les dossiers respectifs 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 Releases> dans le menu de gauche, puis sélectionnez 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 Étape . Dans le volet Étape , ajoutez le nom de l’étape, puis 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 utilisée dans la tâche. Entrez le nom et la valeur du point de terminaison, puis sélectionnez Enregistrer pour enregistrer votre pipeline.

   

   Pour rechercher votre URL de point de terminaison, accédez à la page de présentation de votre cluster Azure Data Explorer, dans le portail Azure, et copiez l’URI du cluster. Construisez l’URI de la variable au format suivant https://<ClusterURI>?DatabaseName=<DBName>. Par exemple, https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

Créer une tâche pour déployer les dossiers

1. Sous l’onglet Pipeline , sélectionnez 1 travail, 0 tâche à ajouter.

   

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
        Méthode d’authentification	Configurez les informations d’identification d’identité fédérées (FIC) (recommandé) ou sélectionnez l’authentification par principal de service (SPA).
        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é de l'application du service principal	Entrez la clé d’application Microsoft Entra (créée en tant que prérequis)
        ID de locataire Microsoft Entra	Entrez votre client Microsoft Entra (par exemple, microsoft.com ou contoso.com)

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

      

   4. Si vos commandes d’administrateur sont des opérations asynchrones de longue durée, cochez la case Attendre que les commandes d’administrateur asynchrones longues soient terminées. Quand elle est activée, la tâche interroge l’état .show operations de l’opération jusqu’à ce que la commande se termine.

3. Sélectionnez Enregistrer, puis, sous l’onglet Tâches , vérifiez qu’il existe trois tâches : Déployer des tables, déployer des fonctions et déployer des 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 de build ou de mise en production peut être utilisée afin de valider un jeu de données et de 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, Regroupement de requêtes.
   • 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 gestion de passerelle de serveur de requêtes

Si nécessaire, créez une tâche pour exécuter une requête sur un cluster et bloquer la progression de la mise en production jusqu'à ce que le nombre de lignes des résultats de la requête soit atteint. La tâche Server Query Gate est une tâche 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.

   

Exécuter la mise en production

1. Sélectionnez + Version>Créer une version pour démarrer une version.

   

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

   

La création d’un pipeline de mise en production pour le déploiement en préproduction est à présent terminée.

Prise en charge de l’authentification sans clé pour les tâches DevOps d’Azure Data Explorer

L’extension prend en charge l’authentification sans clé pour les clusters Azure Data Explorer. L’authentification sans clé vous permet de vous authentifier auprès des clusters Azure Data Explorer sans utiliser de clé. Il est plus sécurisé et plus facile à gérer.

Utiliser les informations d’identification d’identité fédérées (FIC) dans une connexion de service Azure Data Explorer

1. Dans votre instance DevOps, accédez aux Paramètres du projet>Connexions de service> Nouvelle connexion de service> Azure Data Explorer.

2. Sélectionnez Informations d’identification d ’identité fédérées, puis entrez l’URL de votre cluster, l’ID du principal de service, l’ID de locataire, un nom de connexion de service, puis sélectionnez Enregistrer.

3. Dans le portail Azure, ouvrez l’application Microsoft Entra pour le principal de service spécifié.

4. Dans Certificats et secrets, sélectionnez informations d’identification fédérées.

   

5. Sélectionnez Ajouter des informations d’identification, puis pour le scénario d’informations d’identification fédérées, sélectionnez Autre émetteur, puis renseignez les paramètres à l’aide des informations suivantes :

   • Émetteur : <https://vstoken.dev.azure.com/{System.CollectionId}> où {System.CollectionId} est l’ID de collection de votre organisation Azure DevOps. Vous trouverez l’ID de collection de la manière suivante :

     • Dans le pipeline de mise en production Classique Azure DevOps, sélectionnez Initialiser la tâche. L’ID de collection s’affiche dans les journaux d’activité.

   • Identificateur du sujet : <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> où {DevOps_Org_name} est le nom de l’organisation Azure DevOps, {Project_Name} est le nom du projet et {Service_Connection_Name} le nom de connexion de service que vous avez créé précédemment.

     Remarque

     S’il y a de l’espace dans votre nom de connexion de service, vous pouvez l’utiliser avec l’espace dans le champ. Par exemple : sc://MyOrg/MyProject/My Service Connection.

   • Nom: entrez un nom pour les informations d’identification.

   

6. Sélectionnez Ajouter.

Utiliser des informations d’identification d’identité fédérées ou une identité managée dans une connexion de service Azure Resource Manager (ARM)

1. Dans votre instance DevOps, accédez aux Paramètres du projet>connexions de service> Nouveau service de connexion>Azure Resource Manager.

   

2. Sous Méthode d’authentification, sélectionnez Workload Identity Federation (automatique) pour continuer. Vous pouvez également utiliser l’option Fédération d’identité de charge de travail manuelle pour spécifier les détails de la fédération des identités de charge de travail ou l’option Identité gérée. En savoir plus sur la configuration d’une identité managée à l’aide d’Azure Resource Management dans azure Resource Manager (ARM) Service Connections.

   

3. Renseignez les détails requis, sélectionnez Vérifier, puis sélectionnez Enregistrer.

Configuration du pipeline YAML

Vous pouvez configurer des tâches à l’aide de l’interface utilisateur web Azure DevOps ou du code YAML dans le schéma de pipeline.

L’extension fournit trois tâches de pipeline, toutes accessibles via YAML :

• Commande Azure Data Explorer (ADXAdminCommand@5) : exécuter des commandes d’administration/de contrôle sur un cluster ADX
• Requête Azure Data Explorer : exécuter des requêtes sur un cluster ADX et analyser les résultats
• Porte du serveur de requête Azure Data Explorer : tâche sans agent permettant de gérer les versions en fonction du résultat de la requête

exemple de commande administrateur — commandes intégrées

L’exemple suivant exécute une commande d’administrateur inline à l’aide d’une connexion de service Azure Resource Manager (ARM), qui prend en charge l’authentification WIF (Workload Identity Federation) et Managed Identity :

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Run inline ADX admin command'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'inline'
    inlineCommands: |
      .create-merge table MyTable (Id:int, Name:string, Timestamp:datetime)
      .create-or-alter function MyFunction() { MyTable | take 10 }
    azureSubscription: '<ARM Service Connection Name>'
  continueOnError: true

Exemple de commande d’administrateur : commandes basées sur des fichiers

L’exemple suivant exécute des commandes d’administration à partir de fichiers correspondant à un modèle glob, à l’aide de l’authentification AAD App Registration :

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Deploy schema from files'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'files'
    commandFilesPattern: '**/*.csl'
    aadAppId: '$(AAD_APP_ID)'
    aadAppKey: '$(AAD_APP_KEY)'
    aadTenantId: '$(AAD_TENANT_ID)'
  continueOnError: true

Vous pouvez également utiliser **/*.kql comme modèle glob en fonction de votre convention d’affectation de noms de fichier.

Exemple de commande Administrateur – Connexion de service Azure Resource Manager

L’exemple suivant utilise une connexion de service Azure Resource Manager, qui prend en charge la fédération des identités de charge de travail (WIF) et l’identité managée pour l’authentification sans clé :

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Deploy schema via ARM service connection'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'files'
    commandFilesPattern: '**/*.csl'
    azureSubscription: '<ARM Service Connection Name>'
  continueOnError: true
  condition: ne(variables['ProductVersion'], '')

Paramètres d’entrée de tâche

Le tableau suivant décrit les paramètres d’entrée clés de la ADXAdminCommand@5 tâche :

Méthodes d’authentification

L’extension prend en charge les méthodes d’authentification suivantes :

• Inscription d’application Azure Active Directory (AAD) : utilisez aadAppId, aadAppKeyet aadTenantId pour vous authentifier auprès d’un principal de service. Stockez les informations d’identification en tant que variables de pipeline sécurisées.
• Authentification basée sur un certificat : utilisez un certificat au lieu d’une clé d’application pour l’authentification du principal de service. Stockez les détails du certificat en tant que variables de pipeline sécurisées.
• Identité managée : utilisez une connexion de service Azure Resource Manager configurée avec Managed Identity. Définissez l’entrée azureSubscription sur le nom de la connexion de service.
• Fédération des identités de charge de travail (WIF) : utilisez une connexion de service Azure Resource Manager avec la fédération des identités de charge de travail (automatique ou manuelle). Il s’agit de l’approche sans clé recommandée. Réglez l'entrée azureSubscription sur le nom de la connexion de service.

Exemple de requête

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@5
  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