Úloha Azure DevOps pro Azure Data Explorer

Azure DevOps Services poskytuje nástroje pro spolupráci na vývoji, jako jsou vysoce výkonné kanály, bezplatná privátní úložiště Git, konfigurovatelné desky Kanban a rozsáhlé možnosti automatizovaného a průběžného testování. Azure Pipelines je funkce Azure DevOps, která umožňuje spravovat CI/CD a nasazovat kód pomocí vysoce výkonných kanálů, které pracují s libovolným jazykem, platformou a cloudem. Azure Data Explorer – Pipeline Tools je úloha Azure Pipelines, která umožňuje vytvářet kanály verzí a nasazovat změny databáze do databází Azure Data Explorer. Je k dispozici zdarma na Visual Studio Marketplace. Toto rozšíření zahrnuje 3 základní úlohy:

• Příkaz Azure Data Explorer – Spuštění příkazů Správa v clusteru Azure Data Explorer

• Azure Data Explorer Query – Spouštění dotazů v clusteru Azure Data Explorer a parsování výsledků

• Azure Data Explorer Query Server Gate – Vydání úloh brány bez agentů v závislosti na výsledku dotazu

  

Tento dokument popisuje jednoduchý příklad použití úlohy Azure Data Explorer – Pipeline Tools k nasazení změn schématu do databáze. Kompletní kanály CI/CD najdete v dokumentaci k Azure DevOps.

Požadavky

• Předplatné Azure. Vytvořte si bezplatný účet Azure.
• Cluster a databáze Azure Data Explorer. Vytvořte cluster a databázi.
• Nastavení clusteru Azure Data Explorer:
  • Vytvořte Microsoft Entra aplikaci zřízením aplikace Microsoft Entra.
  • Udělte přístup k aplikaci Microsoft Entra v databázi Azure Data Explorer tím, že spravujete oprávnění databáze Azure Data Explorer.
• Nastavení Azure DevOps:
  • Zaregistrujte se do bezplatné organizace.
  • Vytvořte organizaci.
  • Vytvoření projektu v Azure DevOps
  • Kódujte pomocí Gitu.
• Instalace rozšíření:
  • Pokud jste vlastníkem instance Azure DevOps, nainstalujte rozšíření z Marketplace.
  • Pokud NEJSTE vlastníkem instance Azure DevOps, obraťte se na vlastníka a požádejte ho o instalaci.

Příprava obsahu na vydání

Jsou tři způsoby, jak v úloze spouštět příkazy správce pro cluster.

• Použití vyhledávacího vzoru k získání více souborů příkazů z místní složky agenta (zdroje sestavení nebo artefakty vydané verze)

  

• Zápis příkazů v textu

  

• Určení cesty k souboru pro získání souborů příkazů přímo ze správy zdrojového kódu Git (doporučeno)

  

  Ve svém úložišti Git vytvořte následující ukázkové složky (Functions, Policies, Tables). Zkopírujte soubory odsud do příslušných složek, jak vidíte níže, a potvrďte změny. Ukázkové soubory jsou k dispozici pro provedení následujícího pracovního postupu.

  

  Tip

  Při vytváření vlastního pracovního postupu doporučujeme nastavit idempotentní kód. Můžete například použít .create-merge table místo a .create table.create-or-alter funkci místo .create funkce .

Vytvoření kanálu verze

1. Přihlaste se ke své organizaci Azure DevOps.

2. V nabídce vlevo vybertePipelines Releases (Vydané kanály>) a vyberte New pipeline (Nový kanál).

   

3. Otevře se okno Nový kanál verze . Na kartě Kanály v podokně Vybrat šablonu vyberte Prázdná úloha.

   

4. Vyberte tlačítko Fáze . V podokně Fáze přidejte název fáze. Vyberte Uložit a kanál uložte.

   

5. Vyberte Tlačítko Přidat artefakt . V podokně Přidat artefakt vyberte úložiště, ve kterém existuje váš kód, vyplňte relevantní informace a klikněte na Přidat. Vyberte Uložit a kanál uložte.

   

6. Na kartě Proměnné vyberte + Přidat a vytvořte proměnnou pro adresu URL koncového bodu , která se použije v úloze. Napište Název a Hodnotu koncového bodu. Vyberte Uložit a kanál uložte.

   

   Pokud chcete najít svůj Endpoint_URL, stránka přehledu clusteru Azure Data Explorer v Azure Portal obsahuje identifikátor URI clusteru Azure Data Explorer. Vytvořte identifikátor URI v následujícím formátu https://<Azure Data Explorer cluster URI>?DatabaseName=<DBName>. Například https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB.

   

Vytvoření úloh pro nasazení složek

1. Na kartě Kanál klikněte na 1 úlohu, 0 úkol a přidejte úkoly.

   

2. Opakováním následujících kroků vytvořte příkazové úlohy pro nasazení souborů ze složek Tabulky, Funkce a Zásady :

   

   1. Na kartě Úlohy vyberte + podle úlohy agenta a vyhledejte Azure Data Explorer.

   2. V části Run Azure Data Explorer Command (Spustit příkaz Azure Data Explorer) vyberte Add (Přidat).

   3. Vyberte Příkaz Kusto a aktualizujte úlohu o následující informace:

      • Zobrazovaný název: Název úkolu. Například kde <FOLDER> je název složky pro úlohu nasazení, Deploy <FOLDER> kterou vytváříte.

      • Cesta k souboru: Pro každou složku zadejte cestu, kde */<FOLDER>/*.csl<FOLDER> je příslušná složka úkolu.

      • Adresa URL koncového bodu: Zadejte proměnnou vytvořenou EndPoint URL v předchozím kroku.

      • Použít koncový bod služby: Vyberte tuto možnost.

      • Koncový bod služby: Vyberte existující koncový bod služby nebo vytvořte nový (+ Nový). V okně Přidat připojení služby Azure Data Explorer zadejte následující informace:

        Nastavení	Navrhovaná hodnota
        Název připojení	Zadejte název pro identifikaci tohoto koncového bodu služby.
        Adresa URL clusteru	Hodnotu najdete v části přehledu vašeho clusteru Azure Data Explorer v Azure Portal
        ID instančního objektu	Zadejte ID aplikace Microsoft Entra (vytvořené podle předpokladu).
        Klíč aplikace instančního objektu	Zadejte klíč aplikace Microsoft Entra (vytvořený jako předpoklad).
        ID tenanta Microsoft Entra	Zadejte tenanta Microsoft Entra (například microsoft.com nebo contoso.com).

      Zaškrtněte políčko Povolit všem kanálům používat toto připojení a pak vyberte OK.

      

3. Vyberte Uložit a pak na kartě Úlohy ověřte, že existují tři úlohy: Nasazení tabulek, Nasazení funkcí a Nasazení zásad.

   

Vytvoření úlohy dotazu

V případě potřeby vytvořte úlohu pro spuštění dotazu na cluster. Spuštěné dotazy v kanálu sestavení nebo verze se dají použít k ověření datové sady a na základě výsledků dotazu provést úspěšný nebo neúspěšný krok. Kritéria úspěšnosti úkolů můžou být založená na prahové hodnotě počtu řádků nebo na jedné hodnotě v závislosti na tom, co dotaz vrátí.

1. Na kartě Úlohy vyberte + podle úlohy agenta a vyhledejte Azure Data Explorer.

2. V části Spustit dotaz Azure Data Explorer vyberte Přidat.

3. Vyberte Dotaz Kusto a aktualizujte úlohu pomocí následujících informací:

   • Zobrazovaný název: Název úkolu. Například Dotaz na cluster.
   • Typ: Vyberte Vloženo.
   • Dotaz: Zadejte dotaz, který chcete spustit.
   • Adresa URL koncového bodu: Zadejte proměnnou vytvořenou EndPoint URL dříve.
   • Použít koncový bod služby: Vyberte tuto možnost.
   • Koncový bod služby: Vyberte koncový bod služby.

   

4. V části Výsledky úkolu vyberte kritéria úspěchu úkolu na základě výsledků dotazu následujícím způsobem:

   • Pokud dotaz vrací řádky, vyberte Počet řádků a zadejte kritéria, která potřebujete.

     

   • Pokud dotaz vrátí hodnotu, vyberte Jednoduchá hodnota a zadejte očekávaný výsledek.

     

Vytvoření úlohy Query Server Gate

V případě potřeby vytvořte úlohu, která spustí dotaz na cluster a zamezuje průběh vydání čekající na počet řádků výsledků dotazu. Úloha Server Query Gate je úloha bez agentů, což znamená, že dotaz běží přímo na Azure DevOps Server.

1. Na kartě Úlohy vyberte + podle úlohy bez agentů a vyhledejte Azure Data Explorer.

2. V části Run Azure Data Explorer Query Server Gate (Spustit bránu azure Data Explorer query serveru) vyberte Add (Přidat).

3. Vyberte Kusto Query Server Gate a pak vyberte Test brány serveru.

   

4. Nakonfigurujte úlohu s následujícími informacemi:

   • Zobrazovaný název: Název brány.
   • Koncový bod služby: Vyberte koncový bod služby.
   • Název databáze: Zadejte název databáze.
   • Typ: Vyberte Vložený dotaz.
   • Dotaz: Zadejte dotaz, který chcete spustit.
   • Maximální prahová hodnota: Zadejte maximální počet řádků pro kritéria úspěšnosti dotazu.

   

Poznámka

Při spuštění verze by se měly zobrazit výsledky podobné následujícímu.

Spuštění vydané verze

1. Vyberte + Release>Create release (Vytvořit verzi ) a vytvořte verzi.

   

2. Na kartě Protokoly zkontrolujte, jestli je nasazení úspěšné.

   

Dokončili jste vytvoření kanálu verze pro nasazení do předprodukčního prostředí.

Konfigurace kanálu Yaml

Úlohy je možné nakonfigurovat jak prostřednictvím webového uživatelského rozhraní Azure DevOps (jak je znázorněno výše), tak prostřednictvím kódu Yaml v rámci schématu kanálu.

Ukázkové použití příkazu Správa

steps:
- task: Azure-Kusto.PublishToADX.PublishToADX.PublishToADX@1
  displayName: '<Task Name>'
  inputs:
    script: '<inline Script>'
    waitForOperation: true
    kustoUrls: '$(CONNECTIONSTRING):443?DatabaseName=""'
    customAuth: true
    connectedServiceName: '<Service Endpoint Name>'
    serialDelay: 1000
  continueOnError: true
  condition: ne(variables['ProductVersion'], '') ## Custom condition Sample

Ukázkové využití dotazu

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@1
  displayName: '<Task Display Name>'
  inputs:
    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>'
    customAuth: true
    connectedServiceName: '<Service Endpoint Name>'
  continueOnError: true