Úloha Azure DevOps pro Azure Data Explorer

Azure DevOps Services poskytuje nástroje pro spolupráci pro vývoj, jako jsou vysoce výkonné kanály, bezplatné privátní úložiště Git, konfigurovatelné panely Kanbanu 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é fungují s libovolným jazykem, platformou a cloudem. Azure Data Explorer – Nástroje kanálu je úloha Azure Pipelines, která umožňuje vytvářet kanály verzí a nasazovat změny databáze do databází Azure Data Exploreru. Je k dispozici zdarma v sadě Visual Studio Marketplace. Toto rozšíření zahrnuje následující základní úlohy:

• Příkaz Azure Data Exploreru – Spuštění příkazů správce v clusteru Azure Data Exploreru

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

• Brána dotazovacího serveru Azure Data Exploreru – Úloha bez agentů pro gate vydané verze v závislosti na výsledku dotazu

  

Tento dokument popisuje jednoduchý příklad použití úlohy Nástroje kanálu Azure Data Explorer 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 bezplatný účet Azure.
• Cluster a databáze Azure Data Exploreru. Vytvořte cluster a databázi.
• Nastavení clusteru Azure Data Exploreru:
  • Vytvořte aplikaci Microsoft Entra zřízením aplikace Microsoft Entra.
  • Udělte přístup k aplikaci Microsoft Entra v databázi Azure Data Exploreru tím, že spravujete oprávnění databáze Azure Data Exploreru.
• Nastavení Azure DevOps:
  • Zaregistrujte si bezplatnou organizaci.
  • Vytvořte organizaci.
  • Vytvořte projekt v Azure DevOps.
  • Psaní kódu pomocí Gitu
• Instalace rozšíření:

  • Pokud jste vlastníkem instance Azure DevOps, nainstalujte rozšíření z Marketplace, jinak se obraťte na vlastníka instance Azure DevOps a požádejte ho, aby ho nainstaloval.

    

    

Příprava obsahu na vydání

Pomocí následujících metod můžete spouštět příkazy správce v clusteru v rámci úlohy:

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

  

• Psaní příkazů na řádku

  

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

  

  V úložišti Git vytvořte následující ukázkové složky (Funkce, Zásady, Tabulky). Zkopírujte soubory z úložiště ukázek do příslušných složek 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 vytvořit idempotentní kód. Například místo funkce a .create-merge table .create tablemísto funkce použijte .create-or-alter funkci .create .

Vytvoření kanálu verze

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

2. V nabídce vlevo vyberte Verze kanálů>a vyberte Nový kanál.

   

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

   

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 kód existuje, vyplňte relevantní informace a vyberte 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žívá v úloze. Zadejte název a hodnotu koncového bodu. Vyberte Uložit a kanál uložte.

   

   Pokud chcete najít adresu URL koncového bodu, přejděte na stránku přehledu clusteru Azure Data Exploreru na webu Azure Portal a zkopírujte identifikátor URI clusteru. Vytvořte identifikátor URI proměnné v následujícím formátu https://<ClusterURI>?DatabaseName=<DBName>. Například https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

Vytvoření úlohy nasazení složek

1. Na kartě Kanál vyberte 1 úlohu, 0 úkolu, který chcete přidat.

   

2. Opakováním následujících kroků vytvořte úlohy příkazů 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 Spustit příkaz Azure Data Exploreru vyberte Přidat.

   3. Vyberte příkaz Kusto a aktualizujte úlohu následujícími informacemi:

      • Zobrazovaný název: Název úkolu. Kde je například název složky pro úlohu nasazení, Deploy <FOLDER> <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ý) a v okně Přidat připojení služby Azure Data Exploreru zadejte následující informace:

        Nastavení	Navrhovaná hodnota
        Metoda ověřování	Nastavte přihlašovací údaje federované identity (doporučeno) nebo vyberte ověřování instančního objektu (SPA).
        Název připojení	Zadejte název pro identifikaci tohoto koncového bodu služby.
        Adresa URL clusteru	Hodnotu najdete v části přehledu clusteru Azure Data Exploreru na webu Azure Portal.
        ID instančního objektu	Zadejte ID aplikace Microsoft Entra (vytvořené jako předpoklad).
        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 potom na kartě Úlohy ověřte, že existují tři úlohy: Nasazení tabulek, nasazení funkcí a zásady nasazení.

   

Vytvoření úlohy dotazu

V případě potřeby vytvořte úlohu, která spustí dotaz na cluster. Spouštění dotazů v kanálu buildu nebo verze se dá použít k ověření datové sady a k úspěšnému nebo neúspěšném kroku na základě výsledků dotazu. Kritéria úspěchu úkolů můžou být založená na prahové hodnotě počtu řádků nebo 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 Exploreru vyberte Přidat.

3. Vyberte Dotaz Kusto a aktualizujte úlohu následujícími informacemi:

   • Zobrazovaný název: Název úkolu. Například cluster dotazů.
   • Typ: Vyberte vložený.
   • 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 úkolů vyberte kritéria úspěchu úkolu na základě výsledků dotazu následujícím způsobem:

   • Pokud dotaz vrátí řádky, vyberte Počet řádků a zadejte kritéria, která požadujete.

     

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

     

Vytvoření úlohy Brány dotazovacího serveru

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

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

2. V části Spustit bránu dotazovacího serveru Azure Data Exploreru vyberte Přidat.

3. Vyberte Bránu dotazovacího serveru Kusto 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ěchu dotazu.

   

Poznámka:

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

Spuštění vydané verze

1. Pokud chcete vytvořit verzi, vyberte a>uvolněte verzi.

   

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

   

Vytvoření kanálu verze pro nasazení do předprodukčního prostředí je teď hotové.

Podpora ověřování bez klíčů pro úlohy DevOps v Azure Data Exploreru

Rozšíření podporuje ověřování bez klíčů pro clustery Azure Data Exploreru. Ověřování bez klíčů umožňuje ověřovat se v clusterech Azure Data Exploreru bez použití klíče a je bezpečnější a snadněji se spravuje než použití klíče.

Použití ověřování federovaných identit (FIC) v připojení služby Azure Data Explorer

1. V instanci DevOps přejděte do části Připojení>služby Project Settings>Service Nové připojení>služby Azure Data Explorer.

2. Vyberte Přihlašovací údaje federované identity a zadejte adresu URL clusteru, ID instančního objektu, ID tenanta, název připojení služby a pak vyberte Uložit.

3. Na webu Azure Portal otevřete aplikaci Microsoft Entra pro zadaný instanční objekt.

4. V části Certifikáty a tajné kódy vyberte federované přihlašovací údaje.

   

5. Vyberte Přidat přihlašovací údaje a pak pro scénář federovaných přihlašovacích údajů vyberte Jiný vystavitel a vyplňte nastavení pomocí následujících informací:

   • Vystavitel: <https://vstoken.dev.azure.com/{System.CollectionId}> kde {System.CollectionId} je ID kolekce vaší organizace Azure DevOps. ID kolekce najdete následujícími způsoby:

     • V kanálu verze Azure DevOps Classic vyberte Inicializovat úlohu. ID kolekce se zobrazí v protokolech.

   • Identifikátor subjektu: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> kde {DevOps_Org_name} je název organizace Azure DevOps, {Project_Name} je název projektu a {Service_Connection_Name} je název připojení služby, který jste vytvořili dříve.

     Poznámka:

     Pokud je v názvu připojení služby místo, můžete ho použít s mezerou v poli. Například: sc://MyOrg/MyProject/My Service Connection.

   • Název: Zadejte název přihlašovacích údajů.

   

6. Vyberte Přidat.

Použití přihlašovacích údajů federované identity nebo spravované identity v připojení ke službě Azure Resource Manager (ARM)

1. V instanci DevOps přejděte na připojení>služby Project Settings>Service Nové připojení>služby Azure Resource Manager.

   

2. V části Metoda ověřování vyberte Federaci identit úloh (automaticky). Alternativně můžete použít ruční federování identit úloh (ruční) k určení podrobností o federaci identit úloh nebo použít možnost Spravovaná identita . Další informace o nastavení spravované identity pomocí správy prostředků Azure najdete v tématu Připojení služby Azure Resource Manager (ARM).

   

3. Vyplňte požadované podrobnosti, vyberte Ověřit a pak vyberte Uložit.

Konfigurace kanálu Yaml

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

Ukázkové využití příkazů správce

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

Použití ukázkového dotazu

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