sql_request, wtyczka

Wtyczka sql_request wysyła zapytanie SQL do punktu końcowego sieci 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 o konwencjach składniowych.

Parametry

Nazwa	Typ	Wymagane	Opis
Connectionstring	string	✔️	Parametry połączenia wskazujący punkt końcowy sieci 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 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ść do przekazywania bardziej zaawansowanych ustawień wraz z zapytaniem. Obecnie można ustawić tylko token przekazywanie dostarczonego przez obiekt wywołujący Microsoft Entra tokenu dostępu, który jest 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, takie 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 SQL Server.

Metoda uwierzytelniania	Składnia	Jak	Opis
integracja Microsoft Entra	Authentication="Active Directory Integrated"	Dodaj do parametru ConnectionString .	Jest to preferowana metoda uwierzytelniania. Użytkownik lub aplikacja uwierzytelnia się za pośrednictwem Tożsamość Microsoft Entra w klastrze, a ten sam token jest używany do uzyskiwania dostępu do punktu końcowego sieci SQL Server. Podmiot zabezpieczeń musi mieć odpowiednie uprawnienia do zasobu SQL, aby wykonać żądaną akcję. Na przykład do odczytu z bazy danych podmiot zabezpieczeń wymaga uprawnień SELECT tabeli, a do zapisu w istniejącej tabeli podmiot zabezpieczeń wymaga uprawnień UPDATE i INSERT. Aby zapisać w nowej tabeli, wymagane są również uprawnienia CREATE.
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.
Microsoft Entra token dostępu	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 być zaciemnione, aby zostały 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 Microsoft Entra

Poniższy przykład wysyła zapytanie SQL do bazy danych 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 projekcji danych 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 Microsoft Entra

Poniższy przykład wysyła zapytanie SQL do bazy danych Azure SQL pobierania wszystkich rekordów z [dbo].[Table]elementu , dołączając kolejną datetime kolumnę, a następnie przetwarza wyniki po stronie usługi Kusto. Określa parametr SQL (@param0), który ma być używany 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 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 SQL Server ze względów bezpieczeństwa.

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

W związku z tym SQL Server należy skonfigurować 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 pominąć na przykład prefiksu tcp: , mimo że można to zrobić w przypadku programowego używania bibliotek klienta SQL.

Ta funkcja nie jest obsługiwana w usłudze Azure Monitor