sql_request, wtyczka

Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer

Wtyczka sql_request wysyła zapytanie SQL do punktu końcowego sieci programu Azure SQL Server i zwraca wyniki. Jeśli program SQL zwraca więcej niż jeden zestaw wierszy, używany jest tylko pierwszy zestaw wierszy. Wtyczka jest wywoływana z operatorem evaluate .

Składnia

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

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko	Type	Wymagania	opis
ConnectionString	string	✔️	Parametry połączenia wskazujący punkt końcowy sieci programu SQL Server. Zobacz prawidłowe metody uwierzytelniania i sposób określania punktu końcowego sieci.
Zapytanie sql	string	✔️	Zapytanie, które ma zostać wykonane względem punktu końcowego SQL. Zapytanie musi zwrócić co najmniej jeden zestaw wierszy, ale tylko pierwszy z nich jest dostępny dla pozostałej części zapytania Kusto.
Parametry sql	dynamic		Torba właściwości par klucz-wartość do przekazania jako parametry wraz z zapytaniem.
Opcje	dynamic		Torba właściwości par klucz-wartość, aby przekazać bardziej zaawansowane ustawienia wraz z zapytaniem. Obecnie można ustawić tylko token wartość , aby przekazać dostarczony przez obiekt wywołujący token dostępu firmy Microsoft Entra przekazywany do punktu końcowego SQL na potrzeby uwierzytelniania.
OutputSchema	string		Nazwy i typy oczekiwanych kolumn danych wyjściowych sql_request wtyczki. Użyj następującej składni: ( ColumnName : ColumnType [, ...] ).

Uwaga

• Określenie parametru OutputSchema jest zdecydowanie zalecane, ponieważ umożliwia użycie wtyczki w scenariuszach, które w przeciwnym razie mogą nie działać bez niego, takich jak zapytanie między klastrami. Moduł OutputSchema może również włączyć wiele optymalizacji zapytań.
• Błąd jest zgłaszany, jeśli schemat czasu wykonywania pierwszego zestawu wierszy zwrócony przez punkt końcowy sieci SQL nie jest zgodny ze schematem OutputSchema .

Uwierzytelnianie i autoryzacja

Wtyczka sql_request obsługuje następujące trzy metody uwierzytelniania do punktu końcowego programu SQL Server.

Metoda uwierzytelniania	Składnia	Jak	opis
Microsoft Entra integrated	Authentication="Active Directory Integrated"	Dodaj do parametru ConnectionString .	Użytkownik lub aplikacja uwierzytelnia się za pośrednictwem identyfikatora Entra firmy Microsoft w klastrze, a ten sam token jest używany do uzyskiwania dostępu do punktu końcowego sieci programu SQL Server. Podmiot zabezpieczeń musi mieć odpowiednie uprawnienia do zasobu SQL, aby wykonać żądaną akcję. Na przykład aby odczytać z bazy danych podmiot zabezpieczeń wymaga uprawnień SELECT tabeli, a zapis do istniejącej tabeli wymaga uprawnień UPDATE i INSERT. Aby zapisać w nowej tabeli, wymagane są również uprawnienia CREATE.
Tożsamość zarządzana	Authentication="Active Directory Managed Identity";User Id={object_id}	Dodaj do parametru ConnectionString .	Żądanie jest wykonywane w imieniu tożsamości zarządzanej. Tożsamość zarządzana musi mieć odpowiednie uprawnienia do zasobu SQL, aby wykonać żądaną akcję. Aby włączyć uwierzytelnianie tożsamości zarządzanej, należy dodać tożsamość zarządzaną do klastra i zmienić zasady tożsamości zarządzanej. Aby uzyskać więcej informacji, zobacz Zasady tożsamości zarządzanej.
Nazwa użytkownika i hasło	User ID=...; Password=...;	Dodaj do parametru ConnectionString .	Jeśli to możliwe, należy unikać tej metody, ponieważ może być mniej bezpieczna.
Token dostępu firmy Microsoft Entra	dynamic({'token': h"eyJ0..."})	Dodaj parametr Opcje .	Token dostępu jest przekazywany jako token właściwość w argumencie Opcje wtyczki.

Uwaga

Parametry połączenia i zapytania zawierające poufne informacje lub informacje, które powinny być chronione, powinny zostać pominięte z dowolnego śledzenia Usługi Kusto. Aby uzyskać więcej informacji, zobacz zaciemnione literały ciągu.

Przykłady

Wysyłanie zapytania SQL przy użyciu zintegrowanego uwierzytelniania firmy Microsoft

Poniższy przykład wysyła zapytanie SQL do bazy danych usługi Azure SQL DB. Pobiera wszystkie rekordy z [dbo].[Table]elementu , a następnie przetwarza wyniki po stronie usługi Kusto. Uwierzytelnianie ponownie używa tokenu Microsoft Entra użytkownika wywołującego.

Uwaga

Ten przykład nie powinien być traktowany jako zalecenie dotyczące filtrowania lub filtrowania danych projektu w ten sposób. Zapytania SQL powinny być konstruowane w celu zwrócenia najmniejszego możliwego zestawu danych.

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

Wysyłanie zapytania SQL przy użyciu uwierzytelniania nazwy użytkownika/hasła

Poniższy przykład jest identyczny z poprzednim, z tą różnicą, że uwierzytelnianie SQL odbywa się przy użyciu nazwy użytkownika/hasła. W celu zachowania poufności używamy tutaj zaciemnionych ciągów.

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

Wysyłanie zapytania SQL przy użyciu tokenu dostępu firmy Microsoft Entra

Poniższy przykład wysyła zapytanie SQL do bazy danych Azure SQL Database, która pobiera wszystkie rekordy z [dbo].[Table]usługi , dołączając kolejną datetime kolumnę, a następnie przetwarza wyniki po stronie usługi Kusto. Określa parametr SQL (@param0) do użycia w zapytaniu 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

Wysyłanie zapytania SQL bez schematu danych wyjściowych zdefiniowanych przez zapytanie

Poniższy przykład wysyła zapytanie SQL do bazy danych Azure SQL Database bez schematu wyjściowego. Nie jest to zalecane, chyba że schemat jest nieznany, ponieważ może to mieć wpływ na wydajność zapytania

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

Szyfrowanie i walidacja serwera

Następujące właściwości połączenia są wymuszane podczas nawiązywania połączenia z punktem końcowym sieci programu SQL Server ze względów bezpieczeństwa.

• Encrypt jest ustawiona true bezwarunkowo.
• TrustServerCertificate jest ustawiona false bezwarunkowo.

W związku z tym program SQL Server musi być skonfigurowany przy użyciu prawidłowego certyfikatu serwera SSL/TLS.

Określanie punktu końcowego sieci

Określenie punktu końcowego sieci SQL w ramach parametry połączenia jest obowiązkowe. Odpowiednią składnią jest:

Server= tcp: Nazwa FQDN [, Port]

Gdzie:

• Nazwa FQDN jest w pełni kwalifikowaną nazwą domeny punktu końcowego.
• Port to port TCP punktu końcowego. Domyślnie przyjmuje się założenie 1433 .

Uwaga

Inne formy określania punktu końcowego sieci nie są obsługiwane. Nie można na przykład pominąć prefiksu tcp: , mimo że można to zrobić programowo przy użyciu bibliotek klienckich SQL.