Plug-in sql_request

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

Sintaxe

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Digitar	Obrigatória	Descrição
ConnectionString	string	✔️	A cadeia de conexão que aponta para o ponto de extremidade de rede do SQL Server. Consulte métodos válidos de autenticação e como especificar o ponto de extremidade de rede.
SqlQuery	string	✔️	A consulta a ser executada no ponto de extremidade SQL. A consulta deve retornar um ou mais conjuntos de linhas, mas somente o primeiro é disponibilizado para o restante da consulta do Kusto.
SqlParameters	dynamic		Um conjunto de propriedades de pares chave-valor para passar como parâmetros junto com a consulta.
Opções	dynamic		Um conjunto de propriedades de pares chave-valor para passar configurações mais avançadas junto com a consulta. Atualmente, somente token pode ser definido para passar um token de acesso do 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 plugin. 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, poderiam não funcionar 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 de 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 do sql_request oferece suporte aos três métodos de autenticação a seguir para o ponto de extremidade do SQL Server.

Método de autenticação	Sintaxe	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 se autentica por meio da ID do Microsoft Entra no cluster e o mesmo token é usado para acessar o ponto de extremidade de rede do 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 da tabela e para gravar em uma tabela existente, a entidade 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 pode ser menos seguro.
Token de acesso do Microsoft Entra	dynamic({'token': h"eyJ0..."})	Adicione o parâmetro Options .	O token de acesso é passado como token propriedade no argumento Options do plugin.

Observação

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

Exemplos

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

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

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 a 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 strings 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 do Microsoft Entra

O exemplo a seguir envia uma consulta SQL para um banco de dados SQL do Azure recuperando todos os registros do [dbo].[Table], enquanto acrescenta outra datetime coluna e, em seguida, 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 pela 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 do SQL Server, por motivos de segurança.

• Encrypt está definido como true incondicionalmente.
• TrustServerCertificate está 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 da cadeia de conexão é obrigatório. A sintaxe apropriada é:

Server= tcp: FQDN [, Porta]

Onde:

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

Observação

Não há suporte para outras formas de especificar o ponto de extremidade de rede. Não se pode omitir, por exemplo, o prefixo tcp: , embora seja possível fazê-lo ao usar as bibliotecas de cliente SQL programaticamente.

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