Konfigurieren von benutzerdefinierten SQL-Pools mithilfe der Fabric-REST-API

Gilt für: ✅ SQL-Analyseendpunkt und Warehouse in Microsoft Fabric

Benutzerdefinierte SQL-Pools bieten Administratoren mehr Kontrolle darüber, wie Ressourcen für die Verarbeitung von Anforderungen zugeordnet werden. In dieser Schnellstartanleitung konfigurieren Sie benutzerdefinierte SQL-Pools und beobachten die Klassifiziererwerte mithilfe der Fabric-REST-API.

Arbeitsbereichsadministratoren können den Anwendungsnamen (oder Programmnamen) aus der Verbindungszeichenfolge verwenden, um Anforderungen an verschiedene Computepools weiterzuleiten. Arbeitsbereichsadministratoren können auch den Prozentsatz der Ressourcen steuern, auf die jeder SQL-Pool zugreifen kann, unter Berücksichtigung der dynamischen Skalierungsgrenze der Arbeitsbereichskapazität.

Die Fabric-REST-API definiert einen einheitlichen Endpunkt für Vorgänge.

Voraussetzungen

• Zugriff auf ein Lagerelement in einem Arbeitsbereich. Sie sollten der Administratorrolle angehören.

Erhalten der aktuellen Konfiguration

Verwenden Sie die folgende API, um die aktuelle Konfiguration abzurufen.

Fabric-Notizbuch (Beispiel)

Sie können den folgenden Python-Beispielcode in einem Fabric Spark-Notizbuch ausführen.

• Der Code sendet eine GET Anforderung an die benutzerdefinierte SQL-Poolkonfigurations-API und gibt die benutzerdefinierte SQL-Poolkonfiguration für den Arbeitsbereich zurück.
• Das workspace_id Feld verwendet das mssparkutils.runtime.context, um die GUID des Arbeitsbereichs zu erhalten, in dem das Notizbuch ausgeführt wird. Um einen benutzerdefinierten SQL-Pool in einem anderen Arbeitsbereich zu konfigurieren, aktualisieren Sie die workspace_id GUID des Arbeitsbereichs, in dem Sie die benutzerdefinierten SQL-Pools konfigurieren möchten.

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)

Konfigurieren von benutzerdefinierten SQL-Pools

Im folgenden Python-Beispiel werden benutzerdefinierte SQL-Pools aktiviert und konfiguriert. Sie können diesen Python-Code in einem Fabric Spark-Notizbuch ausführen.

• Die Konfiguration benutzerdefinierter SQL-Pools ist nur aktiv, wenn customSQLPoolsEnabled das Attribut auf "true" festgelegt ist. Sie können eine Nutzlast in der customSQLPools Objektdefinition definieren, aber wenn Sie "customSQLPoolsEnabled " nicht auf "true" festlegen, wird die Nutzlast ignoriert und die autonome Workloadverwaltung verwendet.
• Der Code konfiguriert zwei benutzerdefinierte SQL-Pools ContosoSQLPool und AdhocPool.
  • Die ContosoSQLPool Option ist so festgelegt, dass 70% der verfügbaren Ressourcen empfangen werden. Der Klassifizierer "Anwendungsname" hat den Wert von MyContosoApp.
  • Alle SQL-Abfragen, die aus einer Verbindungszeichenfolge stammen, die den MyContosoApp Anwendungsnamen angibt, werden in den ContosoSQLPool benutzerdefinierten SQL-Pool klassifiziert und haben Zugriff auf 70% der Gesamtknoten der platzfähigen Kapazität.
  • Alle SQL-Abfragen, die nicht im Anwendungsnamen der Verbindungszeichenfolge enthalten MyContosoApp sind, werden an den Adhoc benutzerdefinierten SQL-Pool gesendet, der als Standardpool definiert ist. Diese Anfragen erhalten Zugriff auf 30% der Gesamtknoten der burstfähigen Kapazität.
• Alle benutzerdefinierten SQL-Poolkonfigurationen müssen über einen SQL-Standardpool verfügen, der durch Festlegen des isDefault Attributs auf "true" identifiziert wird.
• Die Summe aller maxResourcePercentage Werte muss kleiner oder gleich 100%sein.
• Das workspace_id Feld verwendet das mssparkutils.runtime.context, um die GUID des Arbeitsbereichs zu erhalten, in dem das Notizbuch ausgeführt wird. Um einen benutzerdefinierten SQL-Pool in einem anderen Arbeitsbereich zu konfigurieren, aktualisieren Sie die workspace_id GUID des Arbeitsbereichs, in dem Sie die benutzerdefinierten SQL-Pools konfigurieren möchten.

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)

Festlegen des Anwendungsnamens in SQL Server Management Studio (SSMS)

Der Klassifizierer für benutzerdefinierte SQL-Pools verwendet den Anwendungsnamen oder den Programmnamenparameter allgemeiner Verbindungszeichenfolgen.

1. Geben Sie in SQL Server Management Studio (SSMS) den Servernamen für das Lager an und stellen Sie die Authentifizierung bereit. Microsoft Entra MFA wird empfohlen.

2. Wählen Sie die Schaltfläche "Erweitert " aus.

3. Ändern Sie auf der Seite "Erweiterte Eigenschaften " unter "Kontext" den Wert des Anwendungsnamens in MyContosoApp.

   

4. Wählen Sie OK aus.

5. Wählen Sie Verbinden aus.

6. Um einige Beispielaktivitäten zu generieren, verwenden Sie diese Verbindung in SSMS, um eine einfache Abfrage in Ihrem Lager auszuführen, z. B.:

   SELECT *
   FROM dbo.DimDate;
   

Einblicke in Abfragen des benutzerdefinierten SQL-Pools beobachten

1. Überprüfen Sie die sys.dm_exec_sessions dynamische Verwaltungsansicht, um zu sehen, dass MyContosoApp als der Anwendungsname erkannt wird, der von SSMS an das SQL-Modul übergeben wird.

   SELECT session_id, program_name
   FROM   sys.dm_exec_sessions
   WHERE  program_name = 'MyContosoApp';
   

   Beispiel:

   

2. Da der program_name Anwendungsname im MyContosoApp benutzerdefinierten SQL-Pool übereinstimmt, verwendet diese Abfrage die Ressourcen in diesem Pool. Um zu beweisen, welchen benutzerdefinierten SQL-Pool die Abfrage verwendet hat, können Sie die queryinsights.exec_requests_history Systemansicht abfragen. Warten Sie 10 bis 15 Minuten, bis Abfrageerkenntnisse aufgefüllt werden, und führen Sie dann die folgende Abfrage aus.

   SELECT distributed_statement_id, submit_time, 
          program_name, sql_pool_name, start_time, end_time
   FROM   queryinsights.exec_requests_history 
   WHERE  program_name = 'MyContosoApp';
   

3. Sie können den Pool einer Abfrage auch anhand ihrer Anweisungs-ID identifizieren. Führen Sie im SQL-Abfrage-Editor des Fabric-Portals eine Abfrage für Ihren Warehouse- oder SQL-Analyseendpunkt aus.

   SELECT *
   FROM dbo.DimDate;
   

4. Wählen Sie die Registerkarte "Nachrichten" aus, und notieren Sie die Statement-ID für die Abfrageausführung. Im SQL-Abfrage-Editor ist das program_nameDMS_user, das Sie zuvor so konfiguriert haben, dass es den benutzerdefinierten SQL-Pool MyContosoApp verwendet.

5. Warten Sie 10-15 Minuten, bis die Abfrageergebnisse verfügbar sind.

6. Rufen Sie die sql_pool_name und andere Informationen ab, um zu überprüfen, ob der richtige benutzerdefinierte SQL-Pool verwendet wurde.

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

Wiederherstellen der Konfiguration von benutzerdefinierten SQL-Pools

Um den Arbeitsbereich in den ursprünglichen Zustand zurückzugeben, ändern Sie die customSQLPoolsEnabled Eigenschaft in False. Wenn Sie die Konfiguration benutzerdefinierter SQL-Pools beibehalten möchten, müssen Sie jeden Poolnamen wie in der customSQLPools Liste übergeben.

In diesem Beispiel-Python-Code werden benutzerdefinierte SQL-Pools deaktiviert und auf die autonome Workloadverwaltungskonfiguration von SELECT und nicht-SELECT-Pools zurückgesetzt. Eine PATCH Anforderung wird aufgerufen, wobei die Eigenschaft customSQLPoolsEnabled auf False gesetzt ist.

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)

Verwandte Inhalte

• Benutzerdefinierte SQL-Pools
• SQL Pools-Konfigurations-API
• Workload-Verwaltung