Modul plug-in sql_request

  • Článek

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer

Modul sql_request plug-in odešle dotaz SQL do koncového bodu sítě Azure SQL Serveru 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 .

Syntaxe

evaluatesql_request ( ConnectionString SqlQuery [, SqlParameters [, Options]] ) [: OutputSchema] ,

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

Parametry

Název Type Požadováno Popis
Připojovací řetězec string ✔️ Připojovací řetězec, která odkazuje na koncový bod sítě SQL Serveru. Prohlédněte si platné metody ověřování a způsob určení koncového bodu sítě.
SqlQuery string ✔️ Dotaz, který se má spustit na koncovém bodu SQL. Dotaz musí vrátit jednu nebo více sad řádků, ale pro zbytek dotazu Kusto je k dispozici pouze první sada řádků.
SqlParameters dynamic Sada vlastností párů klíč-hodnota, které se mají předat 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 pro předání přístupového tokenu Microsoft Entra poskytnutého volajícím, který se předá koncovému bodu SQL pro ověřování.
OutputSchema string Názvy a typy očekávaných sloupců výstupu sql_request modulu plug-in. Použijte následující syntaxi: ( ColumnName : ColumnType [, ...] ).

Poznámka:

  • Zadání outputSchema je vysoce doporučeno, protože umožňuje použití modulu plug-in ve scénářích, které by jinak bez něj nemusely fungovat, například dotaz mezi clustery. OutputSchema může také povolit více optimalizací dotazů.
  • Pokud schéma spuštění první sady řádků vrácené koncovým bodem sítě SQL neodpovídá schématu OutputSchema , vyvolá se chyba.

Ověřování a autorizace

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

Metoda ověřování Syntaxe Jak Popis
Integrovaná aplikace Microsoft Entra Authentication="Active Directory Integrated" Přidejte do parametru ConnectionString . Uživatel nebo aplikace se ověřuje přes Microsoft Entra ID vašeho clusteru a stejný token se používá pro přístup ke koncovému bodu sítě SQL Serveru.
Aby mohl objekt zabezpečení provést požadovanou akci, musí mít příslušná oprávnění k prostředku SQL. Například ke čtení z databáze potřebuje objekt zabezpečení oprávnění SELECT tabulky a k zápisu do existující tabulky potřebuje objekt zabezpečení oprávnění UPDATE a INSERT. K zápisu do nové tabulky se vyžadují také oprávnění CREATE.
Spravovaná identita Authentication="Active Directory Managed Identity";User Id={object_id} Přidejte do parametru ConnectionString . Žádost se provede jménem spravované identity. Aby bylo možné provést požadovanou akci, musí mít spravovaná identita odpovídající oprávnění k prostředku SQL.
Pokud chcete povolit ověřování spravovaných identit, musíte do clusteru přidat spravovanou identitu a změnit zásady spravované identity. Další informace najdete v tématu Zásady spravované identity.
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ě zabezpečená.
Přístupový token Microsoft Entra dynamic({'token': h"eyJ0..."}) Přidejte do parametru Options . 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ěny, by měly být vynechány z jakéhokoli trasování Kusto. Další informace najdete v obfuskovaných řetězcových literálech.

Příklady

Odeslání dotazu SQL pomocí 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žívá token Microsoft Entra volajícího uživatele.

Poznámka:

Tento příklad by se neměl brát jako doporučení k filtrování nebo projektování dat tímto způsobem. Dotazy SQL by se měly vytvořit tak, aby vrátily 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 stejný jako předchozí, s tím rozdílem, že ověřování SQL se provádí pomocí uživatelského jména a hesla. Pro důvěrnost 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á načítá všechny záznamy z [dbo].[Table], při připojení jiného datetime sloupce a poté 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 schématu výstupu 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 schéma není neznámé, protože 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

Ověřování šifrování a serveru

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

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

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

Zadání koncového bodu sítě

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

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

Kde:

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

Poznámka:

Jiné formy zadávání koncového bodu sítě se nepodporují. Nelze například vynechat předponu tcp: , i když je to možné provést při programovém použití klientských knihoven SQL.