Plug-in sql_request

O sql_request plug-in envia uma consulta SQL para um ponto de extremidade de rede SQL Server e retorna os resultados. Se mais de um conjunto de linhas for retornado pelo SQL, somente o primeiro será usado. O plug-in é invocado com o evaluate operador .

Syntax

evaluatesql_request(Connectionstring,SqlQuery [,SqlParameters [,Opções]] ) [:OutputSchema]

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
ConnectionString	string	✔️	O cadeia de conexão que aponta para o ponto de extremidade de rede SQL Server. Consulte métodos válidos de autenticação e como especificar o ponto de extremidade de rede.
SqlQuery	string	✔️	A consulta que deve ser executada no ponto de extremidade do SQL. A consulta deve retornar um ou mais conjuntos de linhas, mas apenas o primeiro é disponibilizado para o restante da consulta Kusto.
SqlParameters	dynamic		Um recipiente de propriedades de pares chave-valor para passar como parâmetros junto com a consulta.
Opções	dynamic		Um recipiente de propriedades de pares chave-valor para passar configurações mais avançadas junto com a consulta. Atualmente, só token pode ser definido para passar um token de acesso Microsoft Entra fornecido pelo chamador que é encaminhado para o ponto de extremidade sql para autenticação.
OutputSchema	string		Os nomes e tipos para as colunas esperadas da saída do sql_request plug-in. Use a seguinte sintaxe: (ColumnName:ColumnType [, ...] ).

Observação

• Especificar o OutputSchema é altamente recomendado, pois permite que o plug-in seja usado em cenários que, de outra forma, não funcionam sem ele, como uma consulta entre clusters. O OutputSchema também pode habilitar várias otimizações de consulta.
• Um erro será gerado se o esquema em tempo de execução do primeiro conjunto de linhas retornado pelo ponto de extremidade de rede SQL não corresponder ao esquema OutputSchema .

Autenticação e autorização

O plug-in sql_request dá suporte aos três métodos de autenticação a seguir para o ponto de extremidade SQL Server.

Método de autenticação	Syntax	Como	Descrição
Microsoft Entra integrado	Authentication="Active Directory Integrated"	Adicione ao parâmetro ConnectionString .	Esse é o método de autenticação preferido. O usuário ou aplicativo é autenticado por meio de Microsoft Entra ID para o cluster e o mesmo token é usado para acessar o ponto de extremidade de rede SQL Server. A entidade de segurança deve ter as permissões apropriadas no recurso SQL para executar a ação solicitada. Por exemplo, para ler do banco de dados, a entidade de segurança precisa de permissões SELECT de tabela e gravar em uma tabela existente, a entidade de segurança precisa das permissões UPDATE e INSERT. Para gravar em uma nova tabela, as permissões CREATE também são necessárias.
Nome de usuário e senha	User ID=...; Password=...;	Adicione ao parâmetro ConnectionString .	Quando possível, evite esse método, pois ele pode ser menos seguro.
token de acesso Microsoft Entra	dynamic({'token': h"eyJ0..."})	Adicione o parâmetro Options .	O token de acesso é passado como token propriedade no argumento Options do plug-in.

Observação

As cadeias de conexão e as consultas que incluem informações confidenciais ou informações que devem ser protegidas devem ser ofuscadas para serem omitidas de qualquer rastreamento do Kusto. Para obter mais informações, consulte literais de cadeia de caracteres ofuscados.

Exemplos

Enviar uma consulta SQL usando Microsoft Entra autenticação integrada

O exemplo a seguir envia uma consulta SQL para um banco de dados SQL do Azure DB. Ele recupera todos os registros de [dbo].[Table]e processa os resultados no lado do Kusto. A autenticação reutiliza o token de Microsoft Entra do usuário que está chamando.

Observação

Este exemplo não deve ser tomado como uma recomendação para filtrar ou projetar dados dessa maneira. As consultas SQL devem ser construídas para retornar o menor conjunto de dados possível.

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

Enviar uma consulta SQL usando autenticação de nome de usuário/senha

O exemplo a seguir é idêntico ao anterior, exceto que a autenticação SQL é feita por nome de usuário/senha. Para confidencialidade, usamos cadeias de caracteres ofuscadas aqui.

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

Enviar uma consulta SQL usando um token de acesso Microsoft Entra

O exemplo a seguir envia uma consulta SQL para um banco de dados SQL do Azure recuperando todos os registros de [dbo].[Table], acrescentando outra datetime coluna e processa os resultados no lado do Kusto. Ele especifica um parâmetro SQL (@param0) a ser usado na 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

Enviar uma consulta SQL sem um esquema de saída definido por consulta

O exemplo a seguir envia uma consulta SQL para um banco de dados SQL do Azure sem um esquema de saída. Isso não é recomendado, a menos que o esquema seja desconhecido, pois pode afetar o desempenho da 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

Criptografia e validação de servidor

As propriedades de conexão a seguir são forçadas ao se conectar a um ponto de extremidade de rede SQL Server, por motivos de segurança.

• Encrypt é definido como true incondicionalmente.
• TrustServerCertificate é definido como false incondicionalmente.

Como resultado, o SQL Server deve ser configurado com um certificado de servidor SSL/TLS válido.

Especificar o ponto de extremidade de rede

Especificar o ponto de extremidade de rede SQL como parte do cadeia de conexão é obrigatório. A sintaxe apropriada é:

Server=tcp:FQDN [,Porta]

Em que:

• FQDN é o nome de domínio totalmente qualificado do ponto de extremidade.
• A porta é a porta TCP do ponto de extremidade. Por padrão, 1433 é assumido.

Observação

Não há suporte para outras formas de especificação do ponto de extremidade de rede. Não é possível omitir, por exemplo, o prefixo tcp: , embora seja possível fazer isso ao usar as bibliotecas de cliente SQL programaticamente.

Essa funcionalidade não é compatível com o Azure Monitor