sql_request, plug-in

Le sql_request plug-in envoie une requête SQL à un point de terminaison réseau SQL Server et retourne les résultats. Si plusieurs ensembles de lignes sont retournés par SQL, seul le premier est utilisé. Le plug-in est appelé avec l’opérateur evaluate .

Syntax

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

Découvrez les conventions de syntaxe.

Paramètres

Nom	Type	Obligatoire	Description
ConnectionString	string	✔️	Chaîne de connexion qui pointe vers le point de terminaison réseau SQL Server. Consultez les méthodes d’authentification valides et comment spécifier le point de terminaison réseau.
SqlQuery	string	✔️	Requête à exécuter sur le point de terminaison SQL. La requête doit retourner un ou plusieurs jeux de lignes, mais seul le premier est disponible pour le reste de la requête Kusto.
SqlParameters	dynamic		Un sac de propriétés de paires clé-valeur à passer en tant que paramètres avec la requête.
Options	dynamic		Un sac de propriétés de paires clé-valeur pour passer des paramètres plus avancés avec la requête. Actuellement, seul token peut être défini pour passer un jeton d’accès Microsoft Entra fourni par l’appelant qui est transféré au point de terminaison SQL pour l’authentification.
OutputSchema	string		Noms et types pour les colonnes attendues de la sortie du sql_request plug-in. Utilisez la syntaxe suivante : (ColumnName:ColumnType [, ...] ).

Notes

• La spécification de OutputSchema est fortement recommandée, car elle permet d’utiliser le plug-in dans des scénarios qui pourraient autrement ne pas fonctionner sans lui, comme une requête inter-cluster. OutputSchema peut également activer plusieurs optimisations de requête.
• Une erreur est générée si le schéma d’exécution du premier jeu de lignes retourné par le point de terminaison réseau SQL ne correspond pas au schéma OutputSchema .

Authentification et autorisation

Le plug-in sql_request prend en charge les trois méthodes d’authentification suivantes auprès du point de terminaison SQL Server.

Méthode d'authentification	Syntax	Comment	Description
Microsoft Entra intégré	Authentication="Active Directory Integrated"	Ajoutez au paramètre ConnectionString .	Il s'agit de la méthode d'authentification conseillée. L’utilisateur ou l’application s’authentifie via Microsoft Entra ID auprès de votre cluster, et le même jeton est utilisé pour accéder au point de terminaison réseau SQL Server. Le principal doit disposer des autorisations appropriées sur la ressource SQL pour effectuer l’action demandée. Par exemple, pour lire à partir de la base de données, le principal a besoin d’autorisations SELECT de table, et pour écrire dans une table existante, le principal a besoin des autorisations UPDATE et INSERT. Pour écrire dans une nouvelle table, les autorisations CREATE sont également requises.
Nom d’utilisateur et mot de passe	User ID=...; Password=...;	Ajoutez au paramètre ConnectionString .	Dans la mesure du possible, évitez cette méthode, car elle peut être moins sécurisée.
jeton d’accès Microsoft Entra	dynamic({'token': h"eyJ0..."})	Ajoutez le paramètre Options .	Le jeton d’accès est passé en tant que token propriété dans l’argument Options du plug-in.

Notes

Les chaînes de connexion et les requêtes qui incluent des informations confidentielles ou des informations à protéger doivent être masquées pour être omises de tout suivi Kusto. Pour plus d’informations, consultez Littéraux de chaîne obfusqués.

Exemples

Envoyer une requête SQL à l’aide de Microsoft Entra’authentification intégrée

L’exemple suivant envoie une requête SQL à une base de données de base de données Azure SQL. Il récupère tous les enregistrements à partir de [dbo].[Table], puis traite les résultats côté Kusto. L’authentification réutilise le jeton Microsoft Entra de l’utilisateur appelant.

Notes

Cet exemple ne doit pas être considéré comme une recommandation de filtrage ou de projet des données de cette manière. Les requêtes SQL doivent être construites pour retourner le plus petit jeu de données possible.

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

Envoyer une requête SQL à l’aide de l’authentification nom d’utilisateur/mot de passe

L’exemple suivant est identique au précédent, sauf que l’authentification SQL est effectuée par nom d’utilisateur/mot de passe. À des fins de confidentialité, nous utilisons ici des chaînes obfuscatées.

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

Envoyer une requête SQL à l’aide d’un jeton d’accès Microsoft Entra

L’exemple suivant envoie une requête SQL à une base de données Azure SQL récupérant tous les enregistrements à partir de [dbo].[Table], tout en ajoutant une autre datetime colonne, puis traite les résultats côté Kusto. Il spécifie un paramètre SQL (@param0) à utiliser dans la requête SQL.

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

Envoyer une requête SQL sans schéma de sortie défini par la requête

L’exemple suivant envoie une requête SQL à une base de données Azure SQL sans schéma de sortie. Cela n’est pas recommandé, sauf si le schéma est inconnu, car il peut avoir un impact sur les performances de la requête

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

Chiffrement et validation du serveur

Les propriétés de connexion suivantes sont forcées lors de la connexion à un point de terminaison réseau SQL Server, pour des raisons de sécurité.

• Encrypt est défini sur true inconditionnellement.
• TrustServerCertificate est défini sur false inconditionnellement.

Par conséquent, le SQL Server doit être configuré avec un certificat de serveur SSL/TLS valide.

Spécifier le point de terminaison réseau

La spécification du point de terminaison réseau SQL dans le cadre du chaîne de connexion est obligatoire. La syntaxe appropriée est :

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

Où :

• FQDN est le nom de domaine complet du point de terminaison.
• Port est le port TCP du point de terminaison. Par défaut, la valeur 1433 est supposée.

Notes

Les autres formes de spécification du point de terminaison réseau ne sont pas prises en charge. On ne peut pas omettre, par exemple, le préfixe tcp: , même s’il est possible de le faire lors de l’utilisation programmatique des bibliothèques clientes SQL.

Cette fonctionnalité n’est pas prise en charge dans Azure Monitor.