Compartir a través de

Complemento sql_request

  • Artículo

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer

El sql_request complemento envía una consulta SQL a un punto de conexión de red de Azure 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 .

Sintaxis

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

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

Parámetros

Nombre Type Obligatorio Descripción
ConnectionString string ✔️ El cadena de conexión que apunta al punto de conexión de red de 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 que se van a 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 de Microsoft Entra proporcionado por el autor de la llamada que se reenvía al punto de conexión de SQL para la autenticación.
OutputSchema string Los nombres y tipos de las columnas esperadas de la salida del sql_request complemento. Use la sintaxis siguiente: ( ColumnName : ColumnType [, ...] ).

Nota:

  • Se recomienda especificar OutputSchema, ya que permite usar el complemento en escenarios que 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 Sintaxis Cómo Descripción
Microsoft Entra integrado Authentication="Active Directory Integrated" Agregue al parámetro ConnectionString . 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 de 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.
Identidad administrada Authentication="Active Directory Managed Identity";User Id={object_id} Agregue al parámetro ConnectionString . La solicitud se ejecuta en nombre de una identidad administrada. La identidad administrada debe tener los permisos adecuados en el recurso SQL para realizar la acción solicitada.
Para habilitar la autenticación de identidad administrada, debe agregar la identidad administrada al clúster y modificar la directiva de identidad administrada. Para más información, consulte Directiva de identidad administrada.
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 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, consulte literales de cadena ofuscados.

Ejemplos

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

En el ejemplo siguiente se envía una consulta SQL a una base de datos de Azure SQL DB. 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], al anexar otra datetime columna y, a continuación, se procesan los resultados en el lado de Kusto. Especifica un parámetro SQL (@param0) que se va a 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 de 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 de SQL Server, por motivos de seguridad.

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

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

Especificar el 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.