Condividi tramite

Gestire il controllo del database SQL con l'API REST

si applica a:✅database SQL in Microsoft Fabric

È possibile usare l'API REST Fabric per visualizzare e configurare le impostazioni di controllo del database SQL programmaticamente. L'API delle impostazioni di controllo SQL è un'API a livello di database che opera su singoli database SQL. Combinando l'API con gli script di PowerShell, è possibile gestire il controllo in modo coerente in tutti i database in un'area di lavoro.

Questo articolo illustra come usare PowerShell e l'API REST delle impostazioni di audit SQL a livello di database per recuperare e aggiornare le impostazioni di audit per i database SQL in un workspace Fabric.

Prerequisiti

Controllo degli endpoint dell'API REST

L'API delle impostazioni di controllo SQL offre due operazioni per la gestione del controllo nei singoli database SQL:

Operation metodo URI (Identificatore Uniforme delle Risorse)
Recuperare le impostazioni di controllo SQL GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{sqlDatabaseId}/settings/sqlAudit
Aggiornare le impostazioni di controllo SQL PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{sqlDatabaseId}/settings/sqlAudit

L'operazione Get richiede uno tra SQLDatabase.Read.All, SQLDatabase.ReadWrite.All, Item.Read.All o Item.ReadWrite.All come ambiti delegati. L'operazione di aggiornamento richiede l'ambito delegato SQLDatabase.ReadWrite.All o Item.ReadWrite.All. Entrambe le operazioni supportano identità utente, entità servizio e identità gestite.

Proprietà delle impostazioni di controllo

L'oggetto impostazioni di controllo include le proprietà seguenti:

Proprietà Tipo Descrizione
auditActionsAndGroups string[] Controlla azioni e gruppi da acquisire. Impostazione predefinita: BATCH_COMPLETED_GROUP, FAILED_DATABASE_AUTHENTICATION_GROUP, SUCCESSFUL_DATABASE_AUTHENTICATION_GROUP.
predicateExpression corda Espressione di predicato T-SQL usata per filtrare gli eventi di controllo. Ad esempio, statement not like '[select ]%' esclude le istruzioni SELECT.
retentionDays numero intero Numero di giorni per conservare i log di controllo. 0 indica la conservazione illimitata.
state corda Stato di controllo: Enabled o Disabled. Quando si abilita il controllo per la prima volta senza specificare altre proprietà, il sistema usa i valori predefiniti.
storageEndpoint corda (Sola lettura) Endpoint di archiviazione OneLake in cui sono archiviati i log di controllo.

Visualizzare le impostazioni di controllo per tutti i database in un'area di lavoro

Lo script di PowerShell seguente elenca tutti i database SQL in un'area di lavoro e recupera la configurazione di controllo per ogni database.

Nel seguente script, sostituire <your workspace id> con l'ID dell'area di lavoro Fabric. È possibile trovare l'ID di un'area di lavoro nell'URL, è la stringa univoca all'interno di due / caratteri dopo /groups/ nella finestra del browser. Ad esempio, 00001111-aaaa-2222-bbbb-3333cccc4444 in https://fabric.microsoft.com/groups/00001111-aaaa-2222-bbbb-3333cccc4444/.

Import-Module Az.Accounts

Connect-AzAccount

$workspaceId = '<your workspace id>'
$baseUri = "https://api.fabric.microsoft.com"

# Obtain an access token
$token = (Get-AzAccessToken -ResourceUrl "https://api.fabric.microsoft.com")
$secureToken = $token.Token | ConvertFrom-SecureString -AsPlainText

$headers = @{
    "Authorization" = "Bearer $secureToken"
    "Content-Type"  = "application/json"
}

# List all SQL databases in the workspace
$databasesUri = "$baseUri/v1/workspaces/$workspaceId/sqlDatabases"
$databases = @()
$continuationToken = $null

do {
    $url = $databasesUri
    if ($continuationToken) {
        $encoded = [System.Web.HttpUtility]::UrlEncode($continuationToken)
        $url = "$url`?continuationToken=$encoded"
    }
    $response = Invoke-RestMethod -Method GET -Uri $url -Headers $headers
    if ($response.value) { $databases += $response.value }
    $continuationToken = $response.continuationToken
} while ($continuationToken)

Write-Host "Found $($databases.Count) SQL databases."

# Retrieve audit settings for each database
$results = @()

foreach ($db in $databases) {
    try {
        $auditUri = "$baseUri/v1/workspaces/$workspaceId/sqlDatabases/$($db.id)/settings/sqlAudit"
        $audit = Invoke-RestMethod -Method GET -Uri $auditUri -Headers $headers

        $results += [PSCustomObject]@{
            DatabaseName        = $db.displayName
            DatabaseId          = $db.id
            State               = $audit.state
            RetentionDays       = $audit.retentionDays
            AuditActionsAndGroups = ($audit.auditActionsAndGroups -join "; ")
            PredicateExpression = $audit.predicateExpression
        }
    }
    catch {
        $results += [PSCustomObject]@{
            DatabaseName        = $db.displayName
            DatabaseId          = $db.id
            State               = "ERROR"
            RetentionDays       = ""
            AuditActionsAndGroups = ""
            PredicateExpression = $_.Exception.Message
        }
    }
}

$results | Format-Table -AutoSize

Configurare il controllo per tutti i database in un'area di lavoro

Dopo aver esaminato lo stato di controllo corrente, usare lo script seguente per configurare il controllo in modo coerente in tutti i database in un'area di lavoro.

Sostituire <your workspace id> con l'ID dell'area di lavoro Fabric. Modificare l'oggetto $auditPayload in modo che corrisponda alla configurazione di controllo desiderata.

Import-Module Az.Accounts

Connect-AzAccount

$workspaceId = '<your workspace id>'
$baseUri = "https://api.fabric.microsoft.com"

# Obtain an access token
$token = (Get-AzAccessToken -ResourceUrl "https://api.fabric.microsoft.com")
$secureToken = $token.Token | ConvertFrom-SecureString -AsPlainText

$headers = @{
    "Authorization" = "Bearer $secureToken"
    "Content-Type"  = "application/json"
}

# Define the audit configuration to apply
$auditPayload = @{
    state                = "Enabled"
    auditActionsAndGroups = @(
        "BATCH_COMPLETED_GROUP",
        "FAILED_DATABASE_AUTHENTICATION_GROUP",
        "SUCCESSFUL_DATABASE_AUTHENTICATION_GROUP"
    )
    retentionDays        = 10
    predicateExpression  = "statement not like '[select ]%'"
} | ConvertTo-Json -Depth 5

# List all SQL databases in the workspace
$databasesUri = "$baseUri/v1/workspaces/$workspaceId/sqlDatabases"
$databases = @()
$continuationToken = $null

do {
    $url = $databasesUri
    if ($continuationToken) {
        $encoded = [System.Web.HttpUtility]::UrlEncode($continuationToken)
        $url = "$url`?continuationToken=$encoded"
    }
    $response = Invoke-RestMethod -Method GET -Uri $url -Headers $headers
    if ($response.value) { $databases += $response.value }
    $continuationToken = $response.continuationToken
} while ($continuationToken)

Write-Host "Configuring auditing for $($databases.Count) SQL databases..."

foreach ($db in $databases) {
    try {
        $auditUri = "$baseUri/v1/workspaces/$workspaceId/sqlDatabases/$($db.id)/settings/sqlAudit"
        Invoke-RestMethod -Method PATCH -Uri $auditUri -Headers $headers -Body $auditPayload | Out-Null
        Write-Host "[OK] Updated auditing for: $($db.displayName)"
    }
    catch {
        Write-Host "[FAIL] $($db.displayName): $($_.Exception.Message)"
    }
}

Procedure consigliate

  • Recuperare sempre le impostazioni di controllo correnti con una GET richiesta prima di eseguire l'aggiornamento con PATCHper comprendere la configurazione esistente.
  • Gestire gli errori per ogni database. Se un aggiornamento del database non riesce, continuare a elaborare i database rimanenti.
  • Ripetere singolarmente i tentativi per errori temporanei invece di eseguire nuovamente l'intero script di aggiornamento in blocco.
  • Usare un'entità servizio o un'identità gestita per la configurazione di controllo automatizzata o pianificata negli ambienti di produzione.

Contenuti correlati

  • Last updated on