Delen via

sql_request-invoegtoepassing

Van toepassing op: ✅Microsoft Fabric✅Azure Data Explorer-

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

Syntaxis

evaluate sql_request ( ConnectionString,SqlQuery [,SqlParameters [,Opties]] ) [:OutputSchema]

Meer informatie over syntaxisconventies.

Parameterwaarden

Naam Typologie Verplicht Beschrijving
ConnectionString- string ✔️ De verbindingsreeks die verwijst naar het SQL Server-netwerkeindpunt. Bekijk 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 is beschikbaar 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 geavanceerdere instellingen door te geven, samen met de query. Momenteel kan alleen token worden ingesteld om een door de aanroeper verstrekte 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 [, ...] ).

Opmerking

  • Het opgeven van het OutputSchema wordt ten zeerste aanbevolen, omdat de invoegtoepassing kan worden gebruikt in scenario's die anders niet werken zonder, zoals een query voor 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 .

Authenticatie en autorisatie

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

Verificatiemethode Syntaxis Hoe Beschrijving
Microsoft Entra geïntegreerd Authentication="Active Directory Integrated" Toevoegen aan de parameter ConnectionString . De gebruiker of toepassing wordt geverifieerd via Microsoft Entra-id voor uw cluster en hetzelfde token wordt gebruikt voor toegang tot het SQL Server-netwerkeindpunt.
De principal moet over de juiste machtigingen voor de SQL-resource beschikken om de aangevraagde actie uit te voeren. Als u bijvoorbeeld wilt lezen uit de database, heeft de principal select-machtigingen nodig voor de tabel en om naar een bestaande tabel te schrijven waarvoor de principal UPDATE- en INSERT-machtigingen nodig heeft. Als u naar een nieuwe tabel wilt schrijven, zijn ook CREATE-machtigingen vereist.
Beheerde identiteit Authentication="Active Directory Managed Identity";User Id={object_id} Toevoegen aan de parameter ConnectionString . De aanvraag wordt uitgevoerd namens een beheerde identiteit. De beheerde identiteit moet over de juiste machtigingen voor de SQL-resource beschikken om de aangevraagde actie uit te voeren.
Als u verificatie van beheerde identiteiten wilt inschakelen, moet u de beheerde identiteit toevoegen aan uw cluster en het beleid voor beheerde identiteiten wijzigen. Zie Managed Identity-beleid voor meer informatie.
Gebruikersnaam en wachtwoord User ID=...; Password=...; Toevoegen 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.
Verificatiemethode Syntaxis Hoe Beschrijving
Microsoft Entra geïntegreerd Authentication="Active Directory Integrated" Toevoegen aan de parameter ConnectionString . De gebruiker of toepassing wordt geverifieerd via Microsoft Entra-id voor uw cluster en hetzelfde token wordt gebruikt voor toegang tot het SQL Server-netwerkeindpunt.
De principal moet over de juiste machtigingen voor de SQL-resource beschikken om de aangevraagde actie uit te voeren. Als u bijvoorbeeld wilt lezen uit de database, heeft de principal select-machtigingen nodig voor de tabel en om naar een bestaande tabel te schrijven waarvoor de principal UPDATE- en INSERT-machtigingen nodig heeft. Als u naar een nieuwe tabel wilt schrijven, zijn ook CREATE-machtigingen vereist.
Gebruikersnaam en wachtwoord User ID=...; Password=...; Toevoegen 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.

Opmerking

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

Voorbeelden

Een SQL-query verzenden met geïntegreerde Microsoft Entra-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. Verificatie hergebruikt het Microsoft Entra-token van de aanroepende gebruiker.

Opmerking

Dit voorbeeld mag niet worden gebruikt als aanbeveling om gegevens op deze manier te filteren of te projecteren. SQL-query's moeten worden samengesteld om de kleinste 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 de vorige, behalve dat SQL-verificatie wordt uitgevoerd met een 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 waarmee alle records worden opgehaald, [dbo].[Table]terwijl u een andere datetime kolom toevoegt en vervolgens de resultaten aan de Kusto-zijde verwerkt. Hiermee geeft u een SQL-parameter (@param0) op 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 een 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 gedwongen wanneer u verbinding maakt met een SQL Server-netwerkeindpunt, om veiligheidsredenen.

  • Encrypt is ingesteld op true voorwaardelijke.
  • TrustServerCertificate is ingesteld op false voorwaardelijke.

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 volledig gekwalificeerde domeinnaam van het eindpunt.
  • Poort is de TCP-poort van het eindpunt. Standaard wordt ervan uitgegaan dat 1433.

Opmerking

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