sql_request 外掛程式

發行項
01/23/2024

外掛程式sql_request會將 SQL 查詢傳送至 SQL Server 網路端點，並傳回結果。如果 SQL 傳回多個數據列集，則只會使用第一個數據列集。使用 evaluate 運算子叫用外掛程式。

語法

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

參數

名稱	類型	必要	Description
ConnectionString	`string`	✔️	指向 SQL Server 網路端點的連接字串。請參閱有效的驗證方法以及如何指定網路端點。
SqlQuery	`string`	✔️	要針對 SQL 端點執行的查詢。查詢必須傳回一或多個數據列集，但只有第一個數據列集可供 Kusto 查詢的其餘部分使用。
SqlParameters	`dynamic`		要隨著查詢一起做為參數傳遞之索引鍵/值組的屬性包。
選項	`dynamic`		索引鍵/值組的屬性包，可傳遞更進階的設定以及查詢。目前，只能`token`設定為傳遞呼叫端提供的 Microsoft Entra 存取令牌，以轉送至 SQL 端點以進行驗證。
OutputSchema	`string`		外掛程式輸出預期 `sql_request` 數據行的名稱和類型。使用下列語法： `(`ColumnName`:`ColumnType [`,` ...] `)`。

注意

強烈建議您指定 OutputSchema ，因為它允許外掛程式用於可能不需使用外掛程式的案例，例如跨叢集查詢。 OutputSchema 也可以啟用多個查詢優化。
如果 SQL 網路端點所傳回之第一個數據列集的運行時間架構不符合 OutputSchema 架構，就會引發錯誤。

驗證與授權

sql_request外掛程式支援下列三種向 SQL Server 端點驗證的方法。

驗證方法	Syntax	方式	Description
Microsoft Entra整合	`Authentication="Active Directory Integrated"`	將新增至 ConnectionString 參數。	這是慣用的驗證方法。使用者或應用程式會透過叢集 Microsoft Entra ID 進行驗證，並使用相同的令牌來存取 SQL Server 網路端點。主體必須具有 SQL 資源的適當許可權，才能執行要求的動作。例如，若要從資料庫讀取，主體需要數據表 SELECT 許可權，而且若要寫入現有數據表，主體需要 UPDATE 和 INSERT 許可權。若要寫入新的數據表，也需要 CREATE 許可權。
使用者名稱和密碼	`User ID=...; Password=...;`	將新增至 ConnectionString 參數。	可能的話，請避免這個方法，因為它可能較不安全。
Microsoft Entra 存取令牌	`dynamic({'token': h"eyJ0..."})`	在 Options 參數中新增。	存取令牌會在外掛程式的Options自變數中當做`token`屬性傳遞。

注意

包含機密資訊的連接字串和查詢，以及應受到防護的資訊，都應該經過模糊處理，避免受到任何的 Kusto 追蹤。如需詳細資訊，請參閱混淆的字串常值。

範例

使用 Microsoft Entra整合式驗證傳送 SQL 查詢

下列範例會將 SQL 查詢傳送至 Azure SQL DB 資料庫。查詢會從 [dbo].[Table] 擷取所有記錄，然後在 Kusto 端處理結果。驗證會重複使用呼叫使用者的 Microsoft Entra 令牌。

注意

此範例不應視為資料篩選或投影方式的建議。 SQL 查詢應該建構為盡可能傳回最小的數據集。

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

使用使用者名稱/密碼驗證傳送 SQL 查詢

下列範例與上一個範例相同，但 SQL 驗證會以使用者名稱和密碼執行。為了機密性，我們此處會使用模糊的字串。

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

使用 Microsoft Entra 存取令牌傳送 SQL 查詢

下列範例會將 SQL 查詢傳送至從擷取所有記錄[dbo].[Table]的 Azure SQL 資料庫，同時附加另一個datetime數據行，然後在 Kusto 端處理結果。其會指定要在 SQL 查詢中使用的 SQL 參數 (@param0)。

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

傳送不含查詢定義輸出架構的 SQL 查詢

下列範例會將 SQL 查詢傳送至沒有輸出架構的 Azure SQL 資料庫。除非架構未知，否則不建議這麼做，因為它可能會影響查詢的效能

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

加密和伺服器驗證

基於安全性考慮，連接到 SQL Server 網路端點時會強制執行下列連接屬性。

Encrypt 會無條件設定為 true。
TrustServerCertificate 會無條件設定為 false。

因此，必須使用有效的 SSL/TLS 伺服器憑證來設定 SQL Server。

指定網路端點

必須將 SQL 的網路端點指定為連接字串的一部分。適當的語法為：

Server=tcp:FQDN [,Port]

其中：

FQDN 是端點的完整網域名稱。
Port 是端點的 TCP 通訊埠。預設會採用 1433。

注意

不支援其他指定網路端點的形式。例如，即使在以程式設計方式使用 SQL 用戶端程式庫時，仍無法省略前置詞 tcp:。

Azure 監視器不支援這項功能