패브릭 REST API를 사용하여 사용자 지정 SQL 풀을 구성하는 방법

적용 대상: ✅ Microsoft Fabric의 SQL 분석 엔드포인트 및 웨어하우스

사용자 지정 SQL 풀을 사용하면 관리자가 요청을 처리하기 위해 리소스를 할당하는 방법을 더 자세히 제어할 수 있습니다. 이 빠른 시작에서는 사용자 지정 SQL 풀을 구성하고 Fabric REST API를 사용하여 분류자 값을 관찰합니다.

작업 영역 관리자는 연결 문자열의 애플리케이션 이름(또는 프로그램 이름)을 사용하여 요청을 다른 컴퓨팅 풀로 라우팅할 수 있습니다. 작업 영역 관리자는 작업 영역 용량의 버스트 가능한 확장 제한에 따라 각 컴퓨팅 SQL 풀에서 액세스할 수 있는 리소스의 비율을 제어할 수도 있습니다.

Fabric REST API는 작업에 대한 통합 엔드포인트를 정의합니다.

사전 요구 사항

작업 영역의 웨어하우스 항목에 액세스합니다. 관리자 역할의 구성원이어야 합니다.

현재 구성 가져오기

다음 API를 사용하여 현재 구성을 가져옵니다.

패브릭 노트북 예제

Fabric Spark Notebook에서 다음 예제 Python 코드를 실행할 수 있습니다.

코드는 사용자 지정 SQL 풀 구성 API에 요청을 보내고 GET 작업 영역에 대한 사용자 지정 SQL 풀 구성을 반환합니다.
이 workspace_id 필드는 Notebook이 실행되는 작업 영역의 GUID를 가져오는 데 mssparkutils.runtime.context을 사용합니다. 다른 작업 영역에서 사용자 지정 SQL 풀을 구성하려면, workspace_id을(를) 사용자 지정 SQL 풀을 구성하고자 하는 작업 영역의 GUID로 업데이트해야 합니다.

import requests
import json
from notebookutils import mssparkutils

# This will get the workspace_id where this notebook is running. 
# Update to the workspace_id (guid) if running this notebook outside of the workspace where the warehouse exists.
workspaceId = mssparkutils.runtime.context.get('currentWorkspaceId') 

url = f'https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses/sqlPoolsConfiguration?beta=true'
response = requests.request(method='get', url=url, headers={'Authorization': f'Bearer {mssparkutils.credentials.getToken("pbi")}'})

if response.status_code == 200:
    print(json.dumps(response.json(), indent=4))
else:
    print(response.text)

사용자 지정 SQL 풀 구성

다음 Python 예제에서는 사용자 지정 SQL 풀을 사용하도록 설정하고 구성합니다. Fabric Spark Notebook에서 이 Python 코드를 실행할 수 있습니다.

사용자 지정 SQL 풀 구성은 customSQLPoolsEnabled 특성이 true로 설정된 경우에만 활성화됩니다. 개체 정의에서 customSQLPools 페이로드를 정의할 수 있지만 customSQLPoolsEnabled 를 true로 설정하지 않으면 페이로드가 무시되고 자율 워크로드 관리 가 사용됩니다.
이 코드는 두 개의 사용자 지정 SQL 풀, ContosoSQLPool 및 AdhocPool을(를) 구성합니다.
- ContosoSQLPool 사용 가능한 리소스의 70% 받도록 설정됩니다. 애플리케이션 이름 분류자의 값은 .입니다 MyContosoApp.
- 애플리케이션 이름을 지정 MyContosoApp 하는 연결 문자열에서 제공되는 모든 SQL 쿼리는 사용자 지정 SQL 풀로 ContosoSQLPool 분류되며 버스트 가능한 용량의 총 노드 중 70개% 액세스할 수 있습니다.
- 연결 문자열의 애플리케이션 이름에 포함되지 MyContosoApp 않은 모든 SQL 쿼리는 기본 풀로 정의된 사용자 지정 SQL 풀로 전송 Adhoc 됩니다. 이러한 요청은 버스트 가능한 용량의 총 노드의 30%에 액세스합니다.
모든 사용자 지정 SQL 풀 구성에는 특성을 true로 설정하여 식별된 하나의 기본 SQL 풀이 isDefault 있어야 합니다.
모든 maxResourcePercentage 값의 합계는%100보다 작거나 같아야 합니다.
workspace_id 필드는 mssparkutils.runtime.context을 사용하여 Notebook이 실행되는 작업 영역의 GUID를 가져옵니다. 사용자 지정 SQL 풀을 다른 작업 영역에 구성하려면, workspace_id를 구성하려는 작업 영역의 GUID로 업데이트하세요.

import requests
import json
from notebookutils import mssparkutils

body = { 
  "customSQLPoolsEnabled": True, 
  "customSQLPools": [ 
    { 
      "name": "ContosoSQLPool", 
      "isDefault": False, 
      "maxResourcePercentage": 70,
      "optimizeForReads": False, 
      "classifier": { 
        "type": "Application Name", 
        "value": [ 
          "MyContosoApp"
        ] 
      } 
    }, 
    { 
      "name": "AdhocPool", 
      "isDefault": True, 
      "maxResourcePercentage": 30,
      "optimizeForReads": True
    } 
  ] 
}

# This will get the workspaceId where this notebook is running. 
# Update to the workspace_id (guid) if running this notebook outside of the workspace where the warehouse exists.
workspace_id = mssparkutils.runtime.context.get('currentWorkspaceId') 

url = f'https://api.fabric.microsoft.com/v1/workspaces/{workspace_id}/warehouses/sqlPoolsConfiguration?beta=true'
response = requests.request(method='patch', url=url, json=body, headers={'Authorization': f'Bearer {mssparkutils.credentials.getToken("pbi")}'})

if response.status_code == 200:
    print("SQL Custom Pools configured successfully.")
else:
    print(response.text)

팁 (조언)

Fabric의 트래픽에 대해 다음과 같은 유용한 애플리케이션 이름(regex) 분류자 값을 사용합니다.

패브릭 파이프라인에서 쿼리를 분류하려면 .를 사용합니다 ^Data Integration-to[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
Power BI에서 쿼리를 분류하려면 .를 사용합니다 ^(PowerBIPremium-DirectQuery|Mashup Engine(?: $PowerBIPremium-Import$)?).
Fabric Portal SQL 쿼리 편집기에서 쿼리를 분류하려면 .를 사용합니다DMS_user.

SSMS(SQL Server Management Studio)에서 애플리케이션 이름 설정

사용자 지정 SQL 풀의 분류자는 공통 연결 문자열의 애플리케이션 이름 또는 프로그램 이름 매개 변수를 사용합니다.

SSMS(SQL Server Management Studio)에서 웨어하우스의 서버 이름을 지정하고 인증을 제공합니다. Microsoft Entra MFA 를 사용하는 것이 좋습니다.
고급 단추를 선택합니다.
고급 속성 페이지의 컨텍스트에서 애플리케이션 이름의MyContosoApp값을 .로 변경합니다.
확인을 선택합니다.
연결을 선택합니다.
일부 샘플 작업을 생성하려면 SSMS에서 이 연결을 사용하여 웨어하우스에서 간단한 쿼리를 실행합니다. 예를 들면 다음과 같습니다.
```
SELECT *
FROM dbo.DimDate;
```

사용자 지정 SQL 풀에 대한 쿼리 인사이트 관찰

sys.dm_exec_sessions 동적 관리 뷰를 검토하여 MyContosoApp가 SSMS에서 SQL 엔진으로 전달된 애플리케이션 이름으로 인식되고 있는지 확인합니다.
```
SELECT session_id, program_name
FROM   sys.dm_exec_sessions
WHERE  program_name = 'MyContosoApp';
```
다음은 그 예입니다.
program_name 사용자 지정 SQL 풀의 MyContosoApp 애플리케이션 이름과 일치하므로 이 쿼리는 해당 풀의 리소스를 사용합니다. 쿼리에서 사용한 사용자 지정 SQL 풀을 증명하기 위해 queryinsights.exec_requests_history 시스템 뷰를 쿼리할 수 있습니다. 쿼리 인사이트가 채워지도록 10-15분 동안 기다린 다음, 다음 쿼리를 실행합니다.
```
SELECT distributed_statement_id, submit_time, 
       program_name, sql_pool_name, start_time, end_time
FROM   queryinsights.exec_requests_history 
WHERE  program_name = 'MyContosoApp';
```
문 ID로 쿼리 풀을 식별할 수도 있습니다. 패브릭 포털 SQL 쿼리 편집기에서 웨어하우스 또는 SQL 분석 엔드포인트에 대해 쿼리를 실행합니다.
```
SELECT *
FROM dbo.DimDate;
```
메시지 탭을 선택하고 쿼리 실행에 대한 문 ID를 기록합니다. SQL 쿼리 편집기 program_name에서 이전에 사용자 지정 SQL 풀 MyContosoApp을(를) 사용하도록 구성한 DMS_user입니다.
쿼리 인사이트가 채워지도록 10-15분 동안 기다립니다.

sql_pool_name 적절한 사용자 지정 SQL 풀이 사용되었는지 확인하기 위해 기타 정보를 검색합니다.

SELECT distributed_statement_id, submit_time, 
       program_name, sql_pool_name, start_time, end_time
FROM   queryinsights.exec_requests_history 
WHERE  distributed_statement_id = '<Statement ID>';

사용자 지정 SQL 풀 구성 되돌리기

작업 영역을 원래 상태로 되돌리려면 속성을 customSQLPoolsEnabled.로 변경 False 합니다. 사용자 지정 SQL 풀 구성을 유지하려면 목록과 같이 customSQLPools 각 풀 이름을 전달해야 합니다.

이 예제 Python 코드는 사용자 지정 SQL 풀을 비활성화하고 SELECT 자율 워크로드 관리 구성 및 SELECT이 아닌 풀로 되돌립니다. PATCH 요청이 customSQLPoolsEnabled 속성이 False로 설정된 상태로 호출됩니다.

import requests
import json
from notebookutils import mssparkutils

body = { 
  "customSQLPoolsEnabled": False, 
  "customSQLPools": [] 
}

# This will get the workspaceId where this notebook is running. 
# Update to the workspace_id (guid) if running this notebook outside of the workspace where the warehouse exists.
workspace_id = mssparkutils.runtime.context.get('currentWorkspaceId') 

url = f'https://api.fabric.microsoft.com/v1/workspaces/{workspace_id}/warehouses/sqlPoolsConfiguration?beta=true'
response = requests.request(method='patch', url=url, json=body, headers={'Authorization': f'Bearer {mssparkutils.credentials.getToken("pbi")}'})

if response.status_code == 200:
    print("SQL Custom Pools successfully disabled.")
else:
    print(response.text)

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-03-18