Plug-In „sql_request“

Das sql_request Plug-In sendet eine SQL-Abfrage an einen SQL Server Netzwerkendpunkt und gibt die Ergebnisse zurück. Wenn mehr als ein Rowset von SQL zurückgegeben wird, wird nur das erste verwendet. Das Plug-In wird mit dem evaluate Operator aufgerufen.

Syntax

evaluatesql_request(Connectionstring,SqlQuery [,SqlParameters [,Optionen]] ) [:OutputSchema]

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Typ	Erforderlich	BESCHREIBUNG
ConnectionString	string	✔️	Die Verbindungszeichenfolge, die auf den SQL Server Netzwerkendpunkt zeigt. Weitere Informationen finden Sie unter gültige Authentifizierungsmethoden und angeben des Netzwerkendpunkts.
SqlQuery	string	✔️	Die Abfrage, die für den SQL-Endpunkt ausgeführt werden soll. Die Abfrage muss einen oder mehrere Zeilensätze zurückgeben, aber nur der erste wird für den Rest der Kusto-Abfrage verfügbar gemacht.
SqlParameters	dynamic		Ein Eigenschaftenbehälter mit Schlüssel-Wert-Paaren, die zusammen mit der Abfrage als Parameter übergeben werden sollen.
Optionen	dynamic		Ein Eigenschaftenbehälter mit Schlüssel-Wert-Paaren, um erweiterte Einstellungen zusammen mit der Abfrage zu übergeben. Derzeit kann nur token so festgelegt werden, dass ein vom Aufrufer bereitgestelltes Microsoft Entra Zugriffstoken übergeben wird, das zur Authentifizierung an den SQL-Endpunkt weitergeleitet wird.
OutputSchema	string		Die Namen und Typen für die erwarteten Spalten der sql_request Plug-In-Ausgabe. Verwenden Sie die folgende Syntax: (ColumnName:ColumnType [, ...] ).

Hinweis

• Die Angabe des OutputSchemas wird dringend empfohlen, da das Plug-In in Szenarien verwendet werden kann, die andernfalls ohne es möglicherweise nicht funktionieren, z. B. bei einer clusterübergreifenden Abfrage. Das OutputSchema kann auch mehrere Abfrageoptimierungen aktivieren.
• Ein Fehler wird ausgelöst, wenn das Laufzeitschema des ersten Zeilensatzes, der vom SQL-Netzwerkendpunkt zurückgegeben wird, nicht mit dem OutputSchema-Schema übereinstimmt.

Authentifizierung und Autorisierung

Das sql_request-Plug-In unterstützt die folgenden drei Methoden der Authentifizierung beim SQL Server-Endpunkt.

Authentifizierungsmethode	Syntax	Wie?	BESCHREIBUNG
Microsoft Entra integriert	Authentication="Active Directory Integrated"	Fügen Sie dem ConnectionString-Parameter hinzu.	Dies ist die bevorzugte Authentifizierungsmethode. Der Benutzer oder die Anwendung authentifiziert sich über Microsoft Entra ID bei Ihrem Cluster, und dasselbe Token wird für den Zugriff auf den SQL Server Netzwerkendpunkt verwendet. Der Prinzipal muss über die entsprechenden Berechtigungen für die SQL-Ressource verfügen, um die angeforderte Aktion ausführen zu können. Um beispielsweise aus der Datenbank zu lesen, benötigt der Prinzipal select-Tabellenberechtigungen, und zum Schreiben in eine vorhandene Tabelle benötigt der Prinzipal die Berechtigungen UPDATE und INSERT. Zum Schreiben in eine neue Tabelle sind auch CREATE-Berechtigungen erforderlich.
Benutzername und Kennwort	User ID=...; Password=...;	Fügen Sie dem ConnectionString-Parameter hinzu.	Vermeiden Sie diese Methode nach Möglichkeit, da sie möglicherweise weniger sicher ist.
Microsoft Entra Zugriffstoken	dynamic({'token': h"eyJ0..."})	Fügen Sie den Options-Parameter hinzu.	Das Zugriffstoken wird als token Eigenschaft im Options-Argument des Plug-Ins übergeben.

Hinweis

Verbindungszeichenfolgen und Abfragen, die vertrauliche Informationen oder Informationen enthalten, die geschützt werden sollen, sollten verschleiert werden, um in jeder Kusto-Ablaufverfolgung ausgelassen zu werden. Weitere Informationen finden Sie unter Verschleierte Zeichenfolgenliterale.

Beispiele

Senden einer SQL-Abfrage mithilfe Microsoft Entra integrierten Authentifizierung

Im folgenden Beispiel wird eine SQL-Abfrage an eine Azure SQL DB-Datenbank gesendet. Es ruft alle Datensätze von ab [dbo].[Table]und verarbeitet dann die Ergebnisse auf der Kusto-Seite. Bei der Authentifizierung wird das Microsoft Entra token des aufrufenden Benutzers wiederverwendet.

Hinweis

Dieses Beispiel sollte nicht als Empfehlung zum Filtern oder Projektieren von Daten auf diese Weise betrachtet werden. SQL-Abfragen sollten so erstellt werden, dass sie das kleinste mögliche Dataset zurückgeben.

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

Senden einer SQL-Abfrage mithilfe der Benutzernamen-/Kennwortauthentifizierung

Das folgende Beispiel ist identisch mit dem vorherigen Beispiel, mit der Ausnahme, dass die SQL-Authentifizierung durch Benutzername/Kennwort erfolgt. Aus Gründen der Vertraulichkeit verwenden wir hier verschleierte Zeichenfolgen.

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

Senden einer SQL-Abfrage mithilfe eines Microsoft Entra-Zugriffstokens

Im folgenden Beispiel wird eine SQL-Abfrage an eine Azure SQL Datenbank gesendet, die alle Datensätze von [dbo].[Table]abruft, während eine weitere datetime Spalte angefügt wird, und verarbeitet dann die Ergebnisse auf der Kusto-Seite. Er gibt einen SQL-Parameter (@param0) an, der in der SQL-Abfrage verwendet werden soll.

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

Senden einer SQL-Abfrage ohne ein abfragedefiniertes Ausgabeschema

Im folgenden Beispiel wird eine SQL-Abfrage ohne Ausgabeschema an eine Azure SQL Datenbank gesendet. Dies wird nur empfohlen, wenn das Schema unbekannt ist, da es sich möglicherweise auf die Leistung der Abfrage auswirken kann.

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

Verschlüsselung und Servervalidierung

Die folgenden Verbindungseigenschaften werden aus Sicherheitsgründen erzwungen, wenn sie eine Verbindung mit einem SQL Server Netzwerkendpunkt herstellen.

• Encrypt ist auf true bedingungslos festgelegt.
• TrustServerCertificate ist auf false bedingungslos festgelegt.

Daher muss die SQL Server mit einem gültigen SSL/TLS-Serverzertifikat konfiguriert werden.

Angeben des Netzwerkendpunkts

Die Angabe des SQL-Netzwerkendpunkts als Teil der Verbindungszeichenfolge ist obligatorisch. Die erforderliche Syntax lautet:

Server=tcp:FQDN [,Port]

Hierbei gilt:

• FQDN ist der vollqualifizierte Domänenname des Endpunkts.
• Port ist der TCP-Port des Endpunkts. Standardmäßig wird 1433 verwendet.

Hinweis

Andere Formen der Angabe des Netzwerkendpunkts werden nicht unterstützt. Beispielsweise kann das Präfix tcp: nicht weggelassen werden, obwohl dies bei programmgesteuerter Verwendung der SQL-Clientbibliotheken möglich ist.

Diese Funktion wird in Azure Monitor nicht unterstützt.