Attività di Azure DevOps per Azure Esplora dati

Articolo
07/17/2024

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 Esplora dati - Strumenti pipeline è l'attività Azure Pipelines che consente di creare pipeline di versione e distribuire le modifiche del database ai database di Azure Esplora dati. È disponibile gratuitamente in Visual Studio Marketplace. Questa estensione include le attività di base seguenti:

Comando di Azure Esplora dati - Eseguire comandi di amministrazione in un cluster di Azure Esplora dati
Query Esplora dati di Azure - Eseguire query su un cluster di Azure Esplora dati e analizzare i risultati
Controllo del server di query di Azure Esplora dati - Attività senza agente per controllare le versioni a seconda del risultato della query

Questo documento descrive un semplice esempio sull'uso dell'attività Azure Esplora dati - Strumenti pipeline per distribuire le modifiche dello schema nel 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à:

Screenshot che mostra le opzioni del controllo del codice sorgente del comando.

Usare un modello di ricerca per ottenere più file di comando da una cartella dell'agente locale (origini di compilazione o artefatti versione)
Scrivere comandi inline
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 creare l'idempotente del codice. Ad esempio, usare .create-merge table invece di .create tablee usare .create-or-alter la funzione anziché la .create funzione .

Creazione di una pipeline di rilascio

Accedere all'Organizzazione di Azure DevOps.
Selezionare Versioni pipeline> dal menu a sinistra e selezionare Nuova pipeline.
Verrà visualizzata la finestra Nuova pipeline di versione. Nella scheda Pipeline selezionare Processo vuoto nel riquadro Selezionare un modello.
Selezionare il pulsante Fase . Nel riquadro Fase aggiungere il nome della fase. Selezionare Salva per salvare la pipeline.
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.
Nella scheda Variabili selezionare + Aggiungi per creare una variabile per l'URL dell'endpoint usato nell'attività. Scrivere il nome e il valore dell'endpoint. 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

Creare un'attività per distribuire le cartelle

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

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

Screenshot che mostra come aggiungere un comando di amministrazione di Azure Esplora dati.

Nella scheda Attività selezionare + per processo di Agent e cercare Azure Esplora dati.
In Esegui comando di Azure Esplora dati selezionare Aggiungi.

Selezionare Comando Kusto e aggiornare l'attività con le informazioni seguenti:

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à.
URL endpoint: specificare la EndPoint URL variabile creata nel passaggio precedente.
Usare l'endpoint di servizio: selezionare questa opzione.

Endpoint servizio: selezionare un endpoint di servizio esistente o crearne uno nuovo (+ Nuovo) specificando le informazioni seguenti nella finestra Aggiungi connessione al servizio azure Esplora dati:

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 entità 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)
Microsoft Entra tenant ID	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.

Screenshot che mostra come aggiungere una connessione al servizio.

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

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.

Nella scheda Attività selezionare + per processo di Agent e cercare Azure Esplora dati.
In Esegui query di Azure Esplora dati selezionare Aggiungi.
Selezionare Kusto Query e aggiornare l'attività con le informazioni seguenti:
- Nome visualizzato: nome dell'attività. Ad esempio, eseguire query sul cluster.
- Tipo: selezionare Inline.
- Query: immettere la query da eseguire.
- URL endpoint: specificare la EndPoint URL variabile creata in precedenza.
- Usare l'endpoint di servizio: selezionare questa opzione.
- Endpoint servizio: selezionare un endpoint di servizio.
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, selezionare Conteggio righe e specificare i criteri necessari.
- Se la query restituisce un valore, selezionare Valore singolo e fornire il risultato previsto.

Creare un'attività Query Server Gate

Se necessario, creare un'attività per eseguire una query su un cluster e controllare lo stato di avanzamento della versione in sospeso Conteggio righe risultati query. L'attività Server Query Gate è un processo senza agente, ovvero la query viene eseguita direttamente nel server Azure DevOps.

Nella scheda Attività selezionare + per Processo senza agente e cercare Azure Esplora dati.
In Esegui Azure Esplora dati Query Server Gate selezionare Aggiungi.
Selezionare Kusto Query Server Gate (Controllo server di query Kusto) e quindi Server Gate Test (Test controllo server).
Configurare l'attività fornendo le informazioni seguenti:
- Nome visualizzato: nome del cancello.
- Endpoint 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.

Nota

Quando si esegue la versione, verranno visualizzati risultati simili ai seguenti.

Screenshot che mostra un esempio di risultati dell'attività Query Gate.

Eseguire la versione

Selezionare + Rilascio>Crea versione per creare una versione.
Nella scheda Log verificare che lo stato della distribuzione sia riuscito.

La creazione di una pipeline di versione per la preproduzione della distribuzione è stata completata.

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

L'estensione supporta l'autenticazione senza chiave per i cluster di azure Esplora dati. L'autenticazione senza chiave consente di eseguire l'autenticazione nei cluster Esplora dati di Azure senza usare una chiave ed è più sicura e più semplice da gestire rispetto all'uso di una chiave.

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

Nell'istanza di DevOps passare a Project Settings>Service connections New service connection Azure Esplora dati (Connessioni al servizio Nuove connessioni>>al servizio) di Azure Esplora dati.
Selezionare Credenziali identità federata e immettere l'URL del cluster, l'ID entità servizio, l'ID tenant, il nome di una connessione al servizio e quindi selezionare Salva.
Nella portale di Azure aprire l'app Microsoft Entra per l'entità servizio specificata.
In Certificati e segreti selezionare Credenziali federate.
Selezionare Add credential (Aggiungi credenziali) e quindi per Federated credential scenario (Scenario credenziali federate), selezionare Other issuer (Altro autorità di certificazione) e compilare le impostazioni usando le informazioni seguenti:
- Autorità di certificazione: <https://vstoken.dev.azure.com/{System.CollectionId}> dove {System.CollectionId} è l'ID 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 raccolta viene visualizzato nei log.
- 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 è presente spazio, è possibile usarlo con spazio nel campo . Ad esempio: sc://MyOrg/MyProject/My Service Connection.
- Nome: immettere un nome per le credenziali.
Selezionare Aggiungi.

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

Nell'istanza di DevOps passare a Connessioni del servizio>Impostazioni>progetto Nuova connessione>al servizio Azure Resource Manager.
In Metodo di autenticazione selezionare Workload Identity Federation (automatic). In alternativa, è possibile usare l'opzione manuale Workload Identity Federation (manuale) per specificare i dettagli della federazione dell'identità del carico di lavoro o usare l'opzione Identità gestita. Per altre informazioni sulla configurazione di un'identità gestita con Gestione risorse di Azure, vedere Connessioni al servizio Azure Resource Manager (ARM).
Compilare i dettagli necessari, selezionare Verifica e quindi selezionare Salva.

Configurazione della pipeline Yaml

Le attività possono essere configurate sia tramite l'interfaccia utente Web di Azure DevOps che tramite il codice Yaml all'interno dello schema della pipeline.

Utilizzo dell'esempio di comando amministratore

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

Utilizzo dell'esempio di query

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=<DataBaneName>'
    authType: 'kustoserviceconn'
    connectedServiceName: '<connection service name>'
    minThreshold: '0'
    maxThreshold: '10'
  continueOnError: true

Condividi tramite