Partilhar via

Plugin de solicitação SQL

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

Sintaxe

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

Saiba mais sobre convenções de sintaxe.

Parâmetros

Nome Tipo Obrigatório 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.
SqlParameters dynamic Um conjunto de propriedades de pares chave-valor para passar como parâmetros junto com a consulta.
Opções dynamic Um pacote 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.
Esquema de saída string Os nomes e tipos para as colunas esperadas da saída do plug-in sql_request. 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 da rede SQL não corresponder ao esquema OutputSchema .

Autenticação e autorização

O plug-in 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 . O usuário ou aplicativo é autenticado por meio do Microsoft Entra ID em seu 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 a partir 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.
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 utilizador e palavra-passe User ID=...; Password=...; Adicione ao parâmetro ConnectionString . Sempre que possível, evite este método, pois 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 Opções do plugin.
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 do Microsoft Entra ID em seu 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 a partir 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 utilizador e palavra-passe User ID=...; Password=...; Adicione ao parâmetro ConnectionString . Sempre que possível, evite este método, pois 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 Opções 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 ofuscadas.

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 cordas 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 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 é 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 da rede

É obrigatório especificar o ponto de extremidade da rede SQL como parte da cadeia de conexão. 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 da 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.

  • Last updated on