Invoegtoepassing voor sql_request

De sql_request invoegtoepassing verzendt een SQL-query naar een SQL Server netwerkeindpunt en retourneert de resultaten. Als meer dan één rijenset wordt geretourneerd door SQL, wordt alleen de eerste gebruikt. De invoegtoepassing wordt aangeroepen met de evaluate operator.

Syntax

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

Meer informatie over syntaxisconventies.

Parameters

Naam	Type	Vereist	Beschrijving
Connectionstring	string	✔️	De verbindingsreeks die naar het SQL Server-netwerkeindpunt wijst. Zie geldige verificatiemethoden en hoe u het netwerkeindpunt opgeeft.
SqlQuery	string	✔️	De query die moet worden uitgevoerd op het SQL-eindpunt. De query moet een of meer rijensets retourneren, maar alleen de eerste wordt beschikbaar gesteld voor de rest van de Kusto-query.
SqlParameters	dynamic		Een eigenschappenverzameling van sleutel-waardeparen die moeten worden doorgegeven als parameters samen met de query.
Opties	dynamic		Een eigenschappenverzameling van sleutel-waardeparen om meer geavanceerde instellingen door te geven samen met de query. Momenteel kan alleen token worden ingesteld om een Microsoft Entra toegangstoken door te geven dat wordt doorgestuurd naar het SQL-eindpunt voor verificatie.
OutputSchema	string		De namen en typen voor de verwachte kolommen van de uitvoer van de sql_request invoegtoepassing. Gebruik de volgende syntaxis: (ColumnName:ColumnType [, ...] ).

Notitie

• Het opgeven van het OutputSchema wordt ten zeerste aanbevolen, omdat hiermee de invoegtoepassing kan worden gebruikt in scenario's die anders anders niet werken, zoals een query op meerdere clusters. Het OutputSchema kan ook meerdere queryoptimalisaties inschakelen.
• Er treedt een fout op als het runtimeschema van de eerste rijset die door het SQL-netwerkeindpunt wordt geretourneerd, niet overeenkomt met het OutputSchema-schema .

Verificatie en autorisatie

De sql_request-invoegtoepassing ondersteunt de volgende drie verificatiemethoden voor het SQL Server-eindpunt.

Verificatiemethode	Syntax	Hoe	Description
Microsoft Entra geïntegreerd	Authentication="Active Directory Integrated"	Voeg toe aan de parameter ConnectionString .	Dit is de voorkeursmethode voor verificatie. De gebruiker of toepassing verifieert via Microsoft Entra ID uw cluster en hetzelfde token wordt gebruikt voor toegang tot het SQL Server netwerkeindpunt. De principal moet de juiste machtigingen hebben voor de SQL-resource om de aangevraagde actie uit te voeren. Als u bijvoorbeeld wilt lezen uit de database, heeft de principal de tabel SELECT-machtigingen nodig en om naar een bestaande tabel te schrijven, heeft de principal de machtigingen UPDATE en INSERT nodig. Als u naar een nieuwe tabel wilt schrijven, zijn ook CREATE-machtigingen vereist.
Gebruikersnaam en wachtwoord	User ID=...; Password=...;	Voeg toe aan de parameter ConnectionString .	Vermijd deze methode indien mogelijk, omdat deze mogelijk minder veilig is.
Microsoft Entra toegangstoken	dynamic({'token': h"eyJ0..."})	Voeg de parameter Opties toe.	Het toegangstoken wordt doorgegeven als token eigenschap in het argument Opties van de invoegtoepassing.

Notitie

Verbindingsreeksen en query's die vertrouwelijke informatie bevatten of informatie die moet worden beveiligd, moeten worden verborgen om te worden weggelaten bij Kusto-tracering. Zie Verborgen letterlijke tekenreeksen voor meer informatie.

Voorbeelden

Een SQL-query verzenden met behulp van Microsoft Entra geïntegreerde verificatie

In het volgende voorbeeld wordt een SQL-query verzonden naar een Azure SQL DB-database. Alle records worden opgehaald uit [dbo].[Table]en vervolgens worden de resultaten aan de Kusto-zijde verwerkt. Met verificatie wordt het Microsoft Entra-token van de aanroepende gebruiker opnieuw gebruikt.

Notitie

Dit voorbeeld moet niet worden beschouwd als een aanbeveling om gegevens op deze manier te filteren of te projecteren. SQL-query's moeten worden samengesteld om de kleinst mogelijke gegevensset te retourneren.

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

Een SQL-query verzenden met behulp van gebruikersnaam-/wachtwoordverificatie

Het volgende voorbeeld is identiek aan het vorige voorbeeld, behalve dat SQL-verificatie wordt uitgevoerd op basis van gebruikersnaam/wachtwoord. Voor vertrouwelijkheid gebruiken we hier verborgen tekenreeksen.

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

Een SQL-query verzenden met behulp van een Microsoft Entra-toegangstoken

In het volgende voorbeeld wordt een SQL-query verzonden naar een Azure SQL-database waarbij alle records worden opgehaald uit [dbo].[Table], terwijl er nog een datetime kolom wordt toegevoegd, en vervolgens worden de resultaten aan de Kusto-zijde verwerkt. Hiermee wordt een SQL-parameter (@param0) opgegeven die moet worden gebruikt in de SQL-query.

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

Een SQL-query verzenden zonder een querygedefinieerde uitvoerschema

In het volgende voorbeeld wordt een SQL-query verzonden naar een Azure SQL-database zonder uitvoerschema. Dit wordt niet aanbevolen, tenzij het schema onbekend is, omdat dit van invloed kan zijn op de prestaties van de 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

Versleuteling en servervalidatie

De volgende verbindingseigenschappen worden om veiligheidsredenen afgedwongen wanneer u verbinding maakt met een SQL Server-netwerkeindpunt.

• Encrypt wordt ingesteld op true onvoorwaardelijk.
• TrustServerCertificate wordt ingesteld op false onvoorwaardelijk.

Als gevolg hiervan moet de SQL Server worden geconfigureerd met een geldig SSL/TLS-servercertificaat.

Het netwerkeindpunt opgeven

Het opgeven van het SQL-netwerkeindpunt als onderdeel van de verbindingsreeks is verplicht. De juiste syntaxis is:

Server=tcp:FQDN [,poort]

Waar:

• FQDN is de Fully Qualified Domain Name van het eindpunt.
• Poort is de TCP-poort van het eindpunt. 1433 Standaard wordt ervan uitgegaan.

Notitie

Andere vormen van het opgeven van het netwerkeindpunt worden niet ondersteund. U kunt bijvoorbeeld het voorvoegsel tcp: niet weglaten, hoewel dit wel mogelijk is wanneer u programmatisch de SQL-clientbibliotheken gebruikt.

Deze mogelijkheid wordt niet ondersteund in Azure Monitor