sql_request plugin

  • Artikel
  • 4 menit untuk membaca

Plugin sql_request akan mengirimkan kueri SQL ke titik akhir jaringan SQL Server serta mengembalikan kumpulan baris pertama dalam hasil. Jika terdapat lebih dari satu set baris yang ditampilkan oleh SQL, hanya yang pertama yang digunakan. Plugin dipanggil dengan operator evaluate.

Sintaks

evaluatesql_request(ConnectionString,SqlQuery [,SqlParameters [,Options]] ) [:OutputSchema]

Argumen

Nama Jenis Diperlukan Deskripsi
ConnectionString string ✓ Menunjukkan string koneksi yang mengarah ke titik akhir jaringan SQL Server. Lihat metode autentikasi yang valid dan cara menentukan titik akhir jaringan.
SqlQuery string ✓ Menunjukkan kueri yang akan dijalankan terhadap titik akhir SQL. Harus mengembalikan satu atau beberapa kumpulan baris, tetapi hanya yang pertama yang tersedia untuk sisa kueri Kusto.
SqlParameters dinamis Menahan pasangan nilai kunci untuk diteruskan sebagai parameter bersama dengan kueri.
Opsi dinamis Menyimpan pengaturan yang lebih canggih sebagai pasangan kunci-nilai. Saat ini, hanya token yang dapat diatur, untuk meneruskan token akses Azure AD yang disediakan pemanggil yang diteruskan ke titik akhir SQL untuk autentikasi.
OutputSchema Nama dan jenis untuk kolom yang diharapkan dari output plugin sql_request.

Argumen OutputSchema opsional memiliki sintaksis berikut:

(ColumnName:ColumnType [, ...] )

Menentukan argumen ini akan memungkinkan plugin digunakan dalam skenario (seperti kueri lintas kluster) yang sebaliknya akan mencegahnya berjalan, serta memungkinkan beberapa pengoptimalan kueri. Dengan demikian, disarankan untuk selalu menentukannya. Kesalahan muncul jika skema run-time dari set baris pertama yang ditampilkan oleh titik akhir jaringan SQL tidak sesuai dengan skema OutputSchema.

Contoh

Mengirim kueri SQL menggunakan autentikasi terintegrasi Azure AD

Contoh berikut mengirimkan kueri SQL ke database Azure SQL DB. Ini mengambil semua rekaman dari [dbo].[Table], lalu memproses hasilnya pada sisi Kusto. Autentikasi menggunakan kembali token Azure AD pengguna yang memanggil.

Catatan

Contoh ini tidak boleh diambil sebagai rekomendasi untuk memfilter atau memproyeksikan data dengan cara ini. SQL kueri harus dibangun untuk mengembalikan himpunan data sekecil mungkin, karena pengoptimal Kusto tidak berusaha mengoptimalkan kueri antara Kusto dan SQL.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select * from [dbo].[Table]')
| where Id > 0
| project Name

Mengirim kueri SQL menggunakan autentikasi Nama Pengguna/Kata Sandi

Contoh berikut identik dengan yang sebelumnya, kecuali bahwa autentikasi SQL dilakukan dengan nama pengguna /kata sandi. Untuk kerahasiaan, kami menggunakan string yang disamarkan di sini.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Initial Catalog=Fabrikam;'
    h'User ID=USERNAME;'
    h'Password=PASSWORD;',
  'select * from [dbo].[Table]')
| where Id > 0
| project Name

Mengirim kueri SQL menggunakan token akses Azure AD

Contoh berikut mengirimkan kueri SQL ke database Azure SQL DB yang mengambil semua rekaman dari [dbo].[Table], sambil menambahkan kolom datetime lain, lalu memproses hasilnya di sisi Kusto. Ini menentukan parameter SQL (@param0) yang akan digunakan dalam kueri SQL.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select *, @param0 as dt from [dbo].[Table]',
  dynamic({'param0': datetime(2020-01-01 16:47:26.7423305)}))
| where Id > 0
| project Name

Mengirim kueri SQL dengan skema output yang ditentukan kueri

Contoh berikut mengirimkan kueri SQL ke database Azure SQL DB yang mengambil semua rekaman dari [dbo].[Table], sambil hanya memilih kolom tertentu. Conoth ini menggunakan definisi skema eksplisit yang memungkinkan berbagai pengoptimalan dievaluasi sebelum kueri yang sebenarnya terhadap SQL dijalankan.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select Id, Name') : (Id:long, Name:string)
| where Id > 0
| project Name

Autentikasi

Plugin sql_request mendukung tiga metode autentikasi ke titik akhir SQL Server:

Autentikasi terintegrasi Azure AD

Authentication="Active Directory Integrated"

Autentikasi terintegrasi Azure AD adalah metode yang diutamakan. Metode ini membuat pengguna atau aplikasi mengautentikasi melalui Azure AD ke Kusto. Token yang sama kemudian digunakan untuk mengakses titik akhir jaringan SQL Server.

Autentikasi Nama Pengguna/Kata Sandi

User ID=...; Password=...;

Dukungan autentikasi nama pengguna dan kata sandi disediakan saat autentikasi terintegrasi Azure AD tidak dapat dilakukan. Hindari metode ini, jika memungkinkan, karena informasi rahasia dikirim melalui Kusto.

Token akses Azure AD

dynamic({'token': h"eyJ0..."})

Dengan metode autentikasi token akses Azure AD, pemanggil menghasilkan token akses, yang diteruskan oleh Kusto ke titik akhir SQL. String koneksi SQL tidak boleh menyertakan informasi autentikasi seperti Authentication, User ID, atau Password. Sebaliknya, token akses diteruskan sebagai properti token dalam argumen Options plugin sql_request.

Peringatan

String koneksi dan kueri yang menyertakan informasi rahasia atau informasi yang harus dijaga harus dikaburkan agar tidak terlihat dari pelacakan Kusto. Untuk informasi selengkapnya, lihat harfiah string yang disamarkan.

Enkripsi dan validasi server

Properti koneksi berikut dipaksakan saat menyambungkan ke titik akhir jaringan SQL Server, karena alasan keamanan.

  • Encrypt diatur ke true tanpa syarat.
  • TrustServerCertificate diatur ke false tanpa syarat.

Akibatnya, SQL Server harus dikonfigurasi dengan sertifikat server SSL/TLS yang valid.

Menentukan titik akhir jaringan

Menentukan titik akhir jaringan SQL sebagai bagian dari string koneksi adalah wajib. Sintaksis yang sesuai adalah:

Server=tcp:FQDN [,Port]

Di mana:

  • FQDN adalah nama domain yang sepenuhnya memenuhi syarat dari titik akhir.
  • Port adalah port TCP dari titik akhir. Secara default, 1433 diasumsikan.

Catatan

Cara lain untuk menentukan titik akhir jaringan tidak didukung. Prefiks tcp: tidak dapat dihilangkan meskipun dapat dilakukan ketika menggunakan pustaka klien SQL secara terprogram.

Kemampuan ini tidak didukung di Azure Monitor