Plug-in sql_request

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

Sintassi

evaluatesql_request(Connessione ionString,SqlQuery [,SqlParameters [,Opzioni]] ) [:OutputSchema]

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Digita	Obbligatorio	Descrizione
ConnectionString	string	✔️	Il stringa di connessione che punta all'endpoint di rete di 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 di proprietà di coppie chiave-valore per passare impostazioni più avanzate insieme alla query. Attualmente, è possibile impostare solo token per passare un token di accesso Microsoft Entra fornito dal chiamante inoltrato all'endpoint SQL per l'autenticazione.
OutputSchema	string		Nomi e tipi per le colonne previste dell'output del plug-in sql_request . 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.
• Viene generato un errore se lo schema di runtime del primo set di righe restituito dall'endpoint di rete SQL non corrisponde allo schema OutputSchema .

Autenticazione e autorizzazione

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

Authentication method	Sintassi	Come	Descrizione
Integrato in Microsoft Entra	Authentication="Active Directory Integrated"	Aggiungere al parametro Connessione ionString.	Questo è il metodo di autenticazione ottimale. L'utente o l'applicazione esegue l'autenticazione tramite Microsoft Entra ID nel cluster e lo stesso token viene usato per accedere all'endpoint di rete di 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à deve disporre delle autorizzazioni table edizione Standard LECT e per scrivere in una tabella esistente, l'entità deve disporre delle autorizzazioni UPDATE e IN edizione Standard RT. Per scrivere in una nuova tabella, sono necessarie anche le autorizzazioni CREATE.
Nome utente e password	User ID=...; Password=...;	Aggiungere al parametro Connessione ionString.	Quando possibile, evitare questo metodo perché potrebbe essere meno sicuro.
Token di accesso di 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

Connessione stringhe e query che includono informazioni riservate o informazioni che devono essere protette devono essere offuscate per essere omesse da qualsiasi traccia Kusto. Per altre informazioni, vedere Valori letterali stringa offuscati.

Esempi

Inviare una query SQL usando l'autenticazione integrata di Microsoft Entra

L'esempio seguente invia una query SQL a un database SQL di Azure. Recupera tutti i record da [dbo].[Table]e quindi elabora i risultati sul lato Kusto. L'autenticazione riutilizza il token 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 da nome utente/password. Per la riservatezza, in questo caso vengono usate stringhe offuscate.

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

L'esempio seguente invia una query SQL a un database SQL di Azure 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

L'esempio seguente invia una query SQL a un database SQL di Azure senza uno schema di output. Questa operazione non è consigliata a meno che lo schema non sia sconosciuto, perché potrebbe 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 di SQL Server, per motivi di sicurezza.

• Encrypt è impostato su true incondizionato.
• TrustServerCertificate è impostato su false incondizionato.

Di conseguenza, 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