Azure DevOps-Aufgabe für Azure Data Explorer

Artikel
07/19/2024

Azure DevOps Services bietet Tools für die Entwicklungszusammenarbeit wie leistungsstarke Pipelines, kostenlose private Git-Repositorys, konfigurierbare Kanban-Boards und umfangreiche automatisierte und kontinuierliche Testfunktionen. Azure Pipelines ist eine Azure DevOps-Funktion, die es Ihnen ermöglicht, CI/CD zu verwalten, um Ihren Code mit leistungsstarken Pipelines bereitzustellen, die mit jeder Sprache, Plattform und Cloud funktionieren. Azure Data Explorer – Pipeline Tools ist die Azure Pipelines-Aufgabe, mit der Sie Releasepipelines erstellen und Ihre Datenbankänderungen in Ihren Azure Data Explorer-Datenbanken bereitstellen können. Diese finden Sie kostenlos im Visual Studio Marketplace. Diese Erweiterung enthält die folgenden grundlegenden Aufgaben:

Azure Data Explorer-Befehl: Ausführen von Administratorbefehlen für einen Azure Data Explorer-Cluster
Azure Data Explorer-Abfrage: Ausführen von Abfragen für einen Azure Data Explorer-Cluster und Analysieren der Ergebnisse
Azure Data Explorer-Abfrageservergate: Aufgabe ohne Agent zur Einrichtung eines Gates für Releases je nach Abfrageergebnis

In diesem Dokument wird ein einfaches Beispiel für die Verwendung der Aufgabe Azure Data Explorer – Pipeline Tools zum Bereitstellen Ihrer Schemaänderungen in Ihrer Datenbank beschrieben. Vollständige CI/CD-Pipelines finden Sie unter Azure DevOps-Dokumentation.

Voraussetzungen

Ein Azure-Abonnement. Erstellen Sie ein kostenloses Azure-Konto.
Schnellstart: Erstellen eines Azure Data Explorer-Clusters und einer Datenbank. Erstellen eines Clusters und einer Datenbank
Setup eines Azure Data Explorer-Clusters:
- Erstellen Sie eine Microsoft Entra-App durch Bereitstellen einer Microsoft Entra-Anwendung.
- Gewährleisten Sie den Zugriff auf Ihre Microsoft Entra-App in Ihrer Azure Data Explorer-Datenbank, indem Sie die Berechtigungen der Azure Data Explorer-Datenbank verwalten.
Azure DevOps-Setup:
Erweiterungsinstallation:
- Wenn Sie Besitzer von Azure DevOps-Instanzen sind, installieren Sie die Erweiterung aus dem Marketplace, andernfalls wenden Sie sich an den Besitzer Ihrer Azure DevOps-Instanz und bitten ihn, sie zu installieren.

Vorbereiten Ihrer Inhalte für das Release

Sie können die folgenden Methoden verwenden, um Admin-Befehle für einen Cluster innerhalb einer Aufgabe auszuführen:

Screenshot mit den Optionen für die Versionskontrolle des Befehls.

Verwenden eines Suchmusters zum Abrufen von mehreren Befehlsdateien aus einem lokalen Agent-Ordner (Buildquellen oder Releaseartefakte)
Inline-Schreiben von Befehlen
Angeben eines Dateipfads, um Befehlsdateien direkt aus der Git-Quellcodeverwaltung abzurufen (empfohlen)

Erstellen Sie die folgenden Beispielordner (Funktionen, Richtlinien, Tabellen) in Ihrem Git-Repository. Kopieren Sie die Dateien aus dem Beispiel-Repository in die entsprechenden Ordner, und übernehmen Sie die Änderungen. Die Beispieldateien werden zur Verfügung gestellt, um den folgenden Workflow auszuführen.

Tipp

Bei der Erstellung eines eigenen Workflows empfehlen wir, den Code idempotent zu gestalten. Verwenden Sie beispielsweise .create-merge table anstelle von .create table und die Funktion .create-or-alter anstelle der Funktion .create.

Releasepipeline erstellen

Melden Sie sich bei Ihrer Azure DevOps-Organisation an.
Wählen Sie Pipelines>Releases aus, und wählen im linken Menü Neue Pipeline.
Das Fenster Neue Releasepipeline wird geöffnet. Wählen Sie auf der Registerkarte Pipelines im Bereich Eine Vorlage auswählen die Option Leerer Auftrag aus.
Klicken Sie auf die Schaltfläche Stufe. Fügen Sie im Bereich Stufe den Namen der Stufe hinzu. Klicken Sie auf Speichern, um Ihre Pipeline zu speichern.
Klicken Sie auf die Schaltfläche Artefakt hinzufügen. Wählen Sie im Bereich Artefakt hinzufügen das Repository aus, in dem sich Ihr Code befindet, geben Sie die relevanten Informationen ein, und wählen Sie dann Hinzufügen aus. Klicken Sie auf Speichern, um Ihre Pipeline zu speichern.
Wählen Sie auf der Registerkarte Variablen + Hinzufügen, um eine Variable für Endpunkt-URL zu erstellen, die in der Aufgabe verwendet wird. Geben Sie den Namen und den Wert des Endpunkts ein. Klicken Sie auf Speichern, um Ihre Pipeline zu speichern.

Um Ihre Endpunkt-URL zu finden, gehen Sie zur Übersichtsseite Ihres Azure Data Explorer-Clusters im Azure-Portal und kopieren Sie den Cluster-URI. Erstellen Sie die Variable URI im folgenden Format https://<ClusterURI>?DatabaseName=<DBName>. Beispiel: https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

Erstellen einer Aufgabe zum Bereitstellen der Ordner

Klicken Sie auf der Registerkarte Pipeline auf 1 Auftrag, 0 Aufgabe, um Aufgaben hinzuzufügen.

Wiederholen Sie die folgenden Schritte, um Befehlsaufgaben zum Bereitstellen von Dateien aus den Ordnern für Tabellen, Funktionen und Richtlinien zu erstellen:

Screenshot, der zeigt, wie Sie einen Azure Data Explorer-Administratorbefehl hinzufügen.

Wählen Sie auf der Registerkarte Aufgaben das Pluszeichen (+) für Agentauftrag aus, und suchen Sie nach Azure Data Explorer.
Wählen Sie unter Azure Data Explorer-Befehl ausführen die Option Hinzufügen aus.

Wählen Sie Kusto-Befehl aus, und aktualisieren Sie die Aufgabe mit den folgenden Informationen:

Anzeigename: Der Name der Aufgabe. Ein Beispiel hierfür ist Deploy <FOLDER>, wobei <FOLDER> der Name des Ordners für die von Ihnen erstellte Bereitstellungsaufgabe ist.
Dateipfad: Geben Sie für jeden Ordner den Pfad in der Form */<FOLDER>/*.csl an, wobei <FOLDER> der relevante Ordner für die Aufgabe ist.
Endpunkt-URL: Geben Sie die im vorherigen Schritt erstellte Variable EndPoint URL an.
Dienstendpunkt verwenden: Wählen Sie diese Option aus.

Dienstendpunkt: Wählen Sie einen vorhandenen Dienstendpunkt aus, oder erstellen Sie einen neuen (+ Neu), indem Sie im Fenster Azure Data Explorer-Dienstverbindung hinzufügen die folgenden Informationen angeben:

Einstellung	Vorgeschlagener Wert
Authentifizierungsmethode	Einrichten von Verbundidentitätsanmeldeinformationen (FIC) (empfohlen) oder Auswählen der Dienstprinzipalauthentifizierung (SPA).
Verbindungsname	Geben Sie den Namen zum Identifizieren dieses Dienstendpunkts ein.
Cluster-URL	Den Wert finden Sie im Übersichtsbereich Ihres Azure Data Explorer-Clusters im Azure-Portal.
Dienstprinzipal-ID	Geben Sie die Microsoft Entra App-ID ein (als Voraussetzung erstellt)
Dienstprinzipal-App-Schlüssel	Geben Sie den Microsoft Entra App Key ein (als Voraussetzung erstellt).
Microsoft Entra-Mandanten-ID	Geben Sie Ihren Microsoft Entra-Mandanten ein (z. B. microsoft.com oder contoso.com).

Aktivieren Sie das Kontrollkästchen Nutzung dieser Verbindung für alle Pipelines erlauben, und wählen Sie anschließend OK aus.

Screenshot: Hinzufügen der Dienstverbindung

Wählen Sie Speichern aus, und überprüfen Sie auf der Registerkarte Aufgaben, ob drei Aufgaben vorhanden sind: Deploy Tables (Tabellen bereitstellen), Deploy Functions (Funktionen bereitstellen) und Deploy Policies (Richtlinien bereitstellen).

Erstellen einer Abfrageaufgabe

Erstellen Sie bei Bedarf eine Aufgabe, um für den Cluster eine Abfrage auszuführen. Das Ausführen von Abfragen in einer Build- oder Releasepipeline kann verwendet werden, um ein Dataset zu überprüfen und einen Schritt basierend auf den Abfrageergebnissen als erfolgreich oder nicht erfolgreich einzustufen. Die Erfolgskriterien für Aufgaben können auf einem Schwellenwert für die Zeilenanzahl oder einem einzelnen Wert basieren. Dies hängt davon ab, was von der Abfrage zurückgegeben wird.

Wählen Sie auf der Registerkarte Aufgaben das Pluszeichen (+) für Agentauftrag aus, und suchen Sie nach Azure Data Explorer.
Wählen Sie unter Azure Data Explorer-Abfrage ausführen die Option Hinzufügen aus.
Wählen Sie Kusto-Abfrage aus, und aktualisieren Sie die Aufgabe mit den folgenden Informationen:
- Anzeigename: Der Name der Aufgabe. Beispiel: Abfragecluster.
- Typ: Wählen Sie Inline aus.
- Abfrage: Geben Sie die Abfrage ein, die Sie ausführen möchten.
- Endpunkt-URL:Geben Sie die zuvor erstellte Variable EndPoint URL an.
- Dienstendpunkt verwenden: Wählen Sie diese Option aus.
- Dienstendpunkt: Wählen Sie einen Dienstendpunkt aus.
Wählen Sie unter „Aufgabenergebnisse“ die Erfolgskriterien der Aufgabe je nach den Ergebnissen Ihrer Abfrage wie folgt aus:
- Wenn von Ihrer Abfrage Zeilen zurückgegeben werden, wählen Sie die Option Zeilenanzahl aus und geben die erforderlichen Kriterien an.
- Wenn von Ihrer Abfrage ein Wert zurückgegeben wird, wählen Sie Einzelwert aus und geben das erwartete Ergebnis an.

Erstellen einer Aufgabe für ein Abfrageservergate

Erstellen Sie bei Bedarf eine Aufgabe zum Ausführen einer Abfrage für einen Cluster, und richten Sie ein Gate für den Releaseprozess in Abhängigkeit der Zeilenanzahl in den Abfrageergebnissen ein. Die Aufgabe für ein Abfrageservergate ist ein Auftrag ohne Agent. Dies bedeutet, dass die Abfrage direkt in Azure DevOps Server ausgeführt wird.

Wählen Sie auf der Registerkarte Aufgaben das Pluszeichen (+) für Auftrag ohne Agent aus, und suchen Sie nach Azure Data Explorer.
Wählen Sie unter Run Azure Data Explorer Query Server Gate (Azure Data Explorer-Abfrageservergate ausführen) die Option Hinzufügen aus.
Wählen Sie die Option Kusto Query Server Gate (Kusto-Abfrageservergate) und dann Server Gate Test (Servergatetest) aus.
Konfigurieren Sie die Aufgabe, indem Sie die folgenden Informationen angeben:
- Anzeigename: Der Name des Gates.
- Dienstendpunkt: Wählen Sie einen Dienstendpunkt aus.
- Datenbankname: Geben Sie den Namen der Datenbank an.
- Typ: Wählen Sie Inline query (Inline-Abfrage) aus.
- Abfrage: Geben Sie die Abfrage ein, die Sie ausführen möchten.
- Maximum threshold (Maximaler Schwellenwert): Geben Sie die maximale Zeilenanzahl für die Erfolgskriterien der Abfrage an.

Hinweis

Beim Ausführen des Release sollten Ergebnisse der folgenden Art angezeigt werden.

Screenshot eines Beispiels für Query Gate-Aufgabenergebnisse.

Ausführen des Release

Wählen Sie + Release>Release erstellen, um ein Release zu erstellen.
Überprüfen Sie auf der Registerkarte Protokolle, ob die Bereitstellung erfolgreich war.

Jetzt ist die Erstellung einer Releasepipeline für die Bereitstellung für die Vorproduktion abgeschlossen.

Unterstützung für schlüssellose Authentifizierung für DevOps-Aufgaben im Azure Data Explorer

Die Erweiterung unterstützt die schlüssellose Authentifizierung für Azure Data Explorer-Cluster. Die schlüssellose Authentifizierung ermöglicht Ihnen die Authentifizierung bei Azure Data Explorer-Clustern ohne Schlüssel und ist sicherer und einfacher zu verwalten als die Verwendung eines Schlüssels.

Verwenden Sie die Authentifizierung mit Verbundidentitätsanmeldeinformationen (FIC) in einer Azure Data Explorer-Dienstverbindung

Wechseln Sie in Ihrer DevOps-Instanz zu Projekteinstellungen>Dienstverbindungen>Neue Dienstverbindung>Azure Data Explorer.
Wählen Sie Verbundidentitätsanmeldeinformationen aus, und geben Sie Ihre Cluster-URL, Dienstprinzipal-ID, Mandanten-ID, einen Dienstverbindungsnamen ein, und wählen Sie dann Speichern aus.
Öffnen Sie im Azure-Portal die Microsoft Entra-App für den angegebenen Dienstprinzipal.
Wählen Sie unter Zertifikate und Geheimnisse die Option Verbundanmeldeinformationen aus.
Wählen Sie Anmeldeinformationen hinzufügen und wählen Sie dann für Verbundanmeldeinformationsszenario Anderer Aussteller aus, und füllen Sie die Einstellungen mithilfe der folgenden Informationen aus:
- Aussteller: <https://vstoken.dev.azure.com/{System.CollectionId}> wobei {System.CollectionId} die Sammlungs-ID Ihrer Azure DevOps-Organisation ist. Sie finden die Sammlungs-ID auf folgende Weise:
  - Wählen Sie in der klassischen Azure DevOps-Releasepipeline Auftrag initialisieren aus. Die Sammlungs-ID wird in den Protokollen angezeigt.
- Antragstellerbezeichner: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> wobei {DevOps_Org_name} der Name der Azure DevOps-Organisation ist, {Project_Name} der Projektname ist und {Service_Connection_Name} der zuvor erstellte Dienstverbindungsname ist.
  
  Hinweis
  
  Wenn der Dienstverbindungsname leer ist, können Sie ihn mit Leerzeichen im Feld verwenden. Beispiel: sc://MyOrg/MyProject/My Service Connection
- Name: Geben Sie einen Namen für die Anmeldeinformationen ein.
Wählen Sie Hinzufügen.

Verwenden von Verbundidentitätsanmeldeinformationen oder verwalteter Identität in einer Azure Resource Manager (ARM)-Dienstverbindung

Wechseln Sie in Ihrer DevOps-Instanz zu Projekteinstellungen>Dienstverbindungen>Neue Dienstverbindung>Azure Resource Manager.
Wählen Sie unter Authentifizierungsmethode Workload-Identitätsverbund (automatisch) aus. Alternativ können Sie die manuelle Option Workload-Identitätsverbund (manuell) verwenden, um die Details des Workload-Identitätsverbund anzugeben, oder die Option Verwaltete Identität verwenden. Weitere Informationen zum Einrichten einer verwalteten Identität mithilfe von Azure Resource Management finden Sie unter Azure Resource Manager (ARM)-Dienstverbindung.
Füllen Sie die erforderlichen Details aus, wählen Sie Überprüfen und dann Speichernaus.

Konfiguration der YAML-Pipeline

Die Aufgaben können sowohl über die Azure DevOps-Weboberfläche als auch über YAML-Code innerhalb des Pipelineschemas konfiguriert werden.

Beispiel für die Verwendung eines Administratorbefehls

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

Beispiel für die Verwendung einer Abfrage

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

Freigeben über