Complemento sql_requestsql_request plugin

El sql_request complemento envía una consulta SQL a un extremo de red SQL Server y devuelve el primer conjunto de filas en los resultados.The sql_request plugin sends a SQL query to a SQL Server network endpoint and returns the first rowset in the results. La consulta puede devolver más de un conjunto de filas, pero solo el primer conjunto de filas está disponible para el resto de la consulta Kusto.The query may return more then one rowset, but only the first rowset is made available for the rest of the Kusto query.

SyntaxSyntax

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

ArgumentosArguments

  • ConnectionString : un string literal que indica la cadena de conexión que apunta al extremo de red SQL Server.ConnectionString : A string literal indicating the connection string that points at the SQL Server network endpoint. Vea métodos válidos de autenticación y cómo especificar el punto de conexión de red.See valid methods of authentication and how to specify the network endpoint.

  • SqlQuery : un string literal que indica la consulta que se va a ejecutar en el extremo SQL.SqlQuery : A string literal indicating the query that is to be executed against the SQL endpoint. Debe devolver uno o más conjuntos de filas, pero solo el primero está disponible para el resto de la consulta Kusto.Must return one or more rowsets, but only the first one is made available for the rest of the Kusto query.

  • SqlParameters : un valor constante de tipo dynamic que contiene pares clave-valor que se pasan como parámetros junto con la consulta.SqlParameters : A constant value of type dynamic that holds key-value pairs to pass as parameters along with the query. Opcional.Optional.

  • Options : un valor constante de tipo dynamic que contiene valores más avanzados como pares clave-valor.Options : A constant value of type dynamic that holds more advanced settings as key-value pairs. Actualmente, solo token se puede establecer para pasar un token de acceso Azure ad proporcionado por el autor de llamada que se reenvía al punto de conexión de SQL para la autenticación.Currently, only token can be set, to pass a caller-provided Azure AD access token that is forwarded to the SQL endpoint for authentication. Opcional.Optional.

EjemplosExamples

En el ejemplo siguiente se envía una consulta SQL a una base de datos de Azure SQL Database.The following example sends a SQL query to an Azure SQL DB database. Recupera todos los registros de [dbo].[Table] y, a continuación, procesa los resultados en el lado de Kusto.It retrieves all records from [dbo].[Table], and then processes the results on the Kusto side. La autenticación reutiliza el token de Azure AD del usuario que realiza la llamada.Authentication reuses the calling user's Azure AD token.

Nota

Este ejemplo no debe considerarse como una recomendación para filtrar o proyectar los datos de esta manera.This example should not be taken as a recommendation to filter or project data in this manner. Las consultas SQL deben construirse para devolver el conjunto de datos más pequeño posible, ya que el optimizador de Kusto no intenta actualmente optimizar las consultas entre Kusto y 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

El ejemplo siguiente es idéntico al anterior, salvo que la autenticación de SQL se realiza mediante el nombre de usuario y la contraseña.The following example is identical to the previous one, except that SQL authentication is done by username/password. En cuanto a la confidencialidad, usamos cadenas ofuscadas aquí.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

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

AutenticaciónAuthentication

El complemento sql_request admite tres métodos de autenticación para el punto de conexión SQL Server:The sql_request plugin supports three methods of authentication to the SQL Server endpoint:

Autenticación integrada en Azure ADAzure AD-integrated authentication

Authentication="Active Directory Integrated"

La autenticación integrada Azure AD es el método preferido.Azure AD-integrated authentication is the preferred method. Este método tiene el usuario o la aplicación que se autentica a través de Azure AD en Kusto.This method has the user or application authenticate via Azure AD to Kusto. A continuación, se usa el mismo token para tener acceso al punto de conexión de red SQL Server.The same token is then used to access the SQL Server network endpoint.

Autenticación de nombre de usuario/contraseñaUsername/Password authentication

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

Se proporciona compatibilidad con la autenticación de nombre de usuario y contraseña cuando no se puede realizar la autenticación integrada en Azure AD.Username and password authentication support is provided when Azure AD-integrated authentication can't be done. Evite este método cuando sea posible, ya que la información secreta se envía a través de Kusto.Avoid this method, when possible, as secret information is sent through Kusto.

Azure AD token de accesoAzure AD access token

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

Con el método de autenticación Azure AD token de acceso, el autor de la llamada genera el token de acceso, que se reenvía mediante Kusto al punto de conexión de 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 cadena de conexión no debe incluir información de autenticación como Authentication , User ID o Password .The connection string shouldn't include authentication information like Authentication, User ID, or Password. En su lugar, el token de acceso se pasa como token propiedad en el Options argumento del complemento de sql_request.Instead, the access token is passed as token property in the Options argument of the sql_request plugin.

Advertencia

Las cadenas de conexión y las consultas que incluyen información confidencial o información que debe protegerse deben ofuscarse para omitirlas en cualquier seguimiento de 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. Para obtener más información, vea literales de cadena ofuscados.For more informations, see obfuscated string literals.

Cifrado y validación de servidorEncryption and server validation

Las siguientes propiedades de conexión se fuerzan al conectarse a un extremo de red SQL Server, por motivos de seguridad.The following connection properties are forced when connecting to a SQL Server network endpoint, for security reasons.

  • Encrypt está establecido en true incondicionalmente.Encrypt is set to true unconditionally.
  • TrustServerCertificate está establecido en false incondicionalmente.TrustServerCertificate is set to false unconditionally.

Como resultado, el SQL Server se debe configurar con un certificado de servidor SSL/TLS válido.As a result, the SQL Server must be configured with a valid SSL/TLS server certificate.

Especificar el punto de conexión de redSpecify the network endpoint

Es obligatorio especificar el extremo de red de SQL como parte de la cadena de conexión.Specifying the SQL network endpoint as part of the connection string is mandatory. La sintaxis adecuada es:The appropriate syntax is:

Server``= tcp: FQDN [ , Puerto ]Server = tcp: FQDN [, Port ]

Donde:Where:

  • FQDN es el nombre de dominio completo del punto de conexión.FQDN is the fully qualified domain name of the endpoint.
  • Port es el puerto TCP del extremo.Port is the TCP port of the endpoint. De forma predeterminada, 1433 se supone.By default, 1433 is assumed.

Nota

No se admiten otras formas de especificar el punto de conexión de red.Other forms of specifying the network endpoint are not supported. No se puede omitir, por ejemplo, el prefijo tcp: aunque sea posible hacerlo al usar las bibliotecas de cliente SQL mediante programación.One cannot omit, for example, the prefix tcp: even though it is possible to do so when using the SQL client libraries programmatically.

Esta funcionalidad no se admite en Azure MonitorThis capability isn't supported in Azure Monitor