Compartir a través de

Administración de la auditoría de SQL Database con la API REST

Se aplica a:✅Base de datos SQL en Microsoft Fabric

Puede usar la API REST de Fabric para ver y configurar las opciones de auditoría de SQL Database mediante programación. La API de configuración de auditoría de SQL es una API de nivel de base de datos que funciona en bases de datos SQL individuales. Al combinar la API con scripts de PowerShell, puede administrar la auditoría de forma coherente en todas las bases de datos de un área de trabajo.

En este artículo se muestra cómo usar PowerShell y la API REST de la configuración de auditoría de SQL de nivel de base de datos para recuperar y actualizar la configuración de auditoría de las bases de datos SQL en un área de trabajo de Fabric.

Prerrequisitos

Auditoría de puntos de conexión de la API REST

La API de configuración de auditoría de SQL proporciona dos operaciones para administrar la auditoría en bases de datos SQL individuales:

Operación Método URI
Obtención de la configuración de auditoría de SQL GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{sqlDatabaseId}/settings/sqlAudit
Actualización de la configuración de auditoría de SQL PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{sqlDatabaseId}/settings/sqlAudit

La operación Get requiere SQLDatabase.Read.All, SQLDatabase.ReadWrite.All, Item.Read.All o Item.ReadWrite.All, alguno de los siguientes ámbitos delegados. La operación de actualización requiere SQLDatabase.ReadWrite.All o Item.ReadWrite.All ámbito delegado. Ambas operaciones admiten identidades de usuario, entidades de servicio e identidades administradas.

Propiedades de configuración de auditoría

El objeto de configuración de auditoría incluye las siguientes propiedades:

Propiedad Tipo Descripción
auditActionsAndGroups string[] Auditar acciones y grupos para capturar. Valor predeterminado: BATCH_COMPLETED_GROUP, FAILED_DATABASE_AUTHENTICATION_GROUP, SUCCESSFUL_DATABASE_AUTHENTICATION_GROUP.
predicateExpression cuerda / cadena Expresión de predicado de T-SQL que se usa para filtrar eventos de auditoría. Por ejemplo, statement not like '[select ]%' excluye instrucciones SELECT.
retentionDays entero Número de días para conservar los registros de auditoría. 0 indica la retención indefinida.
state cuerda / cadena Estado de auditoría: Enabled o Disabled. Al habilitar la auditoría por primera vez sin especificar otras propiedades, el sistema usa valores predeterminados.
storageEndpoint cuerda / cadena (Solo lectura) El punto de conexión de almacenamiento de OneLake que almacena los registros de auditoría.

Visualización de la configuración de auditoría de todas las bases de datos de un área de trabajo

El siguiente script de PowerShell enumera todas las bases de datos SQL de un área de trabajo y recupera la configuración de auditoría de cada base de datos.

En el script siguiente, reemplace por <your workspace id> el identificador del área de trabajo de Fabric. Puede encontrar el identificador de un área de trabajo en la dirección URL, es la cadena única dentro de dos / caracteres después /groups/ en la ventana del explorador. Por ejemplo, 00001111-aaaa-2222-bbbb-3333cccc4444 en 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

Configuración de la auditoría de todas las bases de datos de un área de trabajo

Después de revisar el estado de auditoría actual, use el siguiente script para configurar la auditoría de forma coherente en todas las bases de datos de un área de trabajo.

Reemplace por <your workspace id> el identificador del área de trabajo de Fabric. Modifique el $auditPayload objeto para que coincida con la configuración de auditoría deseada.

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

procedimientos recomendados

  • Recupere siempre la configuración de auditoría actual con una GET solicitud antes de actualizar con PATCH, para comprender la configuración existente.
  • Controlar errores por base de datos. Si se produce un error en una actualización de la base de datos, continúe procesando las bases de datos restantes.
  • Vuelva a intentar errores transitorios individualmente en lugar de volver a ejecutar todo el script de actualización masiva.
  • Utilice un principal de servicio o una identidad administrada para la configuración de auditoría automatizada o programada en entornos de producción.

Contenido relacionado

  • Last updated on