Plug-in sql_request

  • Artigo

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

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 plug-in é invocado com o evaluate operador.

Sintaxe

evaluatesql_request ( ConnectionString , SqlQuery [ , SqlParameters [ , Opções]] ) [: Esquema de saída]

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 que deve ser executada no ponto de extremidade SQL. A consulta deve retornar um ou mais conjuntos de linhas, mas apenas o primeiro é disponibilizado para o restante da consulta Kusto.
Parâmetros SQL dynamic Um recipiente de propriedades de pares chave-valor a serem passados como parâmetros junto com a consulta.
Opções dynamic Um recipiente de propriedades de pares de 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 do Microsoft Entra fornecido pelo chamador que é encaminhado para o ponto de extremidade SQL para autenticação.
Esquema de saída string Os nomes e tipos das 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 funcionariam 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 sql_request dá 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 . O usuário ou aplicativo é autenticado 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 de tabela e, para gravar em uma tabela existente, a entidade de segurança precisa de permissões UPDATE e INSERT. Para gravar em uma nova tabela, as permissões CREATE também são necessárias.
Identidade gerenciada Authentication="Active Directory Managed Identity";User Id={object_id} Adicione ao parâmetro ConnectionString . A solicitação é executada em nome de uma identidade gerenciada. A identidade gerenciada deve ter as permissões apropriadas no recurso SQL para executar a ação solicitada.
Para habilitar a autenticação de identidade gerenciada, você deve adicionar a identidade gerenciada ao cluster e alterar a política de identidade gerenciada. Para obter mais informações, consulte Política de identidade gerenciada.
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 Opções . O token de acesso é passado como token propriedade no argumento Options do plug-in.

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 do 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 fins de 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 de [dbo].[Table], enquanto acrescenta outra datetime coluna e, em seguida, processa os resultados no lado 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 do 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]

Em que:

  • 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.