Plug-in sql_request

Il sql_request plug-in invia una query SQL a un endpoint di rete SQL Server e restituisce i risultati. Se vengono restituiti più set di righe da SQL, viene usato solo il primo set di righe. Il plug-in viene richiamato con l'operatore evaluate .

Sintassi

evaluatesql_request(Connectionstring,SqlQuery [,SqlParameters [,Opzioni]] ) [:OutputSchema]

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Tipo	Obbligatoria	Descrizione
ConnectionString	string	✔️	Il stringa di connessione che punta all'endpoint di rete SQL Server. Vedere metodi validi di autenticazione e come specificare l'endpoint di rete.
SqlQuery	string	✔️	Query da eseguire sull'endpoint SQL. La query deve restituire uno o più set di righe, ma solo il primo viene reso disponibile per il resto della query Kusto.
Sqlparameters	dynamic		Contenitore di proprietà di coppie chiave-valore da passare come parametri insieme alla query.
Opzioni	dynamic		Contenitore delle proprietà di coppie chiave-valore per passare impostazioni più avanzate insieme alla query. Attualmente, è possibile impostare solo token per passare un token di accesso fornito dal chiamante Microsoft Entra inoltrato all'endpoint SQL per l'autenticazione.
OutputSchema	string		Nomi e tipi per le colonne previste dell'output del sql_request plug-in. Usare la sintassi seguente: (ColumnName:ColumnType [, ...] ).

Nota

• È consigliabile specificare OutputSchema , in quanto consente l'uso del plug-in in scenari che potrebbero altrimenti non funzionare senza di esso, ad esempio una query tra cluster. OutputSchema può anche abilitare più ottimizzazioni delle query.
• Se lo schema di runtime del primo set di righe restituito dall'endpoint di rete SQL non corrisponde allo schema OutputSchema , viene generato un errore.

Autenticazione e autorizzazione

Il plug-in sql_request supporta i tre metodi di autenticazione seguenti per l'endpoint SQL Server.

Metodo di autenticazione	Sintassi	Come	Descrizione
Microsoft Entra integrato	Authentication="Active Directory Integrated"	Aggiungere al parametro ConnectionString .	Questo è il metodo di autenticazione ottimale. L'utente o l'applicazione esegue l'autenticazione tramite Microsoft Entra ID al cluster e lo stesso token viene usato per accedere all'endpoint di rete SQL Server. L'entità deve disporre delle autorizzazioni appropriate per la risorsa SQL per eseguire l'azione richiesta. Ad esempio, per leggere dal database l'entità di sicurezza richiede autorizzazioni SELECT per la tabella e per scrivere in una tabella esistente l'entità deve disporre delle autorizzazioni UPDATE e INSERT. Per scrivere in una nuova tabella, sono necessarie anche le autorizzazioni CREATE.
Nome utente e password	User ID=...; Password=...;	Aggiungere al parametro ConnectionString .	Quando possibile, evitare questo metodo perché potrebbe essere meno sicuro.
token di accesso Microsoft Entra	dynamic({'token': h"eyJ0..."})	Aggiungere il parametro Options .	Il token di accesso viene passato come token proprietà nell'argomento Options del plug-in.

Nota

Le stringhe di connessione e le query che includono informazioni riservate o informazioni da proteggere devono essere offuscate per essere omesse da qualsiasi traccia Kusto. Per altre informazioni, vedere Valori letterali stringa offuscati.

Esempio

Inviare una query SQL usando Microsoft Entra'autenticazione integrata

Nell'esempio seguente viene inviata una query SQL a un database di database Azure SQL. Recupera tutti i record da [dbo].[Table]e quindi elabora i risultati sul lato Kusto. L'autenticazione riutilizza il token di Microsoft Entra dell'utente chiamante.

Nota

In questo esempio non è consigliabile filtrare o proiettare i dati in questo modo. Le query SQL devono essere costruite per restituire il set di dati più piccolo possibile.

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

Inviare una query SQL usando l'autenticazione nome utente/password

L'esempio seguente è identico a quello precedente, ad eccezione del fatto che l'autenticazione SQL viene eseguita con nome utente/password. Per la riservatezza, usiamo le stringhe offuscate qui.

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

Inviare una query SQL usando un token di accesso Microsoft Entra

Nell'esempio seguente viene inviata una query SQL a un database Azure SQL che recupera tutti i record da [dbo].[Table], aggiungendo un'altra datetime colonna e quindi elabora i risultati sul lato Kusto. Specifica un parametro SQL (@param0) da usare nella query 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

Inviare una query SQL senza uno schema di output definito da query

Nell'esempio seguente viene inviata una query SQL a un database Azure SQL senza uno schema di output. Questa operazione non è consigliata a meno che lo schema non sia sconosciuto, perché può influire sulle prestazioni della query

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

Crittografia e convalida del server

Le proprietà di connessione seguenti vengono forzate durante la connessione a un endpoint di rete SQL Server, per motivi di sicurezza.

• Encrypt è impostato su true senza condizioni.
• TrustServerCertificate è impostato su false senza condizioni.

Di conseguenza, il SQL Server deve essere configurato con un certificato server SSL/TLS valido.

Specificare l'endpoint di rete

Specificare l'endpoint di rete SQL come parte del stringa di connessione è obbligatorio. La sintassi appropriata è:

Server=tcp:FQDN [,Porta]

Dove:

• FQDN è il nome di dominio completo dell'endpoint.
• La porta è la porta TCP dell'endpoint. Per impostazione predefinita, 1433 si presuppone .

Nota

Altre forme di specifica dell'endpoint di rete non sono supportate. Non è possibile omettere, ad esempio, il prefisso tcp: anche se è possibile farlo quando si usano le librerie client SQL a livello di codice.

Questa funzionalità non è supportata in Monitoraggio di Azure