sql_request プラグイン

sql_request プラグインは、SQL Server ネットワーク エンドポイントに SQL クエリを送信し、結果を返します。 SQL によって複数の行セットが返される場合は、最初のもののみが使用されます。 このプラグインは、evaluate演算子*を使用して呼び出し*ます。

構文

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

構文規則について詳しく知る。

パラメーター

名前	型	必須	説明
ConnectionString	string	✔️	SQL Server ネットワーク エンドポイントを指す接続文字列。 「認証の有効な方法」と「ネットワーク エンドポイント」を指定する方法を参照してください。
SqlQuery	string	✔️	SQL エンドポイントに対して実行されるクエリ。 クエリは 1 つ以上の行セットを返す必要がありますが、最初の行セットのみが Kusto クエリの残りの部分で使用できるようになります。
SqlParameters	dynamic		クエリと共にパラメーターとして渡すキーと値のペアのプロパティ バッグ。
[オプション]	dynamic		クエリと共により高度な設定を渡すキーと値のペアのプロパティ バッグ。 現時点では、認証のために SQL エンドポイントに転送される呼び出し元が提供Microsoft Entraアクセス トークンを渡す場合にのみtoken設定できます。
OutputSchema	string		sql_request プラグイン出力の予想される列の名前と型。 ColumnName:ColumnType [, ...] )の構文(を使用します。

Note

• OutputSchema を指定することを強くお勧めします。これにより、クラスター間クエリなど、それ以外の場合は機能しない可能性があるシナリオでプラグインを使用できます。 OutputSchema では、複数のクエリの最適化を有効にすることもできます。
• SQL ネットワーク エンドポイントによって返される最初の行セットの実行時スキーマが OutputSchema スキーマと一致しない場合、エラーが発生します。

認証と承認

sql_request プラグインでは、SQL Server エンドポイントに対する次の 3 つの認証方法がサポートされています。

認証方法	構文	どのように	説明
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 トレースから除外されるように難読化される必要があります。 詳細については、「難読化文字列リテラル」を参照してください。

例

統合認証を使用して SQL クエリMicrosoft Entra送信する

次の例では、Azure SQL DB データベースに SQL クエリを送信します。 [dbo].[Table] からすべてのレコードを取得し、Kusto 側の結果を処理します。 認証は、呼び出し元のユーザーのMicrosoft Entra トークンを再利用します。

Note

この例は、この方法でデータをフィルター処理またはプロジェクトするための推奨事項として使用できません。 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 クエリを送信する

次の例では、 からすべてのレコード[dbo].[Table]を取得する sql クエリを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 が想定されます。

Note

ネットワーク エンドポイントを指定するその他の形式はサポートされていません。 たとえば、プログラムで SQL クライアント ライブラリを使用して省略できたとしても、プレフィックス tcp: を省略することはできません。

この機能は、Azure Monitor ではサポートされていません。