Complemento sql_request

El sql_request complemento envía una consulta SQL a un punto de conexión de red SQL Server y devuelve los resultados. Si SQL devuelve más de un conjunto de filas, solo se usa el primero. El complemento se invoca con el evaluate operador .

Syntax

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

Obtenga más información sobre las convenciones de sintaxis.

Parámetros

Nombre	Tipo	Requerido	Descripción
ConnectionString	string	✔️	El cadena de conexión que apunta al punto de conexión de red SQL Server. Consulte los métodos válidos de autenticación y cómo especificar el punto de conexión de red.
SqlQuery	string	✔️	Consulta que se va a ejecutar en el punto de conexión de SQL. La consulta debe devolver uno o varios conjuntos de filas, pero solo el primero está disponible para el resto de la consulta de Kusto.
SqlParameters	dynamic		Contenedor de propiedades de pares clave-valor para pasar como parámetros junto con la consulta.
Opciones	dynamic		Contenedor de propiedades de pares clave-valor para pasar configuraciones más avanzadas junto con la consulta. Actualmente, solo token se puede establecer para pasar un token de acceso proporcionado por el autor de la llamada Microsoft Entra que se reenvía al punto de conexión de SQL para la autenticación.
OutputSchema	string		Nombres y tipos de las columnas esperadas de la salida del sql_request complemento. Use la siguiente sintaxis: (ColumnName:ColumnType [, ...] ).

Nota

• Se recomienda especificar OutputSchema , ya que permite usar el complemento en escenarios que, de lo contrario, podrían no funcionar sin él, como una consulta entre clústeres. OutputSchema también puede habilitar varias optimizaciones de consulta.
• Se produce un error si el esquema en tiempo de ejecución del primer conjunto de filas devuelto por el punto de conexión de red SQL no coincide con el esquema OutputSchema .

Autenticación y autorización

El complemento sql_request admite los tres métodos siguientes de autenticación en el punto de conexión de SQL Server.

Método de autenticación	Syntax	Cómo	Descripción
Microsoft Entra integrado	Authentication="Active Directory Integrated"	Agregue al parámetro ConnectionString .	Éste es el método de autenticación preferido. El usuario o la aplicación se autentica a través de Microsoft Entra ID en el clúster y se usa el mismo token para acceder al punto de conexión de red SQL Server. La entidad de seguridad debe tener los permisos adecuados en el recurso SQL para realizar la acción solicitada. Por ejemplo, para leer desde la base de datos, la entidad de seguridad necesita permisos SELECT de tabla y escribir en una tabla existente, la entidad de seguridad necesita permisos UPDATE e INSERT. Para escribir en una nueva tabla, también se requieren permisos CREATE.
Nombre de usuario y contraseña	User ID=...; Password=...;	Agregue al parámetro ConnectionString .	Cuando sea posible, evite este método, ya que puede ser menos seguro.
token de acceso de Microsoft Entra	dynamic({'token': h"eyJ0..."})	Agregue en el parámetro Options .	El token de acceso se pasa como token propiedad en el argumento Options del complemento.

Nota

Las cadenas de conexión y las consultas que incluyen información confidencial o información que se debe proteger deben ofuscarse para omitirse de cualquier seguimiento de Kusto. Para obtener más información, vea literales de cadena ofuscados.

Ejemplos

Envío de una consulta SQL mediante Microsoft Entra autenticación integrada

En el ejemplo siguiente se envía una consulta SQL a una base de datos de Azure SQL base de datos. Recupera todos los registros de [dbo].[Table]y, a continuación, procesa los resultados en el lado de Kusto. La autenticación reutiliza el token de Microsoft Entra del usuario que llama.

Nota

Este ejemplo no se debe tomar como recomendación para filtrar o proyectar datos de esta manera. Las consultas SQL se deben construir para devolver el conjunto de datos más pequeño posible.

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

Envío de una consulta SQL mediante la autenticación de nombre de usuario y contraseña

El ejemplo siguiente es idéntico al anterior, salvo que la autenticación de SQL se realiza mediante nombre de usuario y contraseña. Para la confidencialidad, usamos cadenas ofuscadas aquí.

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

Envío de una consulta SQL mediante un token de acceso de Microsoft Entra

En el ejemplo siguiente se envía una consulta SQL a una base de datos de Azure SQL que recupera todos los registros de [dbo].[Table], mientras se anexa otra datetime columna y, a continuación, se procesan los resultados en el lado de Kusto. Especifica un parámetro SQL (@param0) que se usará en la consulta 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

Envío de una consulta SQL sin un esquema de salida definido por la consulta

En el ejemplo siguiente se envía una consulta SQL a una base de datos Azure SQL sin un esquema de salida. Esto no se recomienda a menos que el esquema sea desconocido, ya que puede afectar al rendimiento de la consulta.

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

Cifrado y validación del servidor

Las siguientes propiedades de conexión se fuerzan al conectarse a un punto de conexión de red SQL Server, por motivos de seguridad.

• Encrypt se establece en true incondicionalmente.
• TrustServerCertificate se establece en false incondicionalmente.

Como resultado, el SQL Server debe configurarse con un certificado de servidor SSL/TLS válido.

Especificación del punto de conexión de red

Especificar el punto de conexión de red SQL como parte del cadena de conexión es obligatorio. La sintaxis adecuada es:

Server=tcp:FQDN [,Puerto]

Donde:

• FQDN es el nombre de dominio completo del punto de conexión.
• El puerto es el puerto TCP del punto de conexión. De manera predeterminada, se presupone que es 1433.

Nota

No se admiten otras formas de especificar el punto de conexión de red. No se puede omitir, por ejemplo, el prefijo tcp: aunque sea posible hacerlo al usar las bibliotecas cliente de SQL mediante programación.

Esta funcionalidad no se admite en Azure Monitor.