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 utilizzata solo la prima. Il plug-in viene richiamato con l'operatore evaluate .

Sintassi

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

Argomenti

Nome Tipo Obbligatoria Descrizione
Connectionstring string Indica la 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 Indica la query da eseguire sull'endpoint SQL. Deve restituire uno o più set di righe, ma solo il primo viene reso disponibile per il resto della query Kusto.
Sqlparameters dinamico Contiene coppie chiave-valore da passare come parametri insieme alla query.
Opzioni dinamico Contiene impostazioni più avanzate come coppie chiave-valore. Attualmente è possibile impostare solo token per passare un token di accesso di Azure AD fornito dal chiamante inoltrato all'endpoint SQL per l'autenticazione.
OutputSchema Nomi e tipi per le colonne previste dell'output del sql_request plug-in.

L'argomento Facoltativo OutputSchema ha la sintassi seguente:

(Columnname:ColumnType [, ...])

Se si specifica questo argomento, il plug-in può essere usato in scenari ,ad esempio una query tra cluster, che altrimenti impedirebbe l'esecuzione e abilita più ottimizzazioni delle query. È quindi consigliabile specificarlo sempre. 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.

Esempi

Inviare una query SQL usando l'autenticazione integrata di Azure AD

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 Azure AD dell'utente chiamante.

Nota

In questo esempio non è consigliabile filtrare o proiettare i dati in questo modo. SQL query devono essere costruite per restituire il set di dati più piccolo possibile, poiché l'utilità di ottimizzazione di Kusto non tenta di ottimizzare le query tra Kusto e SQL.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select * from [dbo].[Table]')
| 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 SQL'autenticazione viene eseguita da 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]')
| where Id > 0
| project Name

Inviare una query SQL usando un token di accesso di Azure AD

Nell'esempio seguente viene inviata una query SQL a un database di 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)}))
| where Id > 0
| project Name

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

Nell'esempio seguente viene inviata una query SQL a un database di database di Azure SQL che recupera tutti i record da [dbo].[Table], selezionando solo colonne specifiche. Usa definizioni di schema esplicite che consentono di valutare varie ottimizzazioni prima dell'esecuzione della query effettiva su SQL.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select Id, Name') : (Id:long, Name:string)
| where Id > 0
| project Name

Authentication

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

Autenticazione integrata di Azure AD

Authentication="Active Directory Integrated"

L'autenticazione integrata di Azure AD è il metodo preferito. Questo metodo ha l'autenticazione dell'utente o dell'applicazione tramite Azure AD per Kusto. Lo stesso token viene quindi usato per accedere all'endpoint di rete SQL Server.

Autenticazione con nome utente/password

User ID=...; Password=...;

Il supporto per l'autenticazione con nome utente e password viene fornito quando non è possibile eseguire l'autenticazione integrata di Azure AD. Evitare questo metodo, quando possibile, perché le informazioni segrete vengono inviate tramite Kusto.

Token di accesso di Azure AD

dynamic({'token': h"eyJ0..."})

Con il metodo di autenticazione del token di accesso di Azure AD, il chiamante genera il token di accesso, che viene inoltrato da Kusto all'endpoint SQL. La stringa di connessione non deve includere informazioni di autenticazione come Authentication, User IDo Password. Al contrario, il token di accesso viene passato come token proprietà nell'argomento Options del plug-in sql_request.

Avviso

Le stringhe di connessione e le 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.

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 della 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