sql_request 플러그 인

아티클
01/10/2024

플러그 인은 sql_request SQL 쿼리를 SQL Server 네트워크 엔드포인트로 보내고 결과를 반환합니다. SQL에서 둘 이상의 행 집합을 반환하는 경우 첫 번째 행 집합만 사용됩니다. 플러그 인은 연산자를 사용하여 evaluate 호출됩니다.

Syntax

evaluatesql_request(Connectionstring,SqlQuery [,SqlParameters [,옵션]] ) [:OutputSchema]

구문 규칙에 대해 자세히 알아봅니다.

매개 변수

이름	형식	필수	Description
ConnectionString	`string`	✔️	SQL Server 네트워크 엔드포인트를 가리키는 연결 문자열. 유효한 인증 방법 및 네트워크 엔드포인트를 지정하는 방법을 참조하세요.
SqlQuery	`string`	✔️	SQL 엔드포인트에 대해 실행할 쿼리입니다. 쿼리는 하나 이상의 행 집합을 반환해야 하지만 Kusto 쿼리의 나머지 부분에는 첫 번째 행 집합만 사용할 수 있습니다.
SqlParameters	`dynamic`		쿼리와 함께 매개 변수로 전달할 키-값 쌍의 속성 모음입니다.
옵션	`dynamic`		쿼리와 함께 고급 설정을 전달하는 키-값 쌍의 속성 모음입니다. 현재는 인증을 위해 SQL 엔드포인트로 전달되는 호출자 제공 Microsoft Entra 액세스 토큰을 전달하도록 만 `token` 설정할 수 있습니다.
OutputSchema	`string`		플러그 인 출력의 예상 열에 `sql_request` 대한 이름 및 형식입니다. ColumnName`:`ColumnType [`,` ...] `)`구문을 `(` 사용합니다.

참고

OutputSchema를 지정하면 클러스터 간 쿼리와 같이 플러그 인이 작동하지 않을 수 있는 시나리오에서 플러그 인을 사용할 수 있으므로 매우 좋습니다. OutputSchema는 여러 쿼리 최적화를 사용하도록 설정할 수도 있습니다.
SQL 네트워크 엔드포인트에서 반환된 첫 번째 행 집합의 런타임 스키 마가 OutputSchema 스키마 와 일치하지 않으면 오류가 발생합니다.

인증 및 권한 부여

sql_request 플러그 인은 SQL Server 엔드포인트에 대한 다음 세 가지 인증 방법을 지원합니다.

인증 방법	Syntax	방법	Description
통합된 Microsoft Entra	`Authentication="Active Directory Integrated"`	ConnectionString 매개 변수에 를 추가합니다.	이 방법은 기본적으로 사용되는 인증 방법입니다. 사용자 또는 애플리케이션은 클러스터에 대한 Microsoft Entra ID 통해 인증하고 동일한 토큰을 사용하여 SQL Server 네트워크 엔드포인트에 액세스합니다. 보안 주체는 요청된 작업을 수행하려면 SQL 리소스에 대한 적절한 권한이 있어야 합니다. 예를 들어 데이터베이스에서 읽으려면 보안 주체에 SELECT 권한 테이블이 필요하고 기존 테이블에 쓰려면 보안 주체에 UPDATE 및 INSERT 권한이 필요합니다. 새 테이블에 쓰려면 CREATE 권한도 필요합니다.
사용자 이름 및 암호	`User ID=...; Password=...;`	ConnectionString 매개 변수에 를 추가합니다.	가능하면 보안이 떨어지면 이 메서드를 사용하지 마세요.
액세스 토큰 Microsoft Entra	`dynamic({'token': h"eyJ0..."})`	Options 매개 변수에 를 추가 합니다 .	액세스 토큰은 플러그 인의 Options 인수에서 속성으로 `token` 전달됩니다.

참고

보호해야 하는 기밀 정보 또는 정보를 포함하는 연결 문자열 및 쿼리는 Kusto 추적에서 생략되도록 난독 처리해야 합니다. 자세한 내용은 난독 처리를 한 문자열 리터럴을 참조하세요.

예제

Microsoft Entra 통합 인증을 사용하여 SQL 쿼리 보내기

다음 예제에서는 Azure SQL DB 데이터베이스에 SQL 쿼리를 보냅니다. 에서 [dbo].[Table]모든 레코드를 검색한 다음 Kusto 쪽에서 결과를 처리합니다. 인증은 호출하는 사용자의 Microsoft Entra 토큰을 다시 사용합니다.

참고

이 예제는 이러한 방식으로 데이터를 필터링하거나 프로젝트하는 권장 사항으로 간주해서는 안 됩니다. 가능한 가장 작은 데이터 세트를 반환하려면 SQL 쿼리를 생성해야 합니다.

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

사용자 이름/암호 인증을 사용하여 SQL 쿼리 보내기

다음 예제는 SQL 인증이 사용자 이름/암호로 수행된다는 점을 제외하고 이전 예제와 동일합니다. 기밀성을 위해 여기에서 난독 처리를 한 문자열을 사용합니다.

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

Microsoft Entra 액세스 토큰을 사용하여 SQL 쿼리 보내기

다음 예제에서는 다른 datetime 열을 추가하는 동안 에서 [dbo].[Table]모든 레코드를 검색하는 Azure SQL 데이터베이스에 SQL 쿼리를 보낸 다음 Kusto 쪽에서 결과를 처리합니다. SQL 쿼리에 사용할 SQL 매개 변수(@param0)를 지정합니다.

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

쿼리 정의 출력 스키마 없이 SQL 쿼리 보내기

다음 예제에서는 출력 스키마 없이 Azure SQL 데이터베이스에 SQL 쿼리를 보냅니다. 쿼리 성능에 영향을 미칠 수 있으므로 스키마를 알 수 없는 경우 권장되지 않습니다.

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

암호화 및 서버 유효성 검사

다음 연결 속성은 보안상의 이유로 SQL Server 네트워크 엔드포인트에 연결할 때 강제로 적용됩니다.

Encrypt 는 무조건 로 true 설정됩니다.
TrustServerCertificate 는 무조건 로 false 설정됩니다.

따라서 유효한 SSL/TLS 서버 인증서를 사용하여 SQL Server 구성해야 합니다.

네트워크 엔드포인트 지정

SQL 네트워크 엔드포인트를 연결 문자열 일부로 지정해야 합니다. 적합한 구문은 다음과 같습니다.

Server=tcp:FQDN [,포트]

위치:

FQDN 은 엔드포인트의 정규화된 도메인 이름입니다.
포트 는 엔드포인트의 TCP 포트입니다. 기본적으로 1433로 가정됩니다.

참고

네트워크 엔드포인트를 지정하는 다른 형식은 지원되지 않습니다. 예를 들어 SQL 클라이언트 라이브러리를 프로그래밍 방식으로 사용할 때는 접두 tcp: 사를 생략할 수 없습니다.

이 기능은 Azure Monitor에서 지원되지 않습니다.