次の方法で共有

sql_request プラグイン

  • [アーティクル]

適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー

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

構文

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

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

パラメーター

件名 タイプ Required 説明
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 権限も必要です。
マネージド ID Authentication="Active Directory Managed Identity";User Id={object_id} ConnectionString パラメーターに追加します。 要求はマネージド ID に代わって実行されます。 要求されたアクションを実行するには、マネージド ID に SQL リソースに対する適切なアクセス許可が必要です。
マネージド ID 認証を有効にするには、マネージド ID をクラスターに追加し、マネージド ID ポリシーを変更する必要があります。 詳細については、「 管理 ID ポリシー」を参照してください。
ユーザー名とパスワード User ID=...; Password=...; ConnectionString パラメーターに追加します。 可能な場合は、安全性が低い可能性があるため、この方法は避けてください。
Microsoft Entra アクセス トークン dynamic({'token': h"eyJ0..."}) Options パラメーターに追加します。 アクセス トークンは、プラグインの Options 引数でtokenプロパティとして渡されます。

Note

機密情報を含む接続文字列とクエリ、または保護されるべき情報は、すべての Kusto トレースから除外されるように難読化される必要があります。 詳細については、「難読化文字列リテラル」を参照してください。

例

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

次の例では、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 クエリを送信する

次の例では、別の datetime 列を追加しながら、[dbo].[Table]からすべてのレコードを取得する SQL クエリを Azure SQL データベースに送信し、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 クエリを送信する

次の例では、出力スキーマなしで AZURE 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]')
| where Id > 0
| project Name

暗号化とサーバー検証

セキュリティ上の理由により、SQL Server ネットワーク エンドポイントに接続するときは、次の接続プロパティが強制されます。

  • Encrypt は無条件に true 設定されます。
  • TrustServerCertificate は無条件に false 設定されます。

このため、SQL Server は、有効な SSL/TLS サーバー証明書を使用して構成することが必要になります。

ネットワーク エンドポイントを指定する

接続文字列の一部として SQL ネットワーク エンドポイントを指定することは必須です。 適切な構文は次のとおりです。

Server= tcp: FQDN [, Port]

ここで:

  • FQDN は、そのエンドポイントの完全修飾ドメイン名です。
  • Port は、そのエンドポイントの TCP ポートです。 既定では、1433 が想定されます。

Note

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