sql_request, plug-insql_request plugin

Le sql_request plug-in envoie une requête SQL à un point de terminaison de réseau SQL Server et retourne le premier ensemble de lignes dans les résultats.The sql_request plugin sends a SQL query to a SQL Server network endpoint and returns the first rowset in the results. La requête peut retourner plus d’un ensemble de lignes, mais seul le premier ensemble de lignes est rendu disponible pour le reste de la requête Kusto.The query may return more then one rowset, but only the first rowset is made available for the rest of the Kusto query.

SyntaxeSyntax

evaluate``sql_request ( ConnectionString , SqlQuery [ , SqlParameters [ , options ]])evaluate sql_request ( ConnectionString , SqlQuery [, SqlParameters [, Options ]] )

ArgumentsArguments

  • ConnectionString : string littéral indiquant la chaîne de connexion qui pointe vers le point de terminaison du réseau SQL Server.ConnectionString : A string literal indicating the connection string that points at the SQL Server network endpoint. Consultez méthodes d’authentification valides et comment spécifier le point de terminaison réseau.See valid methods of authentication and how to specify the network endpoint.

  • SqlQuery : string littéral indiquant la requête à exécuter sur le point de terminaison SQL.SqlQuery : A string literal indicating the query that is to be executed against the SQL endpoint. Doit retourner un ou plusieurs ensembles de lignes, mais seul le premier est rendu disponible pour le reste de la requête Kusto.Must return one or more rowsets, but only the first one is made available for the rest of the Kusto query.

  • SqlParameters : valeur constante de type dynamic qui contient des paires clé-valeur à passer comme paramètres avec la requête.SqlParameters : A constant value of type dynamic that holds key-value pairs to pass as parameters along with the query. facultatif.Optional.

  • Options : valeur constante de type dynamic qui contient des paramètres plus avancés en tant que paires clé-valeur.Options : A constant value of type dynamic that holds more advanced settings as key-value pairs. Actuellement, seul token peut être défini, pour transmettre un jeton d’accès Azure ad fourni par l’appelant, qui est transféré au point de terminaison SQL pour l’authentification.Currently, only token can be set, to pass a caller-provided Azure AD access token that is forwarded to the SQL endpoint for authentication. facultatif.Optional.

ExemplesExamples

L’exemple suivant envoie une requête SQL à une base de données Azure SQL DB.The following example sends a SQL query to an Azure SQL DB database. Elle récupère tous les enregistrements de [dbo].[Table] , puis traite les résultats du côté Kusto.It retrieves all records from [dbo].[Table], and then processes the results on the Kusto side. L’authentification réutilise le jeton de Azure AD de l’utilisateur appelant.Authentication reuses the calling user's Azure AD token.

Notes

Cet exemple ne doit pas être utilisé comme recommandation pour filtrer ou projeter des données de cette manière.This example should not be taken as a recommendation to filter or project data in this manner. Les requêtes SQL doivent être construites pour retourner le plus petit jeu de données possible, car l’optimiseur Kusto ne tente pas actuellement d’optimiser les requêtes entre Kusto et SQL.SQL queries should be constructed to return the smallest data set possible, Since the Kusto optimizer doesn't currently attempt to optimize queries between Kusto and SQL.

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

L’exemple suivant est identique au précédent, à ceci près que l’authentification SQL est effectuée par nom d’utilisateur/mot de passe.The following example is identical to the previous one, except that SQL authentication is done by username/password. Pour des fins de confidentialité, nous utilisons ici des chaînes masquées.For confidentiality, we use obfuscated strings here.

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

L’exemple suivant envoie une requête SQL à une base de données Azure SQL DB en extrayant tous les enregistrements de [dbo].[Table] , en ajoutant une autre datetime colonne, puis traite les résultats du côté Kusto.The following example sends a SQL query to an Azure SQL DB database retrieving all records from [dbo].[Table], while appending another datetime column, and then processes the results on the Kusto side. Elle spécifie un paramètre SQL ( @param0 ) à utiliser dans la requête SQL.It specifies a SQL parameter (@param0) to be used in the SQL query.

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

AuthentificationAuthentication

Le plug-in sql_request prend en charge trois méthodes d’authentification pour le point de terminaison de SQL Server :The sql_request plugin supports three methods of authentication to the SQL Server endpoint:

Authentification intégrée à l’Azure ADAzure AD-integrated authentication

Authentication="Active Directory Integrated"

L’authentification intégrée à l’Azure AD est la méthode recommandée.Azure AD-integrated authentication is the preferred method. Cette méthode permet à l’utilisateur ou à l’application de s’authentifier via Azure AD à Kusto.This method has the user or application authenticate via Azure AD to Kusto. Le même jeton est ensuite utilisé pour accéder au point de terminaison du réseau SQL Server.The same token is then used to access the SQL Server network endpoint.

Authentification par nom d’utilisateur/mot de passeUsername/Password authentication

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

La prise en charge de l’authentification par nom d’utilisateur et mot de passe est fournie lorsque l’authentification Azure AD intégrée ne peut pas être effectuée.Username and password authentication support is provided when Azure AD-integrated authentication can't be done. Évitez cette méthode, dans la mesure du possible, car les informations secrètes sont envoyées par le biais de Kusto.Avoid this method, when possible, as secret information is sent through Kusto.

Azure AD jeton d’accèsAzure AD access token

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

Avec la méthode d’authentification par jeton d’accès Azure AD, l’appelant génère le jeton d’accès, qui est transféré par Kusto au point de terminaison SQL.With the Azure AD access token authentication method, the caller generates the access token, which is forwarded by Kusto to the SQL endpoint. La chaîne de connexion ne doit pas inclure d’informations d’authentification telles que Authentication , User ID ou Password .The connection string shouldn't include authentication information like Authentication, User ID, or Password. Au lieu de cela, le jeton d’accès est transmis en tant que token propriété dans l' Options argument du plug-in sql_request.Instead, the access token is passed as token property in the Options argument of the sql_request plugin.

Avertissement

Les chaînes de connexion et les requêtes qui incluent des informations confidentielles ou des informations qui doivent être protégées doivent être obscurcies pour être omises de tout suivi Kusto.Connection strings and queries that include confidential information or information that should be guarded should be obfuscated to be omitted from any Kusto tracing. Pour plus d’informations, consultez littéraux de chaîne obscurcis.For more informations, see obfuscated string literals.

Chiffrement et validation du serveurEncryption and server validation

Les propriétés de connexion suivantes sont forcées lors de la connexion à un point de terminaison de réseau SQL Server, pour des raisons de sécurité.The following connection properties are forced when connecting to a SQL Server network endpoint, for security reasons.

  • Encrypt a la valeur sans true condition.Encrypt is set to true unconditionally.
  • TrustServerCertificate a la valeur sans false condition.TrustServerCertificate is set to false unconditionally.

Par conséquent, le SQL Server doit être configuré avec un certificat de serveur SSL/TLS valide.As a result, the SQL Server must be configured with a valid SSL/TLS server certificate.

Spécifier le point de terminaison réseauSpecify the network endpoint

La spécification du point de terminaison de réseau SQL dans le cadre de la chaîne de connexion est obligatoire.Specifying the SQL network endpoint as part of the connection string is mandatory. La syntaxe appropriée est :The appropriate syntax is:

Server``= tcp: Nom de domaine complet [ , port ]Server = tcp: FQDN [, Port ]

Où :Where:

  • FQDN est le nom de domaine complet du point de terminaison.FQDN is the fully qualified domain name of the endpoint.
  • Port est le port TCP du point de terminaison.Port is the TCP port of the endpoint. Par défaut, 1433 est supposé.By default, 1433 is assumed.

Notes

Les autres formes de spécification du point de terminaison réseau ne sont pas prises en charge.Other forms of specifying the network endpoint are not supported. Vous ne pouvez pas omettre, par exemple, le préfixe, tcp: même s’il est possible de le faire en utilisant les bibliothèques clientes SQL par programmation.One cannot omit, for example, the prefix tcp: even though it is possible to do so when using the SQL client libraries programmatically.

Cette fonctionnalité n’est pas prise en charge dans Azure MonitorThis capability isn't supported in Azure Monitor