Bagikan melalui

sql_request plugin

  • Artikel

Berlaku untuk: ✅Microsoft Fabric✅Azure Data Explorer

Plugin sql_request mengirimkan kueri SQL ke titik akhir jaringan Azure SQL Server dan mengembalikan hasilnya. 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] ,

Pelajari selengkapnya tentang konvensi sintaksis.

Parameter

Nama Tipe Wajib Deskripsi
ConnectionString string ✔️ string koneksi yang menunjuk pada titik akhir jaringan SQL Server. Lihat metode autentikasi yang valid dan cara menentukan titik akhir jaringan.
SqlQuery string ✔️ Kueri yang akan dijalankan terhadap titik akhir SQL. Kueri harus mengembalikan satu atau beberapa kumpulan baris, tetapi hanya yang pertama yang tersedia untuk kueri Kusto lainnya.
SqlParameters dynamic Tas properti pasangan kunci-nilai untuk diteruskan sebagai parameter bersama dengan kueri.
Opsi dynamic Tas properti pasangan kunci-nilai untuk melewati pengaturan yang lebih canggih bersama dengan kueri. Saat ini, hanya token dapat diatur, untuk meneruskan token akses Microsoft Entra yang disediakan pemanggil yang diteruskan ke titik akhir SQL untuk autentikasi.
OutputSchema string Nama dan jenis untuk kolom yang diharapkan dari output plugin sql_request. Gunakan sintaks berikut: ( ColumnName : ColumnType [, ...] . )

Catatan

  • Menentukan OutputSchema sangat disarankan, karena memungkinkan plugin digunakan dalam skenario yang mungkin tidak berfungsi tanpanya, seperti kueri lintas kluster. OutputSchema juga dapat mengaktifkan beberapa pengoptimalan kueri.
  • Kesalahan dimunculkan jika skema run-time dari kumpulan baris pertama yang dikembalikan oleh titik akhir jaringan SQL tidak cocok dengan skema OutputSchema .

Autentikasi dan otorisasi

Plugin sql_request mendukung tiga metode autentikasi berikut ke titik akhir SQL Server.

Metode autentikasi Sintaks Bagaimana Deskripsi
Microsoft Entra terintegrasi Authentication="Active Directory Integrated" Tambahkan ke parameter ConnectionString . Pengguna atau aplikasi mengautentikasi melalui ID Microsoft Entra ke kluster Anda, dan token yang sama digunakan untuk mengakses titik akhir jaringan SQL Server.
Prinsipal harus memiliki izin yang sesuai pada sumber daya SQL untuk melakukan tindakan yang diminta. Misalnya, untuk membaca dari database, prinsipal memerlukan izin SELECT tabel, dan untuk menulis ke tabel yang sudah ada, prinsipal memerlukan izin PERBARUI dan SISIPKAN. Untuk menulis ke tabel baru, izin CREATE juga diperlukan.
Identitas terkelola Authentication="Active Directory Managed Identity";User Id={object_id} Tambahkan ke parameter ConnectionString . Permintaan dijalankan atas nama identitas terkelola. Identitas terkelola harus memiliki izin yang sesuai pada sumber daya SQL untuk melakukan tindakan yang diminta.
Untuk mengaktifkan autentikasi identitas terkelola, Anda harus menambahkan identitas terkelola ke kluster Anda dan mengubah kebijakan identitas terkelola. Untuk informasi selengkapnya, lihat Kebijakan Identitas Terkelola.
Nama pengguna dan kata sandi User ID=...; Password=...; Tambahkan ke parameter ConnectionString . Jika memungkinkan, hindari metode ini karena mungkin kurang aman.
Token akses Microsoft Entra dynamic({'token': h"eyJ0..."}) Tambahkan di parameter Opsi . Token akses diteruskan sebagai token properti dalam argumen Opsi plugin.

Catatan

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.

Contoh

Mengirim kueri SQL menggunakan autentikasi terintegrasi Microsoft Entra

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 Microsoft Entra pengguna panggilan.

Catatan

Contoh ini tidak boleh diambil sebagai rekomendasi untuk memfilter atau memproyeksikan data dengan cara ini. Kueri SQL harus dibangun untuk mengembalikan himpunan data sekecil mungkin.

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

Mengirim kueri SQL menggunakan token akses Microsoft Entra

Contoh berikut mengirimkan kueri SQL ke database Azure SQL yang mengambil semua rekaman dari [dbo].[Table], sambil menambahkan kolom lain datetime , 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)})) : (Id:long, Name:string, dt: datetime)
| where Id > 0
| project Name

Mengirim kueri SQL tanpa skema output yang ditentukan kueri

Contoh berikut mengirimkan kueri SQL ke database Azure SQL tanpa skema output. Ini tidak disarankan kecuali skema tidak diketahui, karena dapat memengaruhi performa kueri

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

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]

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.