Zadanie usługi Azure DevOps dla usługi Azure Data Explorer

Usługa Azure DevOps Services udostępnia narzędzia do współpracy programistycznej, takie jak potoki o wysokiej wydajności, bezpłatne prywatne repozytoria Git, konfigurowalne tablice Kanban oraz rozbudowane funkcje zautomatyzowanego i ciągłego testowania. Azure Pipelines to funkcja usługi Azure DevOps, która umożliwia zarządzanie ciągłą integracją/ciągłym wdrażaniem kodu przy użyciu potoków o wysokiej wydajności, które współpracują z dowolnym językiem, platformą i chmurą. Azure Data Explorer - Pipeline Tools to zadanie usługi Azure Pipelines, które umożliwia tworzenie potoków wdrożenia i wdrażanie zmian w bazach danych Azure Data Explorer. Jest ona dostępna bezpłatnie w witrynie Visual Studio Marketplace. Rozszerzenie obejmuje następujące podstawowe zadania:

• Polecenie usługi Azure Data Explorer — uruchamianie poleceń administracyjnych w klastrze usługi Azure Data Explorer

• Zapytanie usługi Azure Data Explorer — uruchamianie zapytań względem klastra usługi Azure Data Explorer i analizowanie wyników

• Bramka serwera zapytań Azure Data Explorer — zadanie bez potrzeby uruchomienia agenta w celu kontroli wydania w zależności od wyniku zapytania

  

W tym dokumencie opisano prosty przykład użycia zadania Azure Data Explorer — Narzędzia potoku w celu wdrożenia zmian schematu w bazie danych. Aby uzyskać pełne potoki CI/CD, zapoznaj się z dokumentacją usługi Azure DevOps.

Wymagania wstępne

• Subskrypcja platformy Azure. Utwórz bezpłatne konto platformy Azure.
• Baza danych i klaster usługi Azure Data Explorer. Utwórz klaster i bazę danych.
• Konfiguracja klastra usługi Azure Data Explorer:
  • Utwórz aplikację Microsoft Entra, dostarczając aplikację Microsoft Entra.
  • Udziel dostępu do aplikacji Microsoft Entra w bazie danych usługi Azure Data Explorer, zarządzając uprawnieniami bazy danych usługi Azure Data Explorer.
• Konfiguracja usługi Azure DevOps:
  • Zarejestruj się, aby utworzyć bezpłatną organizację.
  • Utwórz organizację.
  • Tworzenie projektu w usłudze Azure DevOps.
  • Kod przy użyciu usługi Git.
• Instalacja rozszerzenia:

  • Jeśli jesteś właścicielem wystąpienia usługi Azure DevOps, zainstaluj rozszerzenie z Marketplace, jeśli nie, skontaktuj się z właścicielem Twojego wystąpienia usługi Azure DevOps i poproś go o jego zainstalowanie.

    

    

Przygotowywanie zawartości do wydania

Następujące metody umożliwiają wykonywanie poleceń administracyjnych względem klastra w ramach zadania:

• Użyj wzorca wyszukiwania, aby pobrać wiele plików poleceń z folderu agenta lokalnego (źródła kompilacji lub artefakty wydania). Opcja jednowierszowa obsługuje wiele plików z jednym poleceniem na plik.

  

• Pisanie poleceń w linii.

  

• Określ ścieżkę pliku, aby pobrać pliki poleceń bezpośrednio z kontroli źródła usługi Git (zalecane).

  

  Utwórz następujące przykładowe foldery (funkcje, zasady, tabele) w repozytorium Git. Skopiuj pliki z repozytorium przykładów do odpowiednich folderów i zatwierdź zmiany. Przykładowe pliki są udostępniane w celu wykonania następującego przepływu pracy.

  

  Wskazówka

  Podczas tworzenia własnego przepływu pracy zalecamy utworzenie idempotentnego kodu. Na przykład użyj .create-merge table zamiast .create table, a funkcji .create-or-alter zamiast funkcji .create.

Tworzenie potoku wydań

1. Zaloguj się do organizacji usługi Azure DevOps.

2. Wybierz pozycję Potoki>Wydania z menu po lewej stronie, a następnie wybierz pozycję Nowy potok.

   

3. Okno Nowy potok wydania zostanie otwarte. Na karcie Pipelines w okienku Wybierz szablon wybierz opcję Puste zadanie.

   

4. Wybierz przycisk Stage (Etap ). W okienku Etap dodaj nazwę etapu, a następnie naciśnij Zapisz, aby zapisać pipeline.

   

5. Wybierz przycisk Dodaj artefakt . W okienku Dodawanie artefaktu wybierz repozytorium, w którym istnieje twój kod, wypełnij odpowiednie informacje i wybierz pozycję Dodaj. Wybierz Zapisz, aby zapisać potok.

   

6. Na karcie Zmienne wybierz pozycję + Dodaj , aby utworzyć zmienną dla adresu URL punktu końcowego używanego w zadaniu. Wprowadź nazwę i wartość punktu końcowego, a następnie wybierz Zapisz, aby zapisać pipeline.

   

   Aby znaleźć adres URL punktu końcowego, przejdź do strony przeglądu klastra usługi Azure Data Explorer w witrynie Azure Portal i skopiuj identyfikator URI klastra. Skonstruuj identyfikator URI zmiennej w następującym formacie https://<ClusterURI>?DatabaseName=<DBName>. Na przykład https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

Utwórz zadanie wdrożenia folderów

1. Na karcie Pipeline wybierz 1 zadanie, 0 zadań, aby dodać zadania.

   

2. Powtórz następujące kroki, aby utworzyć zadania poleceń w celu wdrożenia plików z folderów Tabele, Funkcje i Zasady :

   

   1. Na karcie Zadania wybierz pozycję + według pracy agenta i wyszukaj pozycję Azure Data Explorer.

   2. W obszarze Uruchom polecenie usługi Azure Data Explorer wybierz pozycję Dodaj.

   3. Wybierz polecenie Kusto i zaktualizuj zadanie przy użyciu następujących informacji:

      • Wyświetlana nazwa: Nazwa zadania. Na przykład Deploy <FOLDER> gdzie <FOLDER> to nazwa folderu dla tworzonego zadania wdrażania.

      • Ścieżka pliku: dla każdego folderu określ ścieżkę, w */<FOLDER>/*.csl której <FOLDER> znajduje się odpowiedni folder zadania.

      • Adres URL punktu końcowego: określ zmienną utworzoną EndPoint URL w poprzednim kroku.

      • Użyj punktu końcowego usługi: wybierz tę opcję.

      • Punkt końcowy usługi: wybierz istniejący punkt końcowy usługi lub utwórz nowy (+ Nowy), podając następujące informacje w oknie Dodawanie połączenia usługi Azure Data Explorer:

        Ustawienie	Sugerowana wartość
        Metoda uwierzytelniania	Skonfiguruj poświadczenia tożsamości federacyjnej (FIC) (zalecane) lub wybierz autentykację za pomocą konta serwisowego (SPA).
        Nazwa połączenia	Wprowadź nazwę, aby zidentyfikować ten punkt końcowy usługi
        Adres URL klastra	Wartość można znaleźć w sekcji przeglądu klastra usługi Azure Data Explorer w witrynie Azure Portal
        Identyfikator jednostki usługi	Wprowadź identyfikator aplikacji Entra firmy Microsoft (utworzony jako wymaganie wstępne)
        Klucz aplikacji jednostki usługi	Wprowadź klucz aplikacji Entra firmy Microsoft (utworzony jako wymaganie wstępne)
        Identyfikator dzierżawy Microsoft Entra	Wprowadź dzierżawcę Microsoft Entra (na przykład microsoft.com lub contoso.com)

      Zaznacz pole wyboru Zezwalaj wszystkim potokom na używanie tego połączenia , a następnie wybierz przycisk OK.

      

   4. Jeśli polecenia administratora są długotrwałymi operacjami asynchronicznymi, zaznacz pole wyboru Poczekaj na ukończenie długich poleceń administratora asynchronicznego . Po włączeniu zadanie sonduje stan operacji przy użyciu polecenia .show operations , dopóki polecenie nie zostanie ukończone.

3. Wybierz pozycję Zapisz, a następnie na karcie Zadania sprawdź, czy istnieją trzy zadania: Wdrażanie tabel, Wdrażanie funkcji i Wdrażanie zasad.

   

Utwórz zadanie kwerendy

W razie potrzeby utwórz zadanie, aby uruchomić zapytanie względem klastra. Uruchamianie zapytań w potoku kompilacji lub wydania może służyć do weryfikowania zestawu danych i powodzenia lub niepowodzenia kroku na podstawie wyników zapytania. Kryteria powodzenia zadań mogą być oparte na progu liczby wierszy lub pojedynczej wartości w zależności od tego, co zwraca zapytanie.

1. Na karcie Zadania wybierz według zadania agenta i wyszukaj Azure Data Explorer.

2. W obszarze Uruchamianie zapytania usługi Azure Data Explorer wybierz pozycję Dodaj.

3. Wybierz pozycję Zapytanie Kusto i zaktualizuj zadanie przy użyciu następujących informacji:

   • Wyświetlana nazwa: nazwa zadania. Na przykład klaster zapytań.
   • Typ: wybierz Wbudowane.
   • Zapytanie: wprowadź zapytanie, które chcesz uruchomić.
   • Adres URL punktu końcowego: określ wcześniej utworzoną zmienną EndPoint URL .
   • Użyj punktu końcowego usługi: wybierz tę opcję.
   • Punkt końcowy usługi: wybierz punkt końcowy usługi.

   

4. W obszarze Wyniki zadania wybierz kryteria powodzenia zadania na podstawie wyników zapytania w następujący sposób:

   • Jeśli zapytanie zwraca wiersze, wybierz pozycję Liczba wierszy i podaj wymagane kryteria.

     

   • Jeśli zapytanie zwraca wartość, wybierz pozycję Pojedyncza wartość i podaj oczekiwany wynik.

     

Zadanie utworzenia bramy serwera zapytań

Jeśli to konieczne, utwórz zadanie, które uruchomi zapytanie w klastrze i wstrzyma postęp wydania do momentu uzyskania oczekiwanej liczby wierszy wyników zapytania. Zadanie Brama zapytań serwera jest zadaniem bez agenta, co oznacza, że zapytanie jest uruchamiane bezpośrednio na serwerze Usługi Azure DevOps.

1. Na karcie Zadania wybierz + jako typ zadania i wyszukaj Azure Data Explorer.

2. W obszarze Uruchom bramę serwera zapytań Azure Data Explorer wybierz opcję Dodaj.

3. Wybierz Kusto Query Server Gate a następnie Server Gate Test.

   

4. Skonfiguruj zadanie, podając następujące informacje:

   • Nazwa wyświetlana: Nazwa bramy.
   • Punkt końcowy usługi: wybierz punkt końcowy usługi.
   • Nazwa bazy danych: określ nazwę bazy danych.
   • Typ: Wybierz zapytanie wbudowane.
   • Zapytanie: wprowadź zapytanie, które chcesz uruchomić.
   • Maksymalny próg: określ maksymalną liczbę wierszy dla kryteriów powodzenia zapytania.

   

Uruchom wydanie

1. Wybierz + Wydanie>Utwórz wydanie, aby rozpocząć wydanie.

   

2. Na karcie Dzienniki sprawdź, czy wdrożenie zakończyło się pomyślnie.

   

Teraz tworzenie potoku wydania na potrzeby wdrożenia przedprodukcyjnego zostało ukończone.

Obsługa uwierzytelniania bez klucza dla zadań devOps w usłudze Azure Data Explorer

Rozszerzenie obsługuje uwierzytelnianie bez klucza dla klastrów usługi Azure Data Explorer. Uwierzytelnianie bez klucza umożliwia uwierzytelnianie w klastrach usługi Azure Data Explorer bez użycia klucza. Jest ona bezpieczniejsza i łatwiejsza do zarządzania.

Użyj uwierzytelniania za pomocą poświadczeń tożsamości federacyjnej (FIC) w połączeniu z usługą Azure Data Explorer

1. W wystąpieniu DevOps przejdź do Ustawienia projektu>Połączenia usług>Nowe połączenie usług>Azure Data Explorer.

2. Wybierz Poświadczenia tożsamości federacyjnej i wprowadź adres URL klastra, identyfikator główny usługi, identyfikator dzierżawy, nazwę połączenia z usługą, a następnie wybierz Zapisz.

3. W witrynie Azure Portal otwórz aplikację Microsoft Entra dla określonej jednostki usługi.

4. W obszarze Certyfikaty i wpisy tajne wybierz pozycję Poświadczenia federacyjne.

   

5. Wybierz pozycję Dodaj poświadczenia , a następnie w scenariuszu poświadczeń federacyjnych wybierz pozycję Inny wystawca i wypełnij ustawienia, korzystając z następujących informacji:

   • Wystawca: <https://vstoken.dev.azure.com/{System.CollectionId}> gdzie {System.CollectionId} jest identyfikatorem kolekcji organizacji Azure DevOps. Identyfikator kolekcji można znaleźć na następujące sposoby:

     • W potoku klasycznej wersji usługi Azure DevOps wybierz pozycję Zainicjuj zadanie. Identyfikator kolekcji jest wyświetlany w dziennikach.

   • Identyfikator podmiotu: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> gdzie {DevOps_Org_name} jest nazwą organizacji usługi Azure DevOps, {Project_Name} jest nazwą projektu i {Service_Connection_Name} jest nazwą połączenia z usługą utworzoną wcześniej.

     Uwaga

     Jeśli w nazwie połączenia z usługą znajduje się spacja, można ją użyć w polu ze spacją. Na przykład: sc://MyOrg/MyProject/My Service Connection.

   • Nazwa: wprowadź nazwę poświadczenia.

   

6. Wybierz Dodaj.

Użyj poświadczeń tożsamości federacyjnej lub tożsamości zarządzanej w połączeniu z usługą Azure Resource Manager (ARM)

1. W instancji DevOps przejdź do Project Settings>Service connections>New service connection>Azure Resource Manager.

   

2. W obszarze Metoda uwierzytelniania wybierz Federacja tożsamości dla obciążeń (automatyczna), aby kontynuować. Możesz także skorzystać z opcji ręcznej Federacja tożsamości dla obciążeń (ręcznie) aby określić szczegóły federacji tożsamości dla obciążeń lub opcję Tożsamość zarządzana. Dowiedz się więcej o konfigurowaniu tożsamości zarządzanej za pomocą Azure Resource Management w połączeniach usługowych Azure Resource Manager (ARM).

   

3. Wypełnij wymagane szczegóły, wybierz pozycję Weryfikuj, a następnie wybierz pozycję Zapisz.

Konfiguracja potoku YAML

Zadania można skonfigurować przy użyciu internetowego interfejsu użytkownika usługi Azure DevOps lub kodu YAML w schemacie potoku.

Rozszerzenie udostępnia trzy zadania potoku, wszystkie dostępne za pośrednictwem pliku YAML.

• Polecenie usługi Azure Data Explorer (ADXAdminCommand@5) — uruchamianie poleceń administratora/sterowania względem klastra ADX
• Zapytanie usługi Azure Data Explorer — uruchamianie zapytań względem klastra ADX i analizowanie wyników
• Brama serwera zapytań usługi Azure Data Explorer — zadanie sterowane wynikami zapytań bez agenta, służące do kontrolowania wydań.

Przykład polecenia administratora — polecenia wbudowane

Poniższy przykład uruchamia wbudowane polecenie administracyjne przy użyciu połączenia usługi Azure Resource Manager (ARM), które obsługuje Federację Tożsamości Obciążeń (WIF) i uwierzytelnianie tożsamości zarządzanej.

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

Przykład polecenia administratora — polecenia oparte na plikach

Poniższy przykład uruchamia polecenia administratora z plików pasujących do wzorca globu przy użyciu uwierzytelniania rejestracji aplikacji usługi 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

Można również użyć **/*.kql jako wzorca globu w zależności od konwencji nazewnictwa plików.

Przykład polecenia administratora — połączenie usługi Azure Resource Manager

W poniższym przykładzie użyto połączenia usługi Azure Resource Manager, które obsługuje usługę Workload Identity Federation (WIF) i tożsamość zarządzaną na potrzeby uwierzytelniania bez klucza:

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

Parametry wejściowe zadania

W poniższej tabeli opisano kluczowe parametry wejściowe zadania ADXAdminCommand@5 :

Metody uwierzytelniania

Rozszerzenie obsługuje następujące metody uwierzytelniania:

• Rejestracja aplikacji w usłudze Azure Active Directory (AAD) — należy użyć aadAppId, aadAppKey i aadTenantId do uwierzytelnienia się za pomocą jednostki usługi. Przechowuj poświadczenia jako bezpieczne zmienne potoku.
• Uwierzytelnianie oparte na certyfikatach — użyj certyfikatu zamiast klucza aplikacji do uwierzytelniania jednostki usługi. Przechowuj dane certyfikatu jako bezpieczne zmienne pipeliny.
• Tożsamość zarządzana — użyj połączenia usługi Azure Resource Manager skonfigurowanego z tożsamością zarządzaną. azureSubscription Ustaw dane wejściowe na nazwę połączenia z usługą.
• Federacja tożsamości obciążenia (WIF) — użyj połączenia usługi Azure Resource Manager z federacją tożsamości obciążenia (automatyczną lub ręczną). Zalecane podejście to podejście bez klucza. azureSubscription Ustaw dane wejściowe na nazwę połączenia usługi.

Przykładowe zapytanie

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