Modul plug-in sql_request

Modul sql_request plug-in odešle dotaz SQL do SQL Server koncového bodu sítě a vrátí výsledky. Pokud SQL vrátí více než jednu sadu řádků, použije se pouze první sada řádků. Modul plug-in se vyvolá pomocí operátoru evaluate .

Syntax

evaluatesql_request(Connectionstring,SqlQuery [,SqlParameters [,Možnosti]] ) [:OutputSchema]

Přečtěte si další informace o konvencích syntaxe.

Parametry

Název	Typ	Vyžadováno	Popis
Connectionstring	string	✔️	Připojovací řetězec, která ukazuje na koncový bod SQL Server sítě. Projděte si platné metody ověřování a postup zadání koncového bodu sítě.
SqlQuery	string	✔️	Dotaz, který se má spustit proti koncovému bodu SQL. Dotaz musí vrátit jednu nebo více sad řádků, ale pro zbytek dotazu Kusto je k dispozici pouze první.
Parametry SQL	dynamic		Balíček vlastností párů klíč-hodnota, které se předávají jako parametry spolu s dotazem.
Možnosti	dynamic		Sada vlastností párů klíč-hodnota pro předávání pokročilejších nastavení spolu s dotazem. V současné době je možné nastavit pouze token předání volajícího Microsoft Entra přístupového tokenu, který se předá koncovému bodu SQL k ověření.
OutputSchema	string		Názvy a typy očekávaných sloupců výstupu modulu plug-in sql_request Použijte následující syntaxi: (ColumnName:ColumnType [, ...] ).

Poznámka

• Důrazně doporučujeme zadat OutputSchema , protože umožňuje použití modulu plug-in ve scénářích, které by bez něj jinak nemusely fungovat, jako je dotaz mezi clustery. OutputSchema může také povolit více optimalizací dotazů.
• Pokud schéma za běhu sady prvního řádku vrácené koncovým bodem sítě SQL neodpovídá schématu OutputSchema , dojde k chybě.

Ověřování a autorizace

Modul plug-in sql_request podporuje následující tři metody ověřování koncového bodu SQL Server.

Metoda ověřování	Syntax	Jak	Description
Microsoft Entra integrovaná	Authentication="Active Directory Integrated"	Přidejte do parametru ConnectionString .	Toto je upřednostňovaná metoda ověřování. Uživatel nebo aplikace se ověřuje prostřednictvím Microsoft Entra ID do vašeho clusteru a stejný token se používá pro přístup ke koncovému bodu sítě SQL Server. Objekt zabezpečení musí mít příslušná oprávnění k prostředku SQL, aby mohl provést požadovanou akci. Například pro čtení z databáze objekt zabezpečení potřebuje oprávnění SELECT tabulky a k zápisu do existující tabulky potřebuje objekt zabezpečení oprávnění UPDATE a INSERT. Pokud chcete zapisovat do nové tabulky, vyžadují se také oprávnění CREATE.
Uživatelské jméno a heslo	User ID=...; Password=...;	Přidejte do parametru ConnectionString .	Pokud je to možné, vyhněte se této metodě, protože může být méně bezpečná.
Microsoft Entra přístupové tokeny	dynamic({'token': h"eyJ0..."})	Přidejte parametr Možnosti .	Přístupový token se předává jako token vlastnost v argumentu Options modulu plug-in.

Poznámka

Připojovací řetězce a dotazy, které obsahují důvěrné informace nebo informace, které by měly být chráněné, by měly být obfuskovány, aby se z trasování Kusto vynechaly. Další informace najdete v tématu obfuskované řetězcové literály.

Příklady

Odeslání dotazu SQL s využitím integrovaného ověřování Microsoft Entra

Následující příklad odešle dotaz SQL do databáze Azure SQL DB. Načte všechny záznamy z [dbo].[Table]a pak zpracuje výsledky na straně Kusto. Ověřování znovu použije token Microsoft Entra volajícího uživatele.

Poznámka

Tento příklad by neměl být považován za doporučení k filtrování nebo projektování dat tímto způsobem. Dotazy SQL by se měly vytvořit tak, aby vracely nejmenší možnou datovou sadu.

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

Odeslání dotazu SQL pomocí ověřování pomocí uživatelského jména a hesla

Následující příklad je shodný s předchozím příkladem s tím rozdílem, že ověřování SQL se provádí pomocí uživatelského jména a hesla. Kvůli důvěrnosti zde používáme obfuskované řetězce.

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

Odeslání dotazu SQL pomocí přístupového tokenu Microsoft Entra

Následující příklad odešle dotaz SQL do databáze Azure SQL, která při připojení dalšího datetime sloupce načte všechny záznamy z [dbo].[Table], a pak zpracuje výsledky na straně Kusto. Určuje parametr SQL (@param0), který se má použít v dotazu 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

Odeslání dotazu SQL bez výstupního schématu definovaného dotazem

Následující příklad odešle dotaz SQL do databáze Azure SQL bez výstupního schématu. To se nedoporučuje, pokud není schéma neznámé, protože to může mít vliv na výkon dotazu.

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

Šifrování a ověření serveru

Při připojování ke koncovému bodu sítě SQL Server jsou z bezpečnostních důvodů vynucené následující vlastnosti připojení.

• Encrypt je nastavena na true bezpodmínečně.
• TrustServerCertificate je nastavena na false bezpodmínečně.

V důsledku toho musí být SQL Server nakonfigurovaný s platným certifikátem serveru SSL/TLS.

Určení koncového bodu sítě

Zadání koncového bodu sítě SQL jako součásti připojovací řetězec je povinné. Příslušná syntaxe je:

Server=tcp:Plně kvalifikovaný název domény [,port]

Kde:

• Plně kvalifikovaný název domény je plně kvalifikovaný název domény koncového bodu.
• Port je port TCP koncového bodu. Ve výchozím nastavení se 1433 předpokládá.

Poznámka

Jiné formy určení koncového bodu sítě nejsou podporovány. Nelze například vynechat předponu tcp: , i když je to možné při programovém použití klientských knihoven SQL.

Tato funkce není ve službě Azure Monitor podporována.