Como configurar pools SQL personalizados usando a API REST do Fabric

Aplica-se a: ✅ ponto de análise SQL e Armazém em Microsoft Fabric

Pools SQL personalizados dão aos administradores mais controlo sobre como os recursos são alocados para tratar pedidos. Neste arranque rápido, vai configurar pools SQL personalizados e observar os valores do classificador usando a API REST do Fabric.

Os administradores do espaço de trabalho podem usar o nome da aplicação (ou nome do programa) da cadeia de ligação para encaminhar pedidos para diferentes pools de computação. Os administradores de espaços de trabalho também podem controlar a percentagem de recursos a que cada pool SQL de computação pode aceder, com base no limite de escala expansível da capacidade do espaço de trabalho.

A API REST do Fabric define um endpoint unificado para operações.

Pré-requisitos

Acesso a um artigo de armazém num espaço de trabalho. Deves ser membro do cargo de Administrador.

Obter a configuração atual

Use a seguinte API para obter a configuração atual.

Exemplo do Fabric Notebook

Pode executar o exemplo seguinte de código Python num caderno Fabric Spark.

O código envia um GET pedido para a API de configuração personalizada do pool SQL e devolve a configuração personalizada do pool SQL para o espaço de trabalho.
O workspace_id campo usa o mssparkutils.runtime.context para obter o GUID do espaço de trabalho em que o bloco de notas é executado. Para configurar um pool SQL personalizado num espaço de trabalho diferente, atualize para workspace_id o GUID do espaço de trabalho onde pretende configurar os pools SQL personalizados.

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)

Configurar pools SQL personalizados

O exemplo seguinte em Python permite e configura pools SQL personalizados. Podes executar este código Python num caderno Spark do Fabric.

A configuração personalizada dos pools SQL só está ativa quando customSQLPoolsEnabled o atributo está definido como true. Podes definir uma carga útil na definição do customSQLPools objeto, mas se não definires o customSQLPoolsEnabled como true, a carga útil é ignorada e a gestão autónoma da carga de trabalho é utilizada.
O código configura dois pools SQL personalizados, ContosoSQLPool e AdhocPool.
- O ContosoSQLPool está configurado para receber 70% dos recursos disponíveis. O classificador de nome de aplicação tem o valor de MyContosoApp.
- Todas as consultas SQL que provêm de uma string de ligação que especifica o MyContosoApp nome da aplicação são classificadas para o ContosoSQLPool pool SQL personalizado e têm acesso a 70% do total de nós com capacidade expansível.
- Todas as consultas SQL que não contêm MyContosoApp no nome da aplicação da string de ligação são enviadas para o Adhoc pool SQL personalizado, que é definido como o pool default. Estes pedidos têm acesso a 30% dos nós totais de capacidade explosiva.
Todas as configurações personalizadas de pool SQL devem ter um Pool SQL predefinido identificado ao definir o isDefault atributo como true.
A soma de todos maxResourcePercentage os valores deve ser menor ou igual a 100%.
O workspace_id campo usa o mssparkutils.runtime.context para obter o GUID do espaço de trabalho em que o bloco de notas é executado. Para configurar um pool SQL personalizado num espaço de trabalho diferente, atualize para workspace_id o GUID do espaço de trabalho onde pretende configurar os pools SQL personalizados.

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)

Sugestão

Use estes úteis valores de classificador Nome da Aplicação (regex) para tráfego proveniente do Fabric.

Para classificar consultas em pipelines Fabric, use ^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}$.
Para classificar consultas do Power BI, use ^(PowerBIPremium-DirectQuery|Mashup Engine(?: $PowerBIPremium-Import$)?).
Para classificar consultas a partir do editor SQL do portal Fabric, use DMS_user.

Definir o nome da aplicação no SQL Server Management Studio (SSMS)

O classificador para pools SQL personalizados utiliza o nome da aplicação ou o parâmetro do nome do programa em strings de conexão comuns.

No SQL Server Management Studio (SSMS), especifique o nome do servidor para o armazém e forneça a autenticação. Recomenda-se o Microsoft Entra MFA .
Selecione o botão Avançado .
Na página de Propriedades Avançadas , em Contexto, altere o valor do Nome da Aplicação para MyContosoApp.
Selecione OK.
Selecione Conectar.
Para gerar alguma atividade de exemplo, use esta ligação no SSMS para executar uma consulta simples no seu armazém, por exemplo:
```
SELECT *
FROM dbo.DimDate;
```

Observe informações de consulta para o pool SQL personalizado

Revise a sys.dm_exec_sessions vista de gestão dinâmica para ver que MyContosoApp está a ser reconhecido como o nome da aplicação passado do SSMS para o motor SQL.
```
SELECT session_id, program_name
FROM   sys.dm_exec_sessions
WHERE  program_name = 'MyContosoApp';
```
Por exemplo:
Como corresponde program_name ao nome da aplicação no MyContosoApp pool SQL personalizado, esta consulta utiliza os recursos desse pool. Para provar que pool SQL personalizado a consulta utilizou, pode consultar a vista do sistema queryinsights.exec_requests_history . Espere 10-15 minutos para que os insights da consulta apareçam e depois execute a consulta seguinte.
```
SELECT distributed_statement_id, submit_time, 
       program_name, sql_pool_name, start_time, end_time
FROM   queryinsights.exec_requests_history 
WHERE  program_name = 'MyContosoApp';
```
Também pode identificar o pool de uma consulta pelo seu ID de Declaração. No editor de consultas SQL do portal Fabric, executa uma consulta no seu armazém ou endpoint de análise SQL.
```
SELECT *
FROM dbo.DimDate;
```
Selecione o separador Mensagens e anote o ID de Declaração para a execução da consulta. No editor de consultas SQL, o program_name é DMS_user, que configuraste para usar o MyContosoApp pool SQL personalizado anteriormente.
Espere 10-15 minutos para que os insights de consulta apareçam.

Recupere a sql_pool_name e outras informações para verificar se o pool SQL personalizado correto foi utilizado.

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>';

Reverter a configuração personalizada dos pools SQL

Para devolver o espaço de trabalho ao estado original, altere a customSQLPoolsEnabled propriedade para False. Se pretende preservar a configuração personalizada dos pools SQL, é necessário passar cada nome de pool conforme apresentado na lista customSQLPools.

Este exemplo de código Python desativa pools SQL personalizados e reverte para a configuração autónoma de gestão de carga de trabalho de SELECT e pools não personalizadas SELECT. Um pedido é invocado com a propriedade PATCH definida como customSQLPoolsEnabled.

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)

Comentários

Esta página foi útil?

Last updated on 2026-03-18