sql_request-plugin-program

Plugin-programmet sql_request skickar en SQL-fråga till en SQL Server nätverksslutpunkt och returnerar resultatet. Om fler än en raduppsättning returneras av SQL används bara den första. Plugin-programmet anropas med operatorn evaluate .

Syntax

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

Läs mer om syntaxkonventioner.

Parametrar

Namn	Typ	Obligatorisk	Beskrivning
Connectionstring	string	✔️	Den anslutningssträng som pekar på SQL Server nätverksslutpunkt. Se giltiga autentiseringsmetoder och hur du anger nätverksslutpunkten.
SqlQuery	string	✔️	Frågan som ska köras mot SQL-slutpunkten. Frågan måste returnera en eller flera raduppsättningar, men endast den första görs tillgänglig för resten av Kusto-frågan.
SqlParameters	dynamic		En egenskapsuppsättning med nyckel/värde-par som ska skickas som parametrar tillsammans med frågan.
Alternativ	dynamic		En egenskapsuppsättning med nyckel/värde-par för att skicka mer avancerade inställningar tillsammans med frågan. För närvarande kan endast token anges för att skicka en anropare som tillhandahålls Microsoft Entra åtkomsttoken som vidarebefordras till SQL-slutpunkten för autentisering.
OutputSchema	string		Namn och typer för de förväntade kolumnerna i plugin-programmets sql_request utdata. Använd följande syntax: (ColumnName:ColumnType [, ...] ).

Anteckning

• Vi rekommenderar att du anger OutputSchema eftersom det gör att plugin-programmet kan användas i scenarier som annars inte fungerar utan det, till exempel en fråga mellan kluster. OutputSchema kan också aktivera flera frågeoptimeringar.
• Ett fel utlöses om körningsschemat för den första raduppsättningen som returneras av SQL-nätverksslutpunkten inte matchar OutputSchema-schemat .

Autentisering och auktorisering

Plugin-programmet sql_request stöder följande tre autentiseringsmetoder för SQL Server-slutpunkten.

Autentiseringsmetod	Syntax	Hur	Description
Microsoft Entra integrerad	Authentication="Active Directory Integrated"	Lägg till i parametern ConnectionString .	Det här är den föredragna autentiseringsmetoden. Användaren eller programmet autentiseras via Microsoft Entra ID till klustret och samma token används för att komma åt SQL Server nätverksslutpunkt. Huvudkontot måste ha rätt behörigheter för SQL-resursen för att utföra den begärda åtgärden. Om du till exempel vill läsa från databasen behöver huvudkontot tabell SELECT-behörigheter och för att skriva till en befintlig tabell behöver huvudkontot UPDATE- och INSERT-behörigheter. För att skriva till en ny tabell krävs även CREATE-behörigheter.
Användarnamn och lösenord	User ID=...; Password=...;	Lägg till i parametern ConnectionString .	Undvik den här metoden när det är möjligt eftersom den kan vara mindre säker.
Microsoft Entra åtkomsttoken	dynamic({'token': h"eyJ0..."})	Lägg till parametern Alternativ .	Åtkomsttoken skickas som token egenskap i argumentet Alternativ för plugin-programmet.

Anteckning

Anslutningssträngar och frågor som innehåller konfidentiell information eller information som ska skyddas bör döljas för att utelämnas från kusto-spårning. Mer information finns i dolda strängliteraraler.

Exempel

Skicka en SQL-fråga med hjälp av Microsoft Entra integrerad autentisering

I följande exempel skickas en SQL-fråga till en Azure SQL DB-databas. Den hämtar alla poster från [dbo].[Table]och bearbetar sedan resultaten på Kusto-sidan. Autentisering återanvänder den anropande användarens Microsoft Entra token.

Anteckning

Det här exemplet bör inte användas som en rekommendation för att filtrera eller projektdata på det här sättet. SQL-frågor bör konstrueras för att returnera den minsta möjliga datamängden.

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

Skicka en SQL-fråga med hjälp av autentisering med användarnamn/lösenord

Följande exempel är identiskt med det föregående, förutom att SQL-autentisering görs med användarnamn/lösenord. För konfidentialitet använder vi dolda strängar här.

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

Skicka en SQL-fråga med hjälp av en Microsoft Entra åtkomsttoken

I följande exempel skickas en SQL-fråga till en Azure SQL databas som hämtar alla poster från [dbo].[Table]och lägger till en annan datetime kolumn och bearbetar sedan resultaten på Kusto-sidan. Den anger en SQL-parameter (@param0) som ska användas i SQL-frågan.

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

Skicka en SQL-fråga utan ett frågedefinierat utdataschema

I följande exempel skickas en SQL-fråga till en Azure SQL databas utan ett utdataschema. Detta rekommenderas inte om inte schemat är okänt, eftersom det kan påverka frågans prestanda

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

Kryptering och servervalidering

Följande anslutningsegenskaper framtvingas vid anslutning till en SQL Server nätverksslutpunkt av säkerhetsskäl.

• Encrypt villkorslöst true .
• TrustServerCertificate villkorslöst false .

Därför måste SQL Server konfigureras med ett giltigt SSL/TLS-servercertifikat.

Ange nätverksslutpunkten

Det är obligatoriskt att ange SQL-nätverksslutpunkten som en del av anslutningssträng. Lämplig syntax är:

Server=tcp:FQDN [,port]

Plats:

• FQDN är slutpunktens fullständigt kvalificerade domännamn.
• Port är TCP-porten för slutpunkten. Som standard 1433 antas.

Anteckning

Andra former av att ange nätverksslutpunkten stöds inte. Man kan till exempel inte utelämna prefixet tcp: även om det går att göra det när du använder SQL-klientbiblioteken programmatiskt.

Den här funktionen stöds inte i Azure Monitor