Plug-In „sql_request“

Gilt für: ✅Microsoft Fabric✅Azure Data Explorer

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

Syntax

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

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Type	Erforderlich	Beschreibung
ConnectionString	string	✔️	Die Verbindungszeichenfolge, die auf den SQL Server-Netzwerkendpunkt verweist. Sehen Sie sich gültige Methoden der Authentifizierung und die Angabe des Netzwerkendpunkts an.
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 die erste wird für den Rest der Kusto-Abfrage verfügbar gemacht.
SqlParameters	dynamic		Ein Eigenschaftenbehälter von 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 festgelegt werden, um ein vom Aufrufer bereitgestelltes Microsoft Entra-Zugriffstoken zu übergeben, 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 OutputSchema-Schemas wird dringend empfohlen, da das Plug-In in Szenarien verwendet werden kann, die andernfalls nicht funktionieren, z. B. eine clusterübergreifende Abfrage. Das OutputSchema kann auch mehrere Abfrageoptimierungen aktivieren.
• Ein Fehler wird ausgelöst, wenn das Laufzeitschema des vom SQL-Netzwerkendpunkt zurückgegebenen ersten Zeilensatzes nicht mit dem OutputSchema-Schema übereinstimmt.

Authentifizierung und Autorisierung

Das sql_request-Plug-In unterstützt die folgenden drei Authentifizierungsmethoden für den SQL Server-Endpunkt.

Authentifizierungsmethode	Syntax	Wie?	Beschreibung
Microsoft Entra integriert	Authentication="Active Directory Integrated"	Zum Parameter "ConnectionString" hinzufügen.	Der Benutzer oder die Anwendung authentifiziert sich über die Microsoft Entra-ID für Ihren 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 auszuführen. Um z. B. aus der Datenbank zu lesen, benötigt die Prinzipaltabelle SELECT-Berechtigungen, und um in eine vorhandene Tabelle zu schreiben, benötigt der Prinzipal UPDATE- und INSERT-Berechtigungen. Um in eine neue Tabelle zu schreiben, sind auch CREATE-Berechtigungen erforderlich.
Verwaltete Identität	Authentication="Active Directory Managed Identity";User Id={object_id}	Zum Parameter "ConnectionString" hinzufügen.	Die Anforderung wird im Auftrag einer verwalteten Identität ausgeführt. Die verwaltete Identität muss über die entsprechenden Berechtigungen für die SQL-Ressource verfügen, um die angeforderte Aktion auszuführen. Um die verwaltete Identitätsauthentifizierung zu aktivieren, müssen Sie die verwaltete Identität zu Ihrem Cluster hinzufügen und die Richtlinie für verwaltete Identitäten ändern. Weitere Informationen finden Sie unter Verwaltete Identitätsrichtlinie.
Benutzername und Kennwort	User ID=...; Password=...;	Zum Parameter "ConnectionString" hinzufügen.	Vermeiden Sie nach Möglichkeit diese Methode, da sie möglicherweise weniger sicher ist.
Microsoft Entra-Zugriffstoken	dynamic({'token': h"eyJ0..."})	Fügen Sie den Parameter "Options" 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 von jeder Kusto-Ablaufverfolgung weggelassen zu werden. Weitere Informationen finden Sie unter verschleierten Zeichenfolgenliteralen.

Beispiele

Senden einer SQL-Abfrage mithilfe der integrierten Microsoft Entra-Authentifizierung

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

Hinweis

Dieses Beispiel sollte nicht als Empfehlung zum Filtern oder Projektdaten auf diese Weise verwendet werden. SQL-Abfragen sollten erstellt werden, um möglichst kleine Datasets zurückzugeben.

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 Authentifizierung mit Benutzername/Kennwort

Das folgende Beispiel ist mit dem vorherigen identisch, mit der Ausnahme, dass die SQL-Authentifizierung durch Benutzername/Kennwort erfolgt. Zur 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, aus [dbo].[Table]der alle Datensätze abgerufen werden, während sie eine andere datetime Spalte anfügen und dann die Ergebnisse auf der Kusto-Seite verarbeiten. 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 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 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 Serverüberprüfung

Die folgenden Verbindungseigenschaften werden aus Sicherheitsgründen beim Herstellen einer Verbindung mit einem SQL Server-Netzwerkendpunkt erzwungen.

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

Daher muss der 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 der programmgesteuerten Verwendung der SQL-Clientbibliotheken möglich ist.