Partager via

sql_request, plug-in

  • Article

S’applique à : ✅Microsoft Fabric✅Azure Data Explorer

Le sql_request plug-in envoie une requête SQL à un point de terminaison réseau Azure 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 .

Syntaxe

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

En savoir plus sur les conventions de syntaxe.

Paramètres

Nom Type Requise Description
ConnectionString string ✔️ Le 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 Conteneur de propriétés de paires clé-valeur à transmettre en tant que paramètres avec la requête.
Options dynamic Un conteneur de propriétés de paires clé-valeur pour transmettre 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 [, ...] ).

Remarque

  • La spécification de OutputSchema est vivement recommandée, car elle permet au plug-in d’être utilisé dans des scénarios qui peuvent ne pas fonctionner sans cela, 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 sur le point de terminaison SQL Server.

Méthode d'authentification Syntaxe Comment Description
Authentification intégrée Microsoft Entra Authentication="Active Directory Integrated" Ajoutez au paramètre ConnectionString . L’utilisateur ou l’application s’authentifie via l’ID Microsoft Entra sur 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 d’autorisations UPDATE et INSERT. Pour écrire dans une nouvelle table, les autorisations CREATE sont également requises.
Identité managée Authentication="Active Directory Managed Identity";User Id={object_id} Ajoutez au paramètre ConnectionString . La requête est exécutée pour le compte d’une identité managée. L’identité managée doit disposer des autorisations appropriées sur la ressource SQL pour effectuer l’action demandée.
Pour activer l’authentification d’identité managée, vous devez ajouter l’identité managée à votre cluster et modifier la stratégie d’identité managée. Pour plus d’informations, consultez la stratégie d’identité managée.
Nom d’utilisateur et mot de passe User ID=...; Password=...; Ajoutez au paramètre ConnectionString . Si 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.

Remarque

Les chaînes de connexion et les requêtes qui incluent des informations confidentielles ou des informations qui doivent être gardées 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 l’authentification intégrée Microsoft Entra

L’exemple suivant envoie une requête SQL à une base de données Azure SQL DB. 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.

Remarque

Cet exemple ne doit pas être considéré comme une recommandation pour filtrer ou projeter les 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 à celui précédent, sauf que l’authentification SQL est effectuée par nom d’utilisateur/mot de passe. Pour la 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 [dbo].[Table]données Azure SQL récupérant tous les enregistrements, 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

Validation du chiffrement et 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 de true manière inconditionnelle.
  • TrustServerCertificate est défini de false manière inconditionnelle.

Par conséquent, 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 de la chaîne de connexion est obligatoire. La syntaxe appropriée est :

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

Où :

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

Remarque

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 des bibliothèques clientes SQL par programmation.