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 Zeilenet 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 [,Optionen]] ): [,OutputSchema]

Argumente

Name type Erforderlich Beschreibung
Connectionstring Zeichenfolge Gibt die Verbindungszeichenfolge an, die auf den SQL Server Netzwerkendpunkt verweist. Lesen Sie gültige Methoden der Authentifizierung und wie Sie den Netzwerkendpunkt angeben.
SqlQuery Zeichenfolge Gibt die Abfrage an, die für den SQL Endpunkt ausgeführt werden soll. Muss eine oder mehrere Zeilensätze zurückgeben, aber nur für den Rest der Kusto-Abfrage wird nur der erste verfügbar gemacht.
SqlParameters dynamisch Enthält Schlüsselwertpaare, die zusammen mit der Abfrage als Parameter übergeben werden sollen.
Optionen dynamisch Enthält erweiterte Einstellungen als Schlüsselwertpaare. Derzeit kann nur token festgelegt werden, um ein vom Anrufer bereitgestelltes Azure AD-Zugriffstoken zu übergeben, das an den SQL Endpunkt für die Authentifizierung weitergeleitet wird.
OutputSchema Die Namen und Typen für die erwarteten Spalten der sql_request Plug-In-Ausgabe.

Das optionale OutputSchema-Argument weist die folgende Syntax auf:

(Columnname:ColumnType [, ...])

Wenn Sie dieses Argument angeben, kann das Plug-In in Szenarien (z. B. einer clusterübergreifenden Abfrage) verwendet werden, die sie andernfalls verhindern würde, dass es ausgeführt wird und mehrere Abfrageoptimierungen ermöglicht. Daher wird empfohlen, sie immer anzugeben. Ein Fehler wird ausgelöst, wenn das Laufzeitschema des ersten zeilenet, das vom SQL Netzwerkendpunkt zurückgegeben wird, nicht mit dem OutputSchema-Schema übereinstimmt.

Beispiele

Senden einer SQL Abfrage mithilfe der integrierten Azure AD-Authentifizierung

Im folgenden Beispiel wird eine SQL Abfrage an eine Azure SQL DB-Datenbank gesendet. Es ruft alle Datensätze von [dbo].[Table], und verarbeitet dann die Ergebnisse auf der Kusto Seite. Die Authentifizierung verwendet das Azure AD-Token des Anrufers.

Hinweis

Dieses Beispiel sollte nicht als Empfehlung zum Filtern oder Projektdaten auf diese Weise verwendet werden. SQL Abfragen sollten erstellt werden, um den kleinsten Datentyp zurückzugeben, da der Kusto-Optimierungsgeber nicht versucht, Abfragen zwischen Kusto und SQL zu optimieren.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select * from [dbo].[Table]')
| where Id > 0
| project Name

Senden einer SQL Abfrage mithilfe der Benutzernamen/Kennwortauthentifizierung

Das folgende Beispiel ist identisch mit dem vorherigen Beispiel, außer dass SQL Authentifizierung durch Benutzername/Kennwort ausgeführt wird. Für 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]')
| where Id > 0
| project Name

Senden einer SQL Abfrage mithilfe eines Azure AD-Zugriffstokens

Im folgenden Beispiel wird eine SQL Abfrage an eine Azure SQL DB-Datenbank gesendet, die alle Datensätze [dbo].[Table]abruft, während sie eine andere datetime Spalte anfügen und dann die Ergebnisse auf der Kusto Seite verarbeitet. Es 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)}))
| where Id > 0
| project Name

Senden einer SQL Abfrage mit einem abfragedefinitionen Ausgabeschema

Im folgenden Beispiel wird eine SQL Abfrage an eine Azure SQL DB-Datenbank gesendet, die alle Datensätze abruft[dbo].[Table], während sie nur bestimmte Spalten auswählen. Es verwendet explizite Schemadefinitionen, mit denen verschiedene Optimierungen ausgewertet werden können, bevor die tatsächliche Abfrage gegen SQL ausgeführt wird.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select Id, Name') : (Id:long, Name:string)
| where Id > 0
| project Name

Authentifizierung

Das sql_request-Plug-In unterstützt drei Methoden der Authentifizierung an den SQL Server Endpunkt:

Integrierte Azure AD-Authentifizierung

Authentication="Active Directory Integrated"

Azure AD-integrierte Authentifizierung ist die bevorzugte Methode. Diese Methode hat den Benutzer oder die Anwendung über Azure AD authentifiziert, um Kusto. Das gleiche Token wird dann verwendet, um auf den SQL Server Netzwerkendpunkt zuzugreifen.

Benutzername/Kennwortauthentifizierung

User ID=...; Password=...;

Die Unterstützung der Benutzernamen- und Kennwortauthentifizierung wird bereitgestellt, wenn die integrierte Azure AD-Authentifizierung nicht ausgeführt werden kann. Vermeiden Sie diese Methode, wenn möglich, da geheime Informationen über Kusto gesendet werden.

Azure AD-Zugriffstoken

dynamic({'token': h"eyJ0..."})

Mit der Azure AD-Zugriffstokenauthentifizierungsmethode generiert der Aufrufer das Zugriffstoken, das von Kusto an den SQL Endpunkt weitergeleitet wird. Die Verbindungszeichenfolge sollte keine Authentifizierungsinformationen wie Authentication, oder User IDPassword. Stattdessen wird das Zugriffstoken als token Eigenschaft im Options Argument des sql_request Plug-Ins übergeben.

Warnung

Verbindungszeichenfolgen und Abfragen, die vertrauliche Informationen oder Informationen enthalten, die geschützt werden sollen, sollten nicht von jeder Kusto Ablaufverfolgung entfernt werden. Weitere Informationen finden Sie unter obfuscated string literals.

Verschlüsselung und Serverüberprüfung

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

  • 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. Man kann beispielsweise das Präfix tcp: nicht auslassen, obwohl es möglich ist, dies bei der programmgesteuerten Verwendung der SQL Clientbibliotheken zu tun.

Diese Funktion wird in Azure Monitor nicht unterstützt.