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 Pipeline adalah tugas Azure Pipelines yang memungkinkan Anda membuat pipeline rilis dan menyebarkan perubahan database ke database Azure Data Explorer Anda. Ini tersedia secara gratis di Visual Studio Marketplace. Ekstensi ini mencakup tugas dasar berikut:

• Perintah Azure Data Explorer - Menjalankan perintah admin terhadap kluster Azure Data Explorer

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

• Gerbang kueri server Azure Data Explorer - Tugas tanpa agen untuk mengatur rilis berdasarkan hasil kueri

  

Dokumen ini menjelaskan contoh sederhana penggunaan tugas Azure Data Explorer - Alat Alur untuk menyebarkan perubahan skema 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 agar mendapatkan beberapa file perintah dari folder agen lokal (sumber build atau artefak rilis). Opsi baris tunggal mendukung beberapa file dengan satu perintah per file.

  

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

  

  Petunjuk

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

Membuat jalur rilis

1. Masuk ke Organisasi Azure DevOps Anda.

2. Pilih Pipa>Rilis dari menu sebelah kiri, lalu pilih Pipa baru.

   

3. Jendela Pipeline rilis baru terbuka. Pada tab Alur, di panel Pilih templat, pilih Pekerjaan Kosong.

   

4. Pilih tombol Tahap . Di panel Tahap , tambahkan Nama tahap, lalu 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. Masukkan Nama dan Nilai titik akhir, lalu 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 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 jalurnya dengan */<FOLDER>/*.csl di mana <FOLDER> adalah folder yang relevan untuk tugas tersebut.

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

      • Gunakan Endpoint 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
        Cluster URL	Nilai dapat ditemukan di bagian gambaran umum Kluster Azure Data Explorer Anda di portal Azure
        Service Principal Id	Masukkan ID Aplikasi Microsoft Entra (dibuat sebagai prasyarat)
        Kunci Aplikasi Service Principal	Masukkan Kunci Aplikasi Microsoft Entra (dibuat sebagai prasyarat)
        ID penyewa Microsoft Entra	Masukkan tenant Microsoft Entra Anda (seperti microsoft.com atau contoso.com)

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

      

   4. Jika perintah admin Anda adalah operasi asinkron yang berjalan lama, pilih kotak centang Tunggu hingga selesai perintah Admin Asinkron yang lama. Saat diaktifkan, tugas akan memantau status operasi menggunakan .show operations hingga perintah selesai.

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, Kueri kluster.
   • Jenis: Pilih Inline.
   • Kueri: Masukkan kueri yang ingin Anda jalankan.
   • Endpoint URL: Tentukan variabel yang EndPoint URL dibuat sebelumnya.
   • Gunakan Endpoint 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 sediakan kriteria yang Anda perlukan.

     

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

3. Pilih Kusto Query Server Gate lalu pilih Server Gate Test.

   

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 versi rilis

1. Pilih + Rilis>Buat rilis untuk memulai 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. Ini lebih aman dan lebih mudah dikelola.

Catatan

URL kluster Kusto Fabric tidak didukung untuk Federasi Identitas Beban Kerja (WIF) dan autentikasi Identitas Terkelola.

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

Catatan

Dimulai dengan ekstensi versi 4.0.x, Azure Data Explorer Service Endpoint mendukung autentikasi Federasi Identitas Workload (WIF) selain Autentikasi Prinsipal Layanan.

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

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

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

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

   

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

   • Penerbit: <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 spasi dalam nama koneksi layanan Anda, Anda dapat menggunakannya dengan spasi yang sama di bidang tersebut. 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 Pengaturan Proyek>Koneksi layanan>Koneksi layanan baru>Azure Resource Manager.

   

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

   

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

Konfigurasi alur YAML

Anda dapat mengonfigurasi tugas menggunakan UI web Azure DevOps atau kode YAML dalam skema alur.

Ekstensi ini menyediakan tiga tugas alur, semuanya dapat diakses melalui YAML:

• Perintah Azure Data Explorer (ADXAdminCommand@5) — Jalankan perintah admin/kontrol terhadap kluster ADX
• Kueri Azure Data Explorer — Jalankan kueri terhadap kluster ADX dan uraikan hasilnya
• Azure Data Explorer Query Server Gate — Tugas tanpa agen untuk mem-gate rilis bergantung pada hasil kueri

Petunjuk

Untuk keamanan yang ditingkatkan, gunakan Federasi Identitas Beban Kerja atau autentikasi Identitas Terkelola melalui koneksi layanan Azure Resource Manager alih-alih menyimpan kredensial langsung di alur Anda. Metode autentikasi tanpa kunci ini adalah praktik terbaik yang direkomendasikan.

Sampel perintah admin — perintah sebaris

Sampel berikut menjalankan perintah admin secara langsung menggunakan koneksi layanan Azure Resource Manager (ARM), yang mendukung Federasi Identitas Kerja (WIF) dan autentikasi Identitas Terkelola.

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

Sampel perintah admin — perintah berbasis file

Sampel berikut menjalankan perintah admin dari file yang cocok dengan pola glob, menggunakan autentikasi Pendaftaran Aplikasi 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

Anda juga dapat menggunakan **/*.kql sebagai pola glob tergantung pada konvensi penamaan file Anda.

Sampel perintah admin — Koneksi layanan Azure Resource Manager

Sampel berikut menggunakan koneksi layanan Azure Resource Manager, yang mendukung Federasi Identitas Beban Kerja (WIF) dan Identitas Terkelola untuk autentikasi tanpa kunci:

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

Parameter tugas

Tabel berikut ini menjelaskan parameter input kunci untuk tugas:ADXAdminCommand@5

Parameter	Deskripsi
clusterUri	URI dasar untuk kluster Kusto (misalnya, https://<ClusterName>.<Region>.kusto.windows.net)
databaseName	Nama database target
commandsSource	Sumber perintah: inline untuk perintah KQL sebaris, atau files untuk perintah berbasis file
inlineCommands	Perintah KQL inline untuk dijalankan (digunakan ketika commandsSource adalah inline)
commandFilesPattern	Pola glob untuk file skrip (digunakan saat commandsSource adalah files), misalnya **/*.csl atau **/*.kql
aadAppId	ID Aplikasi Microsoft Entra (Service Principal) untuk autentikasi AAD App
aadAppKey	Kunci/rahasia Aplikasi Microsoft Entra untuk autentikasi Aplikasi AAD
aadTenantId	ID penyewa Microsoft Entra untuk autentikasi Aplikasi AAD
azureSubscription	Nama koneksi layanan Azure Resource Manager untuk autentikasi berbasis ARM (mendukung WIF dan Identitas Terkelola)

Metode autentikasi

Ekstensi ini mendukung metode autentikasi berikut:

• Pendaftaran Aplikasi Azure Active Directory (AAD) — Gunakan aadAppId, aadAppKey, dan aadTenantId untuk mengautentikasi dengan Perwakilan Layanan. Simpan kredensial sebagai variabel alur yang aman.
• Autentikasi berbasis sertifikat — Gunakan sertifikat alih-alih kunci aplikasi untuk autentikasi Perwakilan Layanan. Simpan detail sertifikat sebagai variabel alur aman.
• Identitas Terkelola — Gunakan koneksi layanan Azure Resource Manager yang dikonfigurasi dengan Identitas Terkelola. Atur azureSubscription input ke nama koneksi layanan.
• Federasi Identitas Beban Kerja (WIF) — Gunakan koneksi layanan Azure Resource Manager dengan Federasi Identitas Beban Kerja (otomatis atau manual). Ini adalah pendekatan tanpa kunci yang direkomendasikan. Atur azureSubscription input ke nama koneksi layanan.

Catatan

Workload Identity Federation (WIF) adalah fitur baru yang ditambahkan ke ekstensi. Ini memungkinkan autentikasi tanpa rahasia dan merupakan pendekatan yang direkomendasikan untuk alur baru. Untuk instruksi penyiapan, lihat Menggunakan Kredensial Identitas Terfederasi atau Identitas Terkelola dalam koneksi layanan Azure Resource Manager (ARM).

Sampel kueri

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