Attività di Azure DevOps per Azure Data Explorer

Azure DevOps Services offre strumenti di collaborazione per lo sviluppo, ad esempio pipeline ad alte prestazioni, repository Git privati gratuiti, lavagne Kanban configurabili e funzionalità di test automatizzate e continue complete. Azure Pipelines è una funzionalità di Azure DevOps che consente di gestire CI/CD per distribuire il codice con pipeline ad alte prestazioni che funzionano con qualsiasi linguaggio, piattaforma e cloud. Azure Data Explorer - Strumenti pipeline è l'attività di Azure Pipelines che consente di creare pipeline di rilascio e implementare le modifiche del database ai database di Azure Data Explorer. È disponibile gratuitamente in Visual Studio Marketplace. L'estensione include le attività di base seguenti:

• Comando di Azure Data Explorer - Eseguire comandi di amministrazione su un cluster di Azure Data Explorer

• Query di Azure Data Explorer - Eseguire query su un cluster di Azure Data Explorer e interpretare i risultati.

• Controllo del server di query di Esplora dati di Azure - Attività senza agente per controllare le versioni a seconda del risultato della query

  

Questo documento descrive un semplice esempio di uso dell'attività Azure Data Explorer - Pipeline Tools per distribuire le modifiche allo schema al tuo database. Per le pipeline CI/CD complete, vedere la documentazione di Azure DevOps.

Prerequisiti

• Una sottoscrizione di Azure. Creare un account Azure gratuito.
• Un cluster e un database di Esplora dati di Azure. Creare un cluster e un database.
• Configurazione del cluster Esplora dati di Azure:
  • Creare un'app Microsoft Entra effettuando il provisioning di un'applicazione Microsoft Entra.
  • Concedere l'accesso all'app Microsoft Entra nel database di Azure Esplora dati gestendo le autorizzazioni del database di Azure Esplora dati.
• Configurazione di Azure DevOps:
  • Iscriversi a un'organizzazione gratuita.
  • Creare un'organizzazione.
  • Creare un progetto in Azure DevOps.
  • Codice con Git.
• Installazione dell'estensione:

  • Se si è il proprietario dell'istanza di Azure DevOps, installare l'estensione dal Marketplace. In caso contrario, contattare il proprietario dell'istanza di Azure DevOps e chiedere di installarla.

    

    

Preparare il contenuto per il rilascio

È possibile usare i metodi seguenti per eseguire comandi di amministrazione su un cluster all'interno di un'attività:

• Usare un pattern di ricerca per ottenere più file di comando da una cartella dell'agente locale (origini di build o artefatti di rilascio). L'opzione a riga singola supporta più file con un comando per ogni file.

  

• Scrivere i comandi in linea.

  

• Specificare un percorso di file per ottenere i file di comando direttamente dal controllo del codice sorgente Git (scelta consigliata).

  

  Creare le cartelle di esempio seguenti (Funzioni, Criteri, Tabelle) nel repository Git. Copiare i file dal repository degli esempi nelle rispettive cartelle ed eseguire il commit delle modifiche. I file di esempio vengono forniti per eseguire il flusso di lavoro seguente.

  

  Suggerimento

  Quando si crea un flusso di lavoro personalizzato, è consigliabile rendere il codice idempotente. Ad esempio, usare .create-merge table anziché .create tablee usare la .create-or-alter funzione anziché la .create funzione .

Creazione di una pipeline di rilascio

1. Accedi alla tua Organizzazione di Azure DevOps.

2. Selezionare Pipeline>Rilasci dal menu a sinistra e quindi selezionare Nuova pipeline.

   

3. Verrà visualizzata la finestra Nuova pipeline di rilascio di versioni. Nella scheda Pipeline, nel riquadro Selezionare un modello, selezionare Processo vuoto.

   

4. Selezionare il pulsante Fase . Nel riquadro Fase aggiungere il nome della fase e quindi selezionare Salva per salvare la pipeline.

   

5. Selezionare Aggiungi un elemento pulsante. Nel riquadro Aggiungi un artefatto selezionare il repository in cui è presente il codice, compilare le informazioni pertinenti e selezionare Aggiungi. Selezionare Salva per salvare la pipeline.

   

6. Nella scheda Variabili selezionare + Aggiungi per creare una variabile per l'URL dell'endpoint usato nell'attività. Immettere il nome e il valore dell'endpoint e quindi selezionare Salva per salvare la pipeline.

   

   Per trovare l'URL dell'endpoint, passare alla pagina di panoramica del cluster di Azure Esplora dati nel portale di Azure e copiare l'URI del cluster. Costruire l'URI della variabile nel formato https://<ClusterURI>?DatabaseName=<DBName>seguente. Ad esempio, https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

Crea un'attività per distribuire le cartelle

1. Nella scheda Pipeline selezionare 1 processo, 0 attività da aggiungere.

   

2. Ripetere i passaggi seguenti per creare attività di comando per distribuire file dalle cartelle Tabelle, Funzioni e Criteri :

   

   1. Nella scheda Attività, selezionare + per processo Agente e cercare Azure Data Explorer.

   2. In Esegui comando di Azure Data Explorer, selezionare Aggiungi.

   3. Selezionare Kusto Command e aggiornare l'attività con le seguenti informazioni:

      • Nome visualizzato: nome dell'attività. Ad esempio, Deploy <FOLDER> dove <FOLDER> è il nome della cartella per l'attività di distribuzione che si sta creando.

      • Percorso file: per ogni cartella specificare il percorso come */<FOLDER>/*.csl dove <FOLDER> è la cartella pertinente per l'attività.

      • Endpoint URL: specificare la variabile EndPoint URL creata nel passaggio precedente.

      • Usare l'endpoint di servizio: selezionare questa opzione.

      • Endpoint del servizio: selezionare un endpoint del servizio esistente o crearne uno nuovo (+ Nuovo), fornendo le seguenti informazioni nella finestra Aggiungi connessione al servizio Azure Data Explorer:

        Impostazione	Valore suggerito
        Metodo di autenticazione	Configurare le credenziali di identità federate (FIC) (scelta consigliata) o Selezionare l'autenticazione dell'entità servizio (SPA).
        Nome connessione	Immettere un nome per identificare questo endpoint di servizio
        Cluster Url	Il valore è disponibile nella sezione panoramica del cluster di Azure Esplora dati nel portale di Azure
        ID Principale del Servizio	Immettere l'ID app Microsoft Entra (creato come prerequisito)
        Chiave dell'app dell'entità servizio	Immettere la chiave dell'app Microsoft Entra (creata come prerequisito)
        ID tenant di Microsoft Entra	Immettere il tenant di Microsoft Entra (ad esempio microsoft.com o contoso.com)

      Selezionare Consenti a tutte le pipeline di usare questa connessione e quindi selezionare OK.

      

   4. Se i comandi amministrativi sono operazioni asincrone a esecuzione prolungata, selezionare la casella di controllo Attendere il completamento dei comandi amministrativi asincroni lunghi. Se abilitata, l'attività controlla lo stato dell'operazione usando .show operations fino al suo completamento.

3. Selezionare Salva e quindi nella scheda Attività verificare che siano presenti tre attività: Distribuisci tabelle, Distribuisci funzioni e Distribuiscicriteri.

   

Creare un'attività Query

Se necessario, creare un'attività per eseguire una query sul cluster. L'esecuzione di query in una pipeline di compilazione o versione può essere usata per convalidare un set di dati e avere un passaggio riuscito o negativo in base ai risultati della query. I criteri di esito positivo delle attività possono essere basati su una soglia di conteggio delle righe o su un singolo valore a seconda del risultato restituito dalla query.

1. Nella scheda Attività selezionare + per processo dell'agente e cercare Azure Data Explorer.

2. Sotto Esegui query di Azure Esplora dati, selezionare Aggiungi.

3. Selezionare Kusto Query e aggiornare l'attività con le informazioni seguenti:

   • Nome visualizzato: Nome dell'attività. Ad esempio, Cluster di query.
   • Tipo: selezionare Inline.
   • Query: immettere la query da eseguire.
   • Endpoint URL: specificare la variabile EndPoint URL creata in precedenza.
   • Usare l'Endpoint di Servizio: selezionare questa opzione.
   • Endpoint di Servizio: Selezionare un endpoint di servizio.

   

4. In Risultati attività selezionare i criteri di esito positivo dell'attività in base ai risultati della query, come indicato di seguito:

   • Se la query restituisce righe, seleziona Conteggio righe e specifica i criteri richiesti.

     

   • Se la query restituisce un valore, selezionare Valore singolo e fornire il risultato previsto.

     

Creare un'attività di Query Server Gate

Se necessario, creare un'attività per eseguire una query su un cluster e bloccare lo stato di avanzamento del rilascio in attesa del conteggio delle righe dei risultati della query. L'attività Server Query Gate è un processo senza agente, ovvero la query viene eseguita direttamente nel server Azure DevOps.

1. Nella scheda Attività selezionare + per Processo senza agente e cercare Azure Esplora dati.

2. In Esegui Azure Data Explorer Query Server Gate, selezionare Aggiungi.

3. Selezionare Kusto Query Server Gate e quindi selezionare Server Gate Test.

   

4. Configurare l'attività fornendo le informazioni seguenti:

   • Nome visualizzato: Nome del cancello.
   • Endpoint di servizio: Selezionare un endpoint di servizio.
   • Nome database: specificare il nome del database.
   • Tipo: selezionare query inline.
   • Query: immettere la query da eseguire.
   • Soglia massima: specificare il numero massimo di righe per i criteri di esito positivo della query.

   

Eseguire il rilascio

1. Selezionare + Rilascio> per avviare una versione.

   

2. Nella scheda Log, controlla che lo stato della distribuzione sia riuscito.

   

La creazione di una pipeline di rilascio per la distribuzione nell'ambiente di pre-produzione è stata completata.

Supporto dell'autenticazione senza chiave per le attività di Azure Esplora dati DevOps

L'estensione supporta l'autenticazione senza chiavi per i cluster di Azure Data Explorer. L'autenticazione senza chiave consente di eseguire l'autenticazione nei cluster di Esplora dati di Azure senza usare una chiave. È più sicuro e più facile da gestire.

Usare l'autenticazione FIC (Federated Identity Credentials) in una connessione al servizio Esplora dati di Azure

1. Nell'istanza di DevOps, vai a Impostazioni del progetto>Connessioni del servizio>Nuova connessione del servizio>Esplora dati di Azure.

2. Selezionare Credenziali di identità federata e inserire l'URL del cluster, l'ID entità servizio, l'ID tenant, il nome di una connessione al servizio e quindi selezionare Salva.

3. Nella portale di Azure aprire l'app Microsoft Entra per l'entità servizio specificata.

4. In Certificati e segreti, selezionare Credenziali federate.

   

5. Selezionare Aggiungi credenziale e quindi per lo Scenario credenziali federate, selezionare Altro certificatore, e compilare le impostazioni usando le informazioni seguenti:

   • Emittente: <https://vstoken.dev.azure.com/{System.CollectionId}> dove {System.CollectionId} è l'ID della raccolta dell'organizzazione Azure DevOps. È possibile trovare l'ID raccolta nei modi seguenti:

     • Nella pipeline di versione classica di Azure DevOps selezionare Inizializza processo. L'ID della raccolta viene visualizzato nei registri.

   • Identificatore del soggetto: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> dove {DevOps_Org_name} è il nome dell'organizzazione di Azure DevOps, {Project_Name} è il nome del progetto e {Service_Connection_Name} è il nome della connessione al servizio creato in precedenza.

     Nota

     Se nel nome della connessione del servizio c'è uno spazio, è possibile usarlo inserendolo nel campo. Ad esempio: sc://MyOrg/MyProject/My Service Connection.

   • Nome: immettere un nome per le credenziali.

   

6. Selezionare Aggiungi.

Usare le credenziali dell'identità federata o l'identità gestita in una connessione al servizio Azure Resource Manager (ARM)

1. Nell'istanza di DevOps, vai a Impostazioni dei Progetti, >Connessioni del servizio, >Nuova connessione del servizio, >Azure Resource Manager.

   

2. In Metodo di autenticazione selezionare Workload Identity Federation (automatico) per continuare. È anche possibile usare l'opzione Workload Identity Federation (opzione manuale) per specificare i dettagli dell'Identity Federation del carico di lavoro o l'opzione Identità gestita. Altre informazioni su come configurare un'identità gestita utilizzando la Gestione risorse di Azure in Connessioni di servizio di Azure Resource Manager (ARM).

   

3. Compilare i dettagli necessari, selezionare Verifica e quindi selezionare Salva.

Configurazione della pipeline YAML

È possibile configurare le attività usando l'interfaccia utente Web di Azure DevOps o il codice YAML all'interno dello schema della pipeline.

L'estensione fornisce tre attività della pipeline, tutte accessibili tramite YAML:

• Comando di Esplora dati di Azure (ADXAdminCommand@5): eseguire comandi di amministrazione/controllo su un cluster ADX
• Query di Azure Data Explorer — Esegui query sul cluster ADX ed elabora i risultati
• Cancello del server di query di Esplora dati di Azure - Attività senza agente per vincolare i rilasci a seconda del risultato della query

Esempio di comando dell'admin — comandi in linea

L'esempio seguente esegue un comando di amministrazione inline usando una connessione al servizio Azure Resource Manager (ARM), che supporta l'autenticazione wif (Workload Identity Federation) e identità gestita:

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

Esempio di comando admin : comandi basati su file

L'esempio seguente esegue i comandi di amministrazione dai file corrispondenti a un modello GLOB, usando l'autenticazione di registrazione dell'app AAD:

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

È anche possibile usare **/*.kql come modello glob a seconda della convenzione di denominazione dei file.

Esempio di comando amministratore - Connessione al servizio Azure Resource Manager

L'esempio seguente usa una connessione al servizio Azure Resource Manager, che supporta Workload Identity Federation (WIF) e Managed Identity per l'autenticazione senza chiave.

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'], '')

Parametri di input dell'attività

La tabella seguente descrive i parametri chiave di input per l'attività ADXAdminCommand@5 :

Metodi di autenticazione

L'estensione supporta i metodi di autenticazione seguenti:

• Registrazione app di Azure Active Directory (AAD): usare aadAppId, aadAppKey e aadTenantId per eseguire l'autenticazione con un'entità del servizio. Archiviare le credenziali come variabili di pipeline sicure.
• Autenticazione basata su certificato — utilizzare un certificato anziché una chiave dell'app per l'autenticazione del principale del servizio. Archiviare i dettagli del certificato come variabili della pipeline sicura.
• Identità gestita : usare una connessione al servizio Azure Resource Manager configurata con l'identità gestita. Impostare l'input azureSubscription sul nome della connessione del servizio.
• Workload Identity Federation (WIF) — utilizzare una connessione del servizio di Azure Resource Manager con Federazione delle identità del carico di lavoro (automatica o manuale). Questo è l'approccio senza chiave consigliato. Impostare l'input azureSubscription sul nome del servizio di connessione.

Esempio di query

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