plug-in sql_request

O sql_request plug-in envia uma consulta SQL para um ponto final de rede SQL Server e devolve os resultados. Se mais do que um conjunto de linhas for devolvido pelo SQL, só é utilizado o primeiro. 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	Necessário	Descrição
ConnectionString	string	✔️	A cadeia de ligação que aponta para o ponto final de rede SQL Server. Veja métodos válidos de autenticação e como especificar o ponto final de rede.
SqlQuery	string	✔️	A consulta que vai ser executada no ponto final do SQL. A consulta tem de devolver um ou mais conjuntos de linhas, mas apenas o primeiro é disponibilizado para o resto da consulta Kusto.
SqlParameters	dynamic		Um conjunto de propriedades de pares chave-valor para transmitir como parâmetros juntamente com a consulta.
Opções	dynamic		Um conjunto de propriedades de pares chave-valor para transmitir definições mais avançadas juntamente com a consulta. Atualmente, só token pode ser definido para transmitir um token de acesso fornecido pelo chamador Microsoft Entra que é reencaminhado para o ponto final do SQL para autenticação.
OutputSchema	string		Os nomes e tipos das colunas esperadas da saída do sql_request plug-in. Utilize a seguinte sintaxe: (ColumnName:ColumnType [, ...] ).

Nota

• Especificar o OutputSchema é altamente recomendado, uma vez que permite que o plug-in seja utilizado em cenários que, de outra forma, não funcionarão sem ele, como uma consulta entre clusters. O OutputSchema também pode ativar várias otimizações de consultas.
• É gerado um erro se o esquema de tempo de execução do primeiro conjunto de linhas devolvido pelo ponto final de rede SQL não corresponder ao esquema OutputSchema .

Autenticação e autorização

O plug-in sql_request suporta os três métodos seguintes de autenticação para o ponto final SQL Server.

Método de autenticação	Syntax	Como	Description
Microsoft Entra integrado	Authentication="Active Directory Integrated"	Adicione ao parâmetro ConnectionString .	Este é o método de autenticação preferencial. O utilizador ou aplicação autentica-se através de Microsoft Entra ID no cluster e o mesmo token é utilizado para aceder ao ponto final de rede SQL Server. O principal tem de ter as permissões adequadas no recurso SQL para executar a ação pedida. Por exemplo, para ler a partir da base de dados, o principal precisa de permissões SELECT da tabela e para escrever numa tabela existente, o principal precisa de permissões UPDATE e INSERT. Para escrever numa nova tabela, também são necessárias permissões CREATE.
Nome de utilizador e palavra-passe	User ID=...; Password=...;	Adicione ao parâmetro ConnectionString .	Sempre que possível, evite este método, uma vez que pode ser menos seguro.
Microsoft Entra token de acesso	dynamic({'token': h"eyJ0..."})	Adicione o parâmetro Opções .	O token de acesso é transmitido como token propriedade no argumento Opções do plug-in.

Nota

As cadeias de ligação e as consultas que incluem informações confidenciais ou informações que devem ser guardadas devem ser ocultadas para serem omitidas de qualquer rastreio do Kusto. Para obter mais informações, veja literais de cadeias ocultas.

Exemplos

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

O exemplo seguinte envia uma consulta SQL para uma base de dados SQL do Azure DB. Obtém todos os registos de [dbo].[Table]e, em seguida, processa os resultados do lado do Kusto. A autenticação reutiliza o token de Microsoft Entra do utilizador que está a chamar.

Nota

Este exemplo não deve ser considerado como uma recomendação para filtrar ou projetar dados desta forma. As consultas SQL devem ser construídas para devolver 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 com a autenticação nome de utilizador/palavra-passe

O exemplo seguinte é idêntico ao exemplo anterior, exceto que a autenticação SQL é efetuada por nome de utilizador/palavra-passe. Para confidencialidade, utilizamos cadeias ocultas 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 com um token de acesso Microsoft Entra

O exemplo seguinte envia uma consulta SQL para uma base de dados SQL do Azure a obter todos os registos de [dbo].[Table], ao acrescentar outra datetime coluna e, em seguida, processa os resultados no lado do Kusto. Especifica um parâmetro SQL (@param0) a ser utilizado 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 seguinte envia uma consulta SQL para uma base de dados SQL do Azure sem um esquema de saída. Isto não é recomendado a menos que o esquema seja desconhecido, uma vez que 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

Encriptação e validação do servidor

As seguintes propriedades de ligação são forçadas ao ligar a um ponto final de rede SQL Server, por motivos de segurança.

• Encrypt está definido como true incondicionalmente.
• TrustServerCertificate está definido como false incondicionalmente.

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

Especificar o ponto final de rede

É obrigatório especificar o ponto final da rede SQL como parte do cadeia de ligação. A sintaxe adequada é:

Server=tcp:FQDN [,Porta]

Em que:

• FQDN é o nome de domínio completamente qualificado do ponto final.
• A porta é a porta TCP do ponto final. Por predefinição, 1433 é assumido.

Nota

Outras formas de especificar o ponto final de rede não são suportadas. Não é possível omitir, por exemplo, o prefixo tcp: , mesmo que seja possível fazê-lo ao utilizar as bibliotecas de cliente SQL programaticamente.

Esta capacidade não é suportada no Azure Monitor