Partilhar via

Gerir auditoria de bases de dados SQL com a API REST

Aplica-se a:✅Base de dados SQL em Microsoft Fabric

Pode usar a API REST do Fabric para visualizar e configurar as definições de auditoria da base de dados SQL de forma programática. A API de definições de auditoria SQL é uma API ao nível da base de dados que opera em bases de dados SQL individuais. Ao combinar a API com scripts PowerShell, pode gerir a auditoria de forma consistente em todas as bases de dados num espaço de trabalho.

Este artigo demonstra como usar o PowerShell e a API REST das definições de auditoria SQL ao nível da base de dados para recuperar e atualizar as definições de auditoria para bases de dados SQL num espaço de trabalho Fabric.

Pré-requisitos

Auditoria dos endpoints da API REST

A API de definições de auditoria SQL fornece duas operações para gerir auditorias em bases de dados SQL individuais:

Funcionamento Método URI
Obtenha definições de auditoria SQL GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{sqlDatabaseId}/settings/sqlAudit
Atualizar as definições de auditoria SQL PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{sqlDatabaseId}/settings/sqlAudit

A operação Get requer SQLDatabase.Read.All, SQLDatabase.ReadWrite.All, Item.Read.All, ou Item.ReadWrite.All âmbito delegado. A operação Atualização requer âmbito delegado SQLDatabase.ReadWrite.All ou Item.ReadWrite.All. Ambas as operações suportam identidades de utilizador, principais de serviço e identidades geridas.

Propriedades das configurações de auditoria

O objeto de definições de auditoria inclui as seguintes propriedades:

Propriedade Tipo Descrição
auditActionsAndGroups string[] Auditar ações e grupos a serem capturados. Padrão: BATCH_COMPLETED_GROUP, FAILED_DATABASE_AUTHENTICATION_GROUP, SUCCESSFUL_DATABASE_AUTHENTICATION_GROUP.
predicateExpression cadeia (de caracteres) Uma expressão de predicado T-SQL usada para filtrar eventos de auditoria. Por exemplo, statement not like '[select ]%' exclui as instruções SELECT.
retentionDays número inteiro Número de dias para manter registos de auditoria. 0 indica retenção indefinida.
state cadeia (de caracteres) Estado de auditoria: Enabled ou Disabled. Quando ativas a auditoria pela primeira vez sem especificar outras propriedades, o sistema usa valores por defeito.
storageEndpoint cadeia (de caracteres) (Só leitura) O endpoint de armazenamento OneLake que armazena registos de auditoria.

Veja as definições de auditoria para todas as bases de dados num espaço de trabalho

O script PowerShell seguinte lista todas as bases de dados SQL num espaço de trabalho e recupera a configuração de auditoria para cada base de dados.

No script a seguir, substitua <your workspace id> pelo ID do espaço de trabalho Fabric. Podes encontrar o ID de um espaço de trabalho no URL, é a string única dentro de dois / caracteres depois /groups/ na janela do teu navegador. Por exemplo, 00001111-aaaa-2222-bbbb-3333cccc4444 em 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

Configurar a auditoria para todas as bases de dados num espaço de trabalho

Depois de rever o estado atual da auditoria, utilize o seguinte script para configurar a auditoria de forma consistente em todas as bases de dados de um espaço de trabalho.

Substitua <your workspace id> pelo ID do espaço de trabalho do Fabric. Modifica o $auditPayload objeto para corresponder à configuração de auditoria que desejas.

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)"
    }
}

Melhores práticas

  • Recupere sempre as definições atuais de auditoria com uma solicitação GET antes de atualizar com PATCH, para compreender a configuração existente.
  • Tratar falhas por base de dados. Se uma atualização da base de dados falhar, continue a processar as bases de dados restantes.
  • Retente falhas transitórias individualmente em vez de repetir todo o script de atualização em massa.
  • Use um principal de serviço ou identidade gerida para configurações automatizadas ou agendadas de auditoria em ambientes de produção.

Conteúdo relacionado

  • Last updated on