Dela via

sql_request-plugin

Gäller för: ✅Microsoft Fabric✅Azure Data Explorer

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

Syntax

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

Läs mer om syntaxkonventioner.

Parameterar

Namn Typ Krävs Beskrivning
ConnectionString (AnslutningSträng) string ✔️ Anslutningssträngen som pekar på SQL Server-nätverksslutpunkten. 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 Microsoft Entra-åtkomsttoken som tillhandahålls av anroparen och som vidarebefordras till SQL-slutpunkten för autentisering.
OutputSchema string Namn och typer för de förväntade kolumnerna i sql_request plugin-utdata. Använd följande syntax: (ColumnName:ColumnType [, ...] ).

Anmärkning

  • Att ange OutputSchema rekommenderas starkt 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 uppstår 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 till SQL Server-slutpunkten.

Autentiseringsmetod Syntax Hur Beskrivning
Microsoft Entra integrerat Authentication="Active Directory Integrated" Lägg till parametern ConnectionString . Användaren eller programmet autentiserar via Microsoft Entra-ID till klustret och samma token används för att komma åt SQL Server-nätverksslutpunkten.
Huvudkontot måste ha rätt behörighet för SQL-resursen för att utföra den begärda åtgärden. Om du till exempel vill läsa från databasen måste huvudnamnet ha tabell-SELECT-behörigheter och för att kunna skriva till en befintlig tabell behöver huvudnamnet UPDATE- och INSERT-behörigheter. Om du vill skriva till en ny tabell krävs även CREATE-behörigheter.
Hanterad identitet Authentication="Active Directory Managed Identity";User Id={object_id} Lägg till parametern ConnectionString . Begäran körs för en hanterad identitet. Den hanterade identiteten måste ha rätt behörighet för SQL-resursen för att utföra den begärda åtgärden.
Om du vill aktivera hanterad identitetsautentisering måste du lägga till den hanterade identiteten i klustret och ändra principen för hanterad identitet. Mer information finns i Hanterad identitetsprincip.
Användarnamn och lösenord User ID=...; Password=...; Lägg till 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.
Autentiseringsmetod Syntax Hur Beskrivning
Microsoft Entra integrerat Authentication="Active Directory Integrated" Lägg till parametern ConnectionString . Användaren eller programmet autentiserar via Microsoft Entra-ID till klustret och samma token används för att komma åt SQL Server-nätverksslutpunkten.
Huvudkontot måste ha rätt behörighet för SQL-resursen för att utföra den begärda åtgärden. Om du till exempel vill läsa från databasen måste huvudnamnet ha tabell-SELECT-behörigheter och för att kunna skriva till en befintlig tabell behöver huvudnamnet UPDATE- och INSERT-behörigheter. Om du vill skriva till en ny tabell krävs även CREATE-behörigheter.
Användarnamn och lösenord User ID=...; Password=...; Lägg till 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.

Anmärkning

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 kustospårning. Mer information finns i dolda strängliteraler.

Exempel

Skicka en SQL-fråga med 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.

Anmärkning

Det här exemplet bör inte användas som en rekommendation för att filtrera eller projicera data 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 fördunklade 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], medan du 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 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 serververifiering

Följande anslutningsegenskaper tvingas när du ansluter till en SQL Server-nätverksslutpunkt av säkerhetsskäl.

  • Encrypt är inställd på true villkorslöst.
  • TrustServerCertificate är inställd på false villkorslöst.

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ängen. Lämplig syntax är:

Server = tcp: FQDN [,Port]

Var:

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

Anmärkning

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