Condividi tramite

Plug-in sql_request

  • Articolo

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati

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 ( ConnectionString 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.

Metodo di autenticazione Sintassi Come Descrizione
Integrato in Microsoft Entra Authentication="Active Directory Integrated" Aggiungere al parametro ConnectionString . 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à 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.
Identità gestita Authentication="Active Directory Managed Identity";User Id={object_id} Aggiungere al parametro ConnectionString . La richiesta viene eseguita per conto di un'identità gestita. L'identità gestita deve disporre delle autorizzazioni appropriate per la risorsa SQL per eseguire l'azione richiesta.
Per abilitare l'autenticazione dell'identità gestita, è necessario aggiungere l'identità gestita al cluster e modificare i criteri di identità gestita. Per altre informazioni, vedere Criteri di identità gestita.
Nome utente e password User ID=...; Password=...; Aggiungere al parametro ConnectionString . 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

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.

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, questo valore è 1433.

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.