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. Usługa Azure Pipelines to funkcja usługi Azure DevOps, która umożliwia zarządzanie ciągłą integracja/ciągłe wdrażanie kodu przy użyciu potoków o wysokiej wydajności, które współpracują z dowolnym językiem, platformą i chmurą. Azure Data Explorer — narzędzia potoku to zadanie usługi Azure Pipelines, które umożliwia tworzenie potoków wydania i wdrażanie zmian bazy danych w bazach danych usługi Azure Data Explorer. Jest ona dostępna bezpłatnie w witrynie Visual Studio Marketplace. To rozszerzenie obejmuje następujące podstawowe zadania:

• Polecenie usługi Azure Data Explorer — uruchamianie poleceń administracyjnych względem klastra 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

• Brama serwera zapytań usługi Azure Data Explorer — zadanie bez agenta do wydania bramy w zależności od wyniku zapytania

  

W tym dokumencie opisano prosty przykład użycia zadania Azure Data Explorer — Pipeline Tools w celu wdrożenia zmian schematu w bazie danych. Aby uzyskać pełne potoki ciągłej integracji/ciągłego wdrażania, 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, aprowizuj aplikację Firmy 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ę w celu uzyskania bezpłatnej organizacji.
  • 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 witryny Marketplace, w przeciwnym razie skontaktuj się z właścicielem 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)

  

• Pisanie poleceń wbudowanych

  

• 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.

  

  Porada

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

Tworzenie potoku wydania

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

2. Wybierz pozycję Wydania potoków>z menu po lewej stronie i wybierz pozycję Nowy potok.

   

3. Zostanie otwarte okno Nowy potok wydania. Na karcie Potoki w okienku Wybierz szablon wybierz pozycję Puste zadanie.

   

4. Wybierz przycisk Stage (Etap ). W okienku Etap dodaj nazwę etapu. Wybierz pozycję Zapisz , aby zapisać potok.

   

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 pozycję Zapisz , aby zapisać potok.

   

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

   

   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

   

Tworzenie zadania wdrażania folderów

1. Na karcie Potok wybierz 1 zadanie, 0 zadanie , 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 zadania 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:

      • Nazwa wyświetlana: 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 uwierzytelnianie jednostki usługi (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 entra firmy Microsoft	Wprowadź dzierżawę firmy 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.

      

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.

   

Tworzenie zadania Kwerenda

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 pozycję + Według zadania agenta i wyszukaj pozycję 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:

   • Nazwa wyświetlana: nazwa zadania. Na przykład klaster zapytań.
   • Typ: wybierz pozycję 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.

     

Tworzenie zadania Brama serwera zapytań

W razie potrzeby utwórz zadanie, aby uruchomić zapytanie względem klastra i bramę postępu wydania oczekujące na liczbę 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 pozycję + Według zadania bez agenta i wyszukaj pozycję Azure Data Explorer.

2. W obszarze Uruchom bramę serwera zapytań usługi Azure Data Explorer wybierz pozycję Dodaj.

3. Wybierz pozycję Kusto Query Server Gate, a następnie wybierz pozycję Test bramy serwera.

   

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.

   

Uwaga

Powinny zostać wyświetlone wyniki podobne do poniższych podczas uruchamiania wydania.

Uruchamianie wydania

1. Wybierz pozycję + Wydanie>Utwórz wydanie, aby utworzyć wydanie.

   

2. Na karcie Dzienniki sprawdź, czy stan wdrożenia zakończył 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 i jest bezpieczniejsze i łatwiejsze do zarządzania niż używanie klucza.

Używanie uwierzytelniania poświadczeń tożsamości federacyjnej (FIC) w połączeniu usługi Azure Data Explorer

1. W wystąpieniu metodyki DevOps przejdź do pozycji Project Settings Service connections>New service connection Azure Data Explorer (Połączenia z usługą Project Settings>— Nowe połączenie z usługą>Azure Data Explorer).

2. Wybierz pozycję Poświadczenia tożsamości federacyjnej i wprowadź adres URL klastra, identyfikator jednostki usługi, identyfikator dzierżawy, nazwę połączenia z usługą, a następnie wybierz pozycję 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 usługi 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ę miejsce, możesz użyć go ze spacją w polu. Na przykład: sc://MyOrg/MyProject/My Service Connection.

   • Nazwa: wprowadź nazwę poświadczenia.

   

6. Wybierz Dodaj.

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

1. W wystąpieniu metodyki DevOps przejdź do pozycji Project Settings Service connections>New service connection Azure Resource Manager (Połączenia usługi Project Settings>— Nowe połączenie z usługą>Azure Resource Manager).

   

2. W obszarze Metoda uwierzytelniania wybierz pozycję Federacja tożsamości obciążenia (automatyczna). Alternatywnie możesz użyć ręcznej opcji Federacja tożsamości obciążenia (ręcznie), aby określić szczegóły federacji tożsamości obciążenia lub użyć opcji Tożsamość zarządzana. Aby uzyskać więcej informacji na temat konfigurowania tożsamości zarządzanej przy użyciu usługi Azure Resource Management, zobacz Azure Resource Manager (ARM) Service Connections (Połączenia usługi 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ć zarówno za pośrednictwem internetowego interfejsu użytkownika usługi Azure DevOps, jak i kodu Yaml w schemacie potoku.

Przykładowe użycie polecenia administratora

YAML

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

Przykładowe użycie zapytań

YAML

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