sql_request 플러그 인

적용 대상: ✅Microsoft Fabric✅Azure Data Explorer

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

구문

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

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

매개 변수

이름	Type	필수	설명
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 엔드포인트에 대한 다음 세 가지 인증 방법을 지원합니다.

인증 방법	구문	방법	설명
Microsoft Entra 통합	Authentication="Active Directory Integrated"	ConnectionString 매개 변수에 추가합니다.	사용자 또는 애플리케이션은 Microsoft Entra ID를 통해 클러스터에 인증하고 동일한 토큰을 사용하여 SQL Server 네트워크 엔드포인트에 액세스합니다. 요청된 작업을 수행하려면 보안 주체에 SQL 리소스에 대한 적절한 권한이 있어야 합니다. 예를 들어 데이터베이스에서 읽기 위해 보안 주체에는 SELECT 테이블 권한이 필요하고 기존 테이블에 쓰려면 보안 주체에 UPDATE 및 INSERT 권한이 필요합니다. 새 테이블에 쓰려면 CREATE 권한도 필요합니다.
관리 ID	Authentication="Active Directory Managed Identity";User Id={object_id}	ConnectionString 매개 변수에 추가합니다.	요청은 관리 ID를 대신하여 실행됩니다. 요청된 작업을 수행하려면 관리 ID에 SQL 리소스에 대한 적절한 권한이 있어야 합니다. 관리 ID 인증을 사용하도록 설정하려면 클러스터에 관리 ID를 추가하고 관리 ID 정책을 변경해야 합니다. 자세한 내용은 관리 ID 정책을 참조하세요.
사용자 이름 및 암호	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: 사를 생략할 수 없습니다.