Tugas Azure DevOps untuk Azure Data Explorer

Azure DevOps Services menyediakan alat kolaborasi pengembangan seperti alur berkinerja tinggi, repositori Git privat gratis, papan Kanban yang dapat dikonfigurasi, dan kemampuan pengujian otomatis dan berkelanjutan yang luas. Azure Pipelines adalah kemampuan Azure DevOps yang memungkinkan Anda mengelola CI/CD untuk menyebarkan kode Anda dengan alur berkinerja tinggi yang berfungsi dengan bahasa, platform, dan cloud apa pun. Azure Data Explorer - Alat Alur adalah tugas Azure Pipelines yang memungkinkan Anda membuat alur rilis dan menyebarkan perubahan database Anda ke database Azure Data Explorer Anda. Ini tersedia secara gratis di Visual Studio Marketplace. Ekstensi ini mencakup tugas dasar berikut:

• Perintah Azure Data Explorer - Jalankan Perintah Admin terhadap kluster Azure Data Explorer

• Kueri Azure Data Explorer - Menjalankan Kueri terhadap kluster Azure Data Explorer dan mengurai hasilnya

• Azure Data Explorer Query Server Gate - Tugas tanpa agen ke rilis Gate bergantung pada hasil kueri

  

Dokumen ini menjelaskan contoh sederhana tentang penggunaan tugas Azure Data Explorer - Alat Alur untuk menyebarkan perubahan skema Anda ke database Anda. Untuk alur CI/CD lengkap, lihat dokumentasi Azure DevOps.

Prasyarat

• Langganan Azure. Membuat akun Azure gratis.
• Kluster dan database Azure Data Explorer. Membuat kluster dan database.
• Penyiapan kluster Azure Data Explorer:
  • Buat aplikasi Microsoft Entra dengan menyediakan aplikasi Microsoft Entra.
  • Berikan akses ke Aplikasi Microsoft Entra Anda di database Azure Data Explorer Anda dengan mengelola izin database Azure Data Explorer.
• Penyiapan Azure DevOps:
  • Mendaftarlah untuk organisasi gratis.
  • Membuat organisasi.
  • Buat proyek di Azure DevOps.
  • Kode dengan Git.
• Penginstalan Ekstensi:

  • Jika Anda adalah pemilik instans Azure DevOps, instal ekstensi dari Marketplace, jika tidak, hubungi pemilik instans Azure DevOps Anda dan minta mereka untuk menginstalnya.

    

    

Menyiapkan konten Anda untuk rilis

Anda dapat menggunakan metode berikut untuk menjalankan perintah admin terhadap kluster dalam tugas:

• Gunakan pola pencarian untuk mendapatkan beberapa file perintah dari folder agen lokal (Sumber build atau Artefak rilis)

  

• Tulis perintah sebaris

  

• Tentukan jalur file untuk mendapatkan file perintah langsung dari kontrol sumber git (disarankan)

  

  Buat folder sampel berikut (Fungsi, Kebijakan, Tabel) di repositori Git Anda. Salin file dari repositori sampel ke folder masing-masing dan terapkan perubahan. File sampel disediakan untuk menjalankan alur kerja berikut.

  

  Tip

  Saat membuat alur kerja Anda sendiri, sebaiknya buat kode Anda idempotensi. Misalnya, gunakan .create-merge table alih-alih .create table, dan gunakan .create-or-alter fungsi alih-alih .create fungsi.

Membuat alur pipa rilis

1. Masuk ke Organisasi Azure DevOps Anda.

2. Pilih Rilis> Alur dari menu sebelah kiri dan pilih Alur baru.

   

3. Jendela Alur rilis baru terbuka. Di tab Alur , di panel Pilih templat , pilih Pekerjaan kosong.

   

4. Pilih tombol Tahap . Di panel Tahap, tambahkan Nama tahap. Pilih Simpan untuk menyimpan alur Anda.

   

5. Pilih tombol Tambahkan artefak . Di panel Tambahkan artefak , pilih repositori tempat kode Anda ada, isi informasi yang relevan, dan pilih Tambahkan. Pilih Simpan untuk menyimpan alur Anda.

   

6. Di tab Variabel, pilih + Tambahkan untuk membuat variabel untuk URL Titik Akhir yang digunakan dalam tugas. Tulis Nama dan Nilai titik akhir. Pilih Simpan untuk menyimpan alur Anda.

   

   Untuk menemukan URL titik akhir Anda, buka halaman gambaran umum kluster Azure Data Explorer Anda di portal Azure dan salin URI kluster. Buat URI variabel dalam format https://<ClusterURI>?DatabaseName=<DBName>berikut . Misalnya: https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

Membuat tugas menyebarkan folder

1. Di tab Alur , pilih pada 1 pekerjaan, 0 tugas untuk menambahkan tugas.

   

2. Ulangi langkah-langkah berikut untuk membuat tugas perintah untuk menyebarkan file dari folder Tabel, Fungsi, dan Kebijakan :

   

   1. Di tab Tugas , pilih + menurut pekerjaan Agen dan cari Azure Data Explorer.

   2. Di bawah Jalankan Perintah Azure Data Explorer, pilih Tambahkan.

   3. Pilih Perintah Kusto dan perbarui tugas dengan informasi berikut:

      • Nama tampilan: Nama tugas. Misalnya, Deploy <FOLDER> di mana <FOLDER> adalah nama folder untuk tugas penyebaran yang Anda buat.

      • Jalur file: Untuk setiap folder, tentukan jalur sebagai */<FOLDER>/*.csl tempat <FOLDER> folder yang relevan untuk tugas tersebut.

      • URL Titik Akhir: Tentukan variabel yang EndPoint URL dibuat di langkah sebelumnya.

      • Gunakan Titik Akhir Layanan: Pilih opsi ini.

      • Titik Akhir Layanan: Pilih titik akhir layanan yang sudah ada atau buat yang baru (+ Baru) yang menyediakan informasi berikut di jendela Tambahkan koneksi layanan Azure Data Explorer:

        Pengaturan	Nilai yang disarankan
        Metode autentikasi	Siapkan Federated Identity Credentials (FIC) (disarankan), atau Pilih Autentikasi Perwakilan Layanan (SPA).
        Nama koneksi	Masukkan nama untuk mengidentifikasi titik akhir layanan ini
        Url Kluster	Nilai dapat ditemukan di bagian gambaran umum Kluster Azure Data Explorer Anda di portal Azure
        Id Perwakilan Layanan	Masukkan ID Aplikasi Microsoft Entra (dibuat sebagai prasyarat)
        Kunci Aplikasi Perwakilan Layanan	Masukkan Kunci Aplikasi Microsoft Entra (dibuat sebagai prasyarat)
        ID penyewa Microsoft Entra	Masukkan penyewa Microsoft Entra Anda (seperti microsoft.com atau contoso.com)

      Pilih kotak centang Izinkan semua alur untuk menggunakan koneksi ini lalu pilih OK.

      

3. Pilih Simpan lalu di tab Tugas , verifikasi bahwa ada tiga tugas: Sebarkan Tabel, Sebarkan Fungsi, dan Sebarkan Kebijakan.

   

Membuat tugas Kueri

Jika perlu, buat tugas untuk menjalankan kueri terhadap kluster. Menjalankan kueri dalam alur Build atau Release dapat digunakan untuk memvalidasi himpunan data dan membuat langkah berhasil atau gagal berdasarkan hasil kueri. Kriteria keberhasilan tugas dapat didasarkan pada ambang batas jumlah baris atau nilai tunggal tergantung pada apa yang dikembalikan kueri.

1. Di tab Tugas , pilih + menurut pekerjaan Agen dan cari Azure Data Explorer.

2. Di bawah Jalankan Kueri Azure Data Explorer, pilih Tambahkan.

3. Pilih Kueri Kusto dan perbarui tugas dengan informasi berikut:

   • Nama tampilan: Nama tugas. Misalnya, kluster Kueri.
   • Jenis: Pilih Sebaris.
   • Kueri: Masukkan kueri yang ingin Anda jalankan.
   • URL Titik Akhir: Tentukan variabel yang EndPoint URL dibuat sebelumnya.
   • Gunakan Titik Akhir Layanan: Pilih opsi ini.
   • Titik Akhir Layanan: Pilih titik akhir layanan.

   

4. Di bawah Hasil Tugas, pilih kriteria keberhasilan tugas berdasarkan hasil kueri Anda, sebagai berikut:

   • Jika kueri Anda mengembalikan baris, pilih Jumlah Baris dan berikan kriteria yang Anda butuhkan.

     

   • Jika kueri Anda mengembalikan nilai, pilih Nilai Tunggal dan berikan hasil yang diharapkan.

     

Membuat tugas Gerbang Server Kueri

Jika perlu, buat tugas untuk menjalankan kueri terhadap kluster dan gabungkan kemajuan rilis yang menunggu Jumlah Baris Hasil Kueri. Tugas Gerbang Kueri Server adalah pekerjaan tanpa agen, yang berarti bahwa kueri berjalan langsung di Azure DevOps Server.

1. Di tab Tugas , pilih + menurut pekerjaan Tanpa Agen dan cari Azure Data Explorer.

2. Di bawah Jalankan Gerbang Server Kueri Azure Data Explorer, pilih Tambahkan.

3. Pilih Gerbang Server Kueri Kusto lalu pilih Uji Gerbang Server.

   

4. Konfigurasikan tugas yang memberikan informasi berikut:

   • Nama tampilan: Nama gerbang.
   • Titik Akhir Layanan: Pilih titik akhir layanan.
   • Nama database: Tentukan nama database.
   • Jenis: Pilih Kueri sebaris.
   • Kueri: Masukkan kueri yang ingin Anda jalankan.
   • Ambang maksimum: Tentukan jumlah baris maksimum untuk kriteria keberhasilan kueri.

   

Catatan

Anda akan melihat hasil seperti berikut Saat menjalankan rilis.

Jalankan rilis

1. Pilih + Rilis>Buat rilis untuk membuat rilis.

   

2. Di tab Log , periksa status penyebaran berhasil.

   

Sekarang pembuatan alur rilis untuk penyebaran ke praproduksi selesai.

Dukungan autentikasi tanpa kunci untuk tugas Azure Data Explorer DevOps

Ekstensi ini mendukung autentikasi tanpa kunci untuk kluster Azure Data Explorer. Autentikasi tanpa kunci memungkinkan Anda mengautentikasi ke kluster Azure Data Explorer tanpa menggunakan kunci dan lebih aman dan lebih mudah dikelola daripada menggunakan kunci.

Menggunakan autentikasi Federated Identity Credentials (FIC) dalam koneksi layanan Azure Data Explorer

1. Di instans DevOps Anda, buka Koneksi layanan Pengaturan>Proyek Koneksi>>layanan baru Azure Data Explorer.

2. Pilih Kredensial Identitas Federasi, dan masukkan URL kluster Anda, ID perwakilan layanan, ID penyewa, nama koneksi layanan, lalu pilih Simpan.

3. Di portal Azure, buka aplikasi Microsoft Entra untuk perwakilan layanan yang ditentukan.

4. Di bawah Sertifikat & rahasia, pilih Kredensial federasi.

   

5. Pilih Tambahkan kredensial lalu untuk skenario kredensial Federasi, pilih Penerbit lain, dan isi pengaturan menggunakan informasi berikut:

   • Pengeluar sertifikat: <https://vstoken.dev.azure.com/{System.CollectionId}> di mana {System.CollectionId} adalah ID koleksi organisasi Azure DevOps Anda. Anda dapat menemukan ID koleksi dengan cara berikut:

     • Di alur rilis klasik Azure DevOps, pilih Inisialisasi pekerjaan. ID koleksi ditampilkan dalam log.

   • Pengidentifikasi subjek: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> di mana {DevOps_Org_name} adalah nama organisasi Azure DevOps, {Project_Name} adalah nama proyek, dan {Service_Connection_Name} merupakan nama koneksi layanan yang Anda buat sebelumnya.

     Catatan

     Jika ada ruang dalam nama koneksi layanan Anda, Anda dapat menggunakannya dengan ruang di bidang . Misalnya: sc://MyOrg/MyProject/My Service Connection.

   • Nama: Masukkan nama untuk kredensial.

   

6. Pilih Tambahkan.

Menggunakan Kredensial Identitas Terfederasi atau Identitas Terkelola dalam koneksi layanan Azure Resource Manager (ARM)

1. Dalam instans DevOps Anda, buka Koneksi layanan Pengaturan>Proyek Koneksi>>layanan baru Azure Resource Manager.

   

2. Di bawah Metode autentikasi, pilih Federasi Identitas Beban Kerja (otomatis). Atau, Anda dapat menggunakan opsi Federasi Identitas Beban Kerja (manual) manual untuk menentukan detail Federasi Identitas Beban Kerja, atau menggunakan opsi Identitas Terkelola. Untuk informasi selengkapnya tentang menyiapkan identitas terkelola menggunakan Azure Resource Management, lihat Koneksi Layanan Azure Resource Manager (ARM).

   

3. Isi detail yang diperlukan, pilih Verifikasi, lalu pilih Simpan.

Konfigurasi Yaml Pipeline

Tugas dapat dikonfigurasi baik melalui Azure DevOps Web UI dan melalui kode Yaml dalam skema alur.

Penggunaan sampel perintah admin

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

Penggunaan sampel kueri

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