Compartilhar via

sys.fn_get_audit_file_v2 (Transact-SQL)

Aplica-se a:Azure SQL DatabaseWarehouse no Microsoft FabricBanco de dados SQL no Microsoft Fabric

A sys.fn_get_audit_file_v2 função do sistema foi projetada para recuperar dados de logs de auditoria com maior eficiência em comparação com seu predecessor, sys.fn_get_audit_file. A função introduz filtragem baseada em tempo nos níveis de arquivo e registro, fornecendo melhorias significativas de desempenho, especialmente para consultas direcionadas a intervalos de tempo específicos.

Informações de retorno de um arquivo de auditoria criado por uma auditoria de servidor. Para obter mais informações, confira Auditoria do SQL Server (Mecanismo de Banco de Dados).

Convenções de sintaxe de Transact-SQL

Sintaxe

fn_get_audit_file_v2 ( file_pattern
    , { default | initial_file_name | NULL }
    , { default | audit_record_offset | NULL }
    , { default | start time | NULL }
    , { default | end time | NULL } )

Argumentos

file_pattern

Aplica-se a: somente Banco de Dados SQL do Azure

Especifica o diretório ou caminho e o nome de arquivo do conjunto de arquivos de auditoria que será lido. file_pattern é nvarchar(260).

Passar um caminho sem um padrão de nome de arquivo gera um erro.

Esse argumento é usado para especificar uma URL de blob (incluindo o ponto de extremidade de armazenamento e o contêiner). Embora ele não dê suporte a um curinga de asterisco, você pode usar um prefixo de nome de arquivo parcial (blob) (em vez do nome completo do blob) para coletar vários arquivos (blobs) que começam com esse prefixo. Por exemplo:

  • <Storage_endpoint>/<Container>/<ServerName>/<DatabaseName>/ - Coleta todos os arquivos de auditoria (blobs) para o banco de dados específico.

  • <Storage_endpoint>/<Container>/<ServerName>/<DatabaseName>/<AuditName>/<CreationDate>/<FileName>.xel - Coleta um arquivo de auditoria específico (BLOB).

initial_file_name

Aplica-se a: somente Banco de Dados SQL do Azure

Especifica o caminho e o nome de um arquivo especificado no conjunto de arquivos de auditoria a partir do qual iniciar a leitura dos registros de auditoria. initial_file_name é nvarchar(260).

O argumento initial_file_name deve conter entradas válidas ou deve conter o default valor or NULL .

audit_record_offset

Aplica-se a: somente Banco de Dados SQL do Azure

Especifica um local conhecido com o arquivo especificado para o initial_file_name. Quando esse argumento é usado, a função começa a ler no primeiro registro do buffer imediatamente após o deslocamento especificado.

O argumento audit_record_offset deve conter entradas válidas ou deve conter o default valor or NULL . audit_record_offset é bigint.

start_time

A hora de início da filtragem dos logs. Os registros anteriores a esse horário são excluídos.

end_time

A hora de término da filtragem dos logs. Os registros após esse período são excluídos.

Tabela retornada

A tabela a seguir descreve o conteúdo do arquivo de auditoria retornado por essa função.

Nome da coluna Tipo Descrição
event_time datetime2 Data e hora em que a ação auditável é acionada. Não permite valor nulo.
sequence_number int Rastreia a sequência de registros dentro de um único registro de auditoria que é muito grande para se ajustar no buffer de gravação das auditorias. Não permite valor nulo.
action_id varchar(4) A identificação da ação. Não permite valor nulo.
succeeded bit Indica se a ação que disparou o evento foi realizada com êxito. Não permite valor nulo. Para todos os demais eventos que não são eventos de logon, reporta somente se a verificação de permissões foi bem-sucedida ou não, e não a operação.

1 = sucesso
0 = falha
permission_bitmask varbinary(16) Em algumas ações, essa máscara de bits são as permissões que foram concedidas, negadas ou revogadas.
is_column_permission bit Sinalizador que indica se esta é uma permissão no nível de coluna. Não permite valor nulo. Retorna 0 quando opermission_bitmask = 0 .

1 = verdadeiro
0 = falso
session_id smallint Identificação da sessão em que ocorreu o evento. Não permite valor nulo.
server_principal_id int ID do contexto de logon em que a ação é executada. Não permite valor nulo.
database_principal_id int ID do contexto do usuário de banco de dados no qual a ação é executada. Não permite valor nulo. Devoluções 0 se isso não se aplicar. Por exemplo, uma operação de servidor.
target_server_principal_id int Entidade de servidor na qual a GRANT/DENY/REVOKE operação é executada. Não permite valor nulo. Devoluções 0 se não aplicável.
target_database_principal_id int A entidade de banco de dados na qual a GRANT/DENY/REVOKE operação é executada. Não permite valor nulo. Devoluções 0 se não aplicável.
object_id int A ID da entidade na qual a auditoria ocorreu, que inclui os seguintes objetos:

- Objetos de servidor
-Bancos
- Objetos de banco de dados
- Objetos de esquema

Não permite valor nulo. Retorna 0 se a entidade for o próprio servidor ou se a auditoria não for executada em um nível de objeto. Por exemplo, Autenticação.
class_type varchar(2) O tipo de entidade auditável no qual a auditoria ocorre. Não permite valor nulo.
session_server_principal_name sysname Entidade de servidor para sessão. Anulável. Retorna a identidade do logon original que foi conectado à instância do Mecanismo de Banco de Dados caso haja alternâncias de contexto explícitas ou implícitas.
server_principal_name sysname Logon atual. Anulável.
server_principal_sid varbinary SID do logon atual. Anulável.
database_principal_name sysname Usuário atual. Anulável. Devoluções NULL se não estiverem disponíveis.
target_server_principal_name sysname Logon de destino da ação. Anulável. Devoluções NULL se não aplicável.
target_server_principal_sid varbinary SID do logon de destino. Anulável. Devoluções NULL se não aplicável.
target_database_principal_name sysname Usuário de destino da ação. Anulável. Devoluções NULL se não aplicável.
server_instance_name sysname Nome da instância de servidor no qual a auditoria ocorreu. O formato padrão server\instance é usado.
database_name sysname O contexto do banco de dados no qual a ação aconteceu. Anulável. Retorna NULL para auditorias que ocorrem no nível do servidor.
schema_name sysname O contexto do esquema no qual a ação aconteceu. Anulável. Retorna NULL para auditorias que ocorrem fora de um esquema.
object_name sysname O nome da entidade na qual a auditoria ocorreu, que inclui os seguintes objetos:

- Objetos de servidor
-Bancos
- Objetos de banco de dados
- Objetos de esquema

Anulável. Retorna NULL se a entidade for o próprio servidor ou se a auditoria não for executada em um nível de objeto. Por exemplo, Autenticação.
statement nvarchar(4000) Transact-SQL, se existir. Anulável. Devoluções NULL se não aplicável.
additional_information nvarchar(4000) Informações exclusivas que se aplicam somente a um evento são retornadas como XML. Algumas ações auditáveis contêm esse tipo de informação.

Um nível de pilha T-SQL é exibido no formato XML para ações que têm a pilha T-SQL associada a elas. O formato XML é: <tsql_stack><frame nest_level = '%u' database_name = '%.*s' schema_name = '%.*s' object_name = '%.*s' /></tsql_stack>

frame nest_level indica o nível de aninhamento atual do quadro. O nome do módulo é representado em formato de três partes (database_name, schema_name, e object_name). O nome do módulo é analisado para escapar caracteres XML inválidos como <, >, /, _x. Eles escaparam como _xHHHH_. O HHHH significa o código UCS-2 hexadecimal de quatro dígitos para o caractere. Anulável. Retorna NULL quando não há informações adicionais relatadas pelo evento.
file_name varchar(260) O caminho e nome do arquivo de log de auditoria que deu origem ao registro. Não permite valor nulo.
audit_file_offset bigint O deslocamento de buffer no arquivo que contém o registro de auditoria. Não permite valor nulo.
user_defined_event_id smallint ID de evento definida pelo usuário passada como um argumento para sp_audit_write. NULL para eventos do sistema (padrão) e diferente de zero para evento definido pelo usuário. Para obter mais informações, consulte sp_audit_write (Transact-SQL).
user_defined_information nvarchar(4000) Usado para registrar qualquer informação extra que o usuário deseja registrar no log de auditoria usando o sp_audit_write procedimento armazenado.
audit_schema_version int Sempre 1.
sequence_group_id varbinary Identificador único.<
transaction_id bigint Identificador exclusivo para identificar vários eventos de auditoria em uma transação.
client_ip nvarchar(128) IP de origem do aplicativo cliente.
application_name nvarchar(128) Nome do aplicativo cliente que executou a instrução que causou o evento de auditoria.
duration_milliseconds bigint Duração da execução da consulta em milissegundos.
response_rows bigint Número de linhas retornadas no conjunto de resultados.<
affected_rows bigint Número de linhas afetadas pela instrução executada.
connection_id uniqueidentifier ID da conexão no servidor.
data_sensitivity_information nvarchar(4000) Tipos de informações e rótulos de confidencialidade retornados pela consulta auditada, com base nas colunas classificadas no banco de dados. Saiba mais sobre a descoberta e a classificação de dados do Banco de Dados SQL do Azure.
host_name nvarchar(128) Nome do host da máquina cliente.
session_context nvarchar(4000) Os pares de chave-valor que fazem parte do contexto da sessão atual.
client_tls_version bigint Versão mínima do TLS com suporte do cliente.
client_tls_version_name nvarchar(128) Versão mínima do TLS com suporte do cliente.
database_transaction_id bigint ID da transação atual na sessão atual.
ledger_start_sequence_number bigint Número de sequência de uma operação dentro de uma transação que criou uma versão de linha.
external_policy_permissions_checked nvarchar(4000) Informações relacionadas à verificação de permissão de autorização externa, quando um evento de auditoria é gerado e as políticas de autorização externa do Purview são avaliadas.
obo_middle_tier_app_id varchar(120) O ID da aplicação do nível intermediário que se conecta usando acesso on-behalf-of (OBO). Anulável. Retorna NULL se a solicitação não for feita usando o acesso OBO.
is_local_secondary_replica bit True se o registro de auditoria se originar de uma réplica secundária local somente leitura, False caso contrário.

Melhorias em relação ao sys.fn_get_audit_file

A sys.fn_get_audit_file_v2 função oferece uma melhoria substancial em relação ao sys.fn_get_audit_file mais antigo, introduzindo uma filtragem eficiente baseada em tempo nos níveis de arquivo e registro. Essa otimização é particularmente benéfica para consultas direcionadas a intervalos de tempo menores e pode ajudar a manter o desempenho em ambientes de vários bancos de dados.

Filtragem de dois níveis

Filtragem no nível do arquivo: a função primeiro filtra os arquivos com base no intervalo de tempo especificado, reduzindo o número de arquivos que precisam ser verificados.

Filtragem em nível de registro: Em seguida, aplica a filtragem nos arquivos selecionados para extrair apenas os registros relevantes.

Aprimoramentos de desempenho

As melhorias de desempenho dependem principalmente do tempo de substituição dos arquivos de blob e do intervalo de tempo consultado. Pressupondo uma distribuição uniforme dos registros de auditoria:

  • Carga reduzida: ao minimizar o número de arquivos e registros a serem verificados, reduz a carga no sistema e melhora os tempos de resposta da consulta.

  • Escalabilidade: ajuda a manter o desempenho mesmo com o aumento do número de bancos de dados, embora a melhoria líquida possa ser menos pronunciada em ambientes com um grande número de bancos de dados.

Comentários

Se o argumento file_pattern passado para fizer referência a fn_get_audit_file_v2 um caminho ou arquivo que não existe, ou se o arquivo não for um arquivo de auditoria, a MSG_INVALID_AUDIT_FILE mensagem de erro será retornada.

A fn_get_audit_file_v2 função não pode ser usada quando a auditoria é criada com as APPLICATION_LOGopções, SECURITY_LOG, ou EXTERNAL_MONITOR .

Atualmente, no Fabric Data Warehouse, você não pode acessar arquivos individuais, apenas a pasta de auditoria. Os seguintes argumentos não são suportados para auditoria SQL em um item de armazenamento: file_pattern, initial_file_name, audit_record_offset.

Permissões

Permissões necessárias no Azure SQL Database

Requer a permissão CONTROL DATABASE.

  • Os administradores do servidor podem acessar os logs de auditoria de todos os bancos de dados no servidor.

  • Os administradores que não são do servidor só podem acessar os logs de auditoria do banco de dados atual.

  • Os blobs que não atendem aos critérios acima são ignorados (uma lista de blobs ignorados é exibida na mensagem de saída da consulta). A função retorna logs somente de blobs para os quais o acesso é permitido.

Permissões necessárias no banco de dados SQL Fabric

Para gerenciar auditorias usando funções de workspace do Fabric, os usuários devem ter associação ao papel de Contribuidor do workspace Fabric ou permissões superiores. Para gerenciar a auditoria com permissões SQL:

  • Para configurar a auditoria de banco de dados, os usuários devem possuir a permissão ALTER ANY DATABASE AUDIT.
  • Para exibir logs de auditoria usando T-SQL, os usuários devem ter a permissão VIEW DATABASE SECURITY AUDIT.

Para mais informações, veja Auditoria no banco de dados SQL Fabric.

Permissões necessárias no Fabric Data Warehouse

Os usuários devem ter a permissão do item Audit Fabric. Para saber mais, consulte Permissões.

Exemplos

A. Veja logs de auditoria SQL para Azure SQL Database

Este exemplo recupera logs de auditoria de um local específico do Armazenamento de Blobs do Azure, filtrando registros entre 2023-11-17T08:40:40Z e 2023-11-17T09:10:40Z.

SELECT *
FROM sys.fn_get_audit_file_v2(
    'https://<storage_account>.blob.core.windows.net/sqldbauditlogs/server_name/database_name/SqlDbAuditing_ServerAudit/',
    DEFAULT,
    DEFAULT,
    '2023-11-17T08:40:40Z',
    '2023-11-17T09:10:40Z')

B. Veja logs de auditoria SQL para o Fabric Data Warehouse

Este exemplo recupera logs de auditoria da pasta OneLake alinhados com o workspace e o warehouse atuais, filtrando registros entre 2023-11-17T08:40:40Z e 2023-11-17T09:10:40Z.

No portal Tecido, recupere seu workspaceID e warehouseID:

  • <workspaceID>: Visite seu espaço de trabalho no portal Fabric. Encontre o GUID do workspace na URL após a /groups/ seção, ou rodando SELECT @@SERVERNAME em um depósito existente. Se sua /groups/ URL for seguida por /me/, você está usando o workspace padrão, e atualmente o SQL Audit para Fabric Data Warehouse não é suportado no workspace padrão.
  • <warehouseID>: Visite seu depósito no portal Fabric. Encontre o ID do depósito na URL após a /warehouses/ seção.
SELECT *
FROM sys. fn_get_audit_file_v2(
    'https://onelake.blob.fabric.microsoft.com/{workspaceId}/{warehouseId}/Audit/sqldbauditlogs/',
    DEFAULT,
    DEFAULT,
    '2023-11-17T08:40:40Z',
    '2023-11-17T09:10:40Z')

C. Visualize logs de auditoria SQL para banco de dados SQL no Microsoft Fabric

Este exemplo recupera logs de auditoria do OneLake no Microsoft Fabric, entre 2025-11-17T08:40:40Z e 2025-11-17T09:10:40Z.

No script a seguir, você precisa fornecer seu ID de espaço de trabalho do Microsoft Fabric e ID do banco de dados. Ambos podem ser encontrados na URL do portal Fabric. Por exemplo: https://fabric.microsoft.com/groups/<fabric workspace id>/sqldatabases/<fabric sql database id>. A primeira string de identificador único na URL é o ID do workspace do Fabric, e a segunda string de identificador único é o ID do banco de dados SQL.

  • Substitua <fabric_workspace_id> pela ID do espaço de trabalho do Fabric. Você pode encontrar o ID de um espaço de trabalho facilmente na URL, é a string exclusiva dentro de dois caracteres / após /groups/ na janela do navegador.
  • Substitua <fabric sql database id> pelo seu banco de dados SQL na identificação do banco de dados do Fabric. Você pode encontrar a ID do item de banco de dados facilmente na URL, é a cadeia de caracteres exclusiva dentro de dois / caracteres após /sqldatabases/ na janela do seu navegador.
SELECT *
FROM sys.fn_get_audit_file_v2(
    'https://onelake.blob.fabric.microsoft.com/<fabric workspace id>/<fabric sql database id>/Audit/sqldbauditlogs/',
    DEFAULT,
    DEFAULT,
    '2025-11-17T08:40:40Z',
    '2025-11-17T09:10:40Z')

Mais informações

Exibições do catálogo do sistema:

Transact-SQL:

Conteúdo relacionado

  • Last updated on