sql_request 外掛程式

發行項
10/15/2024

適用於： ✅Microsoft網狀架構✅Azure 數據總管

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

語法

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

深入瞭解語法慣例。

參數

姓名	類型	必要	描述
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 端點驗證。

驗證方法	語法	方式	描述
Microsoft Entra 整合式	`Authentication="Active Directory Integrated"`	將新增至 ConnectionString 參數。	使用者或應用程式會透過 Microsoft Entra ID 向叢集進行驗證，並使用相同的令牌來存取 SQL Server 網路端點。主體必須具有 SQL 資源的適當許可權，才能執行要求的動作。例如，若要從資料庫讀取，主體需要數據表 SELECT 許可權，以及寫入主體需要 UPDATE 和 INSERT 許可權的現有數據表。若要寫入新的數據表，也需要 CREATE 許可權。
受控識別	`Authentication="Active Directory Managed Identity";User Id={object_id}`	將新增至 ConnectionString 參數。	要求會代表受控識別執行。受控識別必須具有 SQL 資源的適當許可權，才能執行要求的動作。若要啟用受控識別驗證，您必須將受控識別新增至叢集，並變更受控識別原則。如需詳細資訊，請參閱受控識別原則。
使用者名稱與密碼	`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 。

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

指定網路端點

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

Server= tcp: FQDN [, 連接埠]

其中：

FQDN 是端點的完整功能變數名稱。
埠是連接點的 TCP 連接埠。預設會採用 1433。

注意

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

共用方式為