sys.fn_get_audit_file (Transact-SQL)

2025-06-21

Van toepassing op:SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics

Retourneert informatie uit een auditbestand dat is gemaakt door een servercontrole in SQL Server. Zie SQL Server Audit (Database Engine) voor meer informatie.

Opmerking

Voor Azure SQL Database kunt u in plaats daarvan sys.fn_get_audit_file_v2 gebruiken. sys.fn_get_audit_file_v2 introduceert tijdgebaseerde filtering op zowel bestand- als recordniveau, wat aanzienlijke prestatieverbeteringen biedt, met name voor query's die zijn gericht op specifieke tijdsbereiken.

Transact-SQL syntaxis-conventies

Syntaxis

fn_get_audit_file ( file_pattern ,
    { default | initial_file_name | NULL } ,
    { default | audit_record_offset | NULL } )

Argumenten

file_pattern

Hiermee geeft u de map of het pad en de bestandsnaam op voor de auditbestand die moet worden gelezen. Type is nvarchar(260).

Als u een pad doorgeeft zonder een bestandsnaampatroon, wordt er een fout gegenereerd.

SQL Server
Azure SQL Database

Dit argument moet zowel een pad (stationsletter of netwerkshare) als een bestandsnaam bevatten die een jokerteken kan bevatten. Eén sterretje (*) kan worden gebruikt voor het verzamelen van meerdere bestanden uit een auditbestandsset. Voorbeeld:

\<path>\* - Verzamel alle auditbestanden op de opgegeven locatie.
<path>\LoginsAudit_{GUID}* - Verzamel alle auditbestanden met de opgegeven naam en GUID-paar.
<path>\LoginsAudit_{GUID}_00_29384.sqlaudit - Een specifiek auditbestand verzamelen.

Dit argument wordt gebruikt om een blob-URL op te geven (inclusief het opslageindpunt en de container). Hoewel het geen ondersteuning biedt voor een sterretje, kunt u een gedeeltelijk naamvoorvoegsel (blob) (in plaats van de volledige blobnaam) gebruiken om meerdere bestanden (blobs) te verzamelen die beginnen met dit voorvoegsel. Voorbeeld:

<Storage_endpoint>/<Container>/<ServerName>/<DatabaseName>/ - verzamelt alle auditbestanden (blobs) voor de specifieke database.
<Storage_endpoint>/<Container>/<ServerName>/<DatabaseName>/<AuditName>/<CreationDate>/<FileName>.xel - verzamelt een specifiek auditbestand (blob).

initial_file_name

Hiermee geeft u het pad en de naam van een specifiek bestand in het auditbestand ingesteld om te beginnen met het lezen van auditrecords van. Type is nvarchar(260).

Het argument initial_file_name moet geldige vermeldingen bevatten of moet de default of NULL waarde bevatten.

audit_record_offset

Hiermee geeft u een bekende locatie met het bestand dat is opgegeven voor de initial_file_name. Wanneer dit argument wordt gebruikt, begint de functie te lezen bij de eerste record van de buffer direct na de opgegeven offset.

Het argument audit_record_offset moet geldige vermeldingen bevatten of moet de default of NULL waarde bevatten. Type is bigint.

Geretourneerde tabellen

In de volgende tabel wordt de inhoud van het auditbestand beschreven die door deze functie kan worden geretourneerd.

Kolomnaam	Typologie	Beschrijving
`event_time`	datetime2	UTC-datum en -tijd waarop de controleerbare actie wordt geactiveerd. Niet nullwaarde.
`sequence_number`	Int	Houdt de reeks records in één controlerecord bij die te groot was om in de schrijfbuffer voor controles te passen. Niet nullwaarde.
`action_id`	varchar(4)	Id van de actie. Niet nullwaarde.
`succeeded`	bit	Geeft aan of de actie die de gebeurtenis heeft geactiveerd, is geslaagd. Niet nullwaarde. Voor alle andere gebeurtenissen dan aanmeldingsgebeurtenissen wordt alleen gerapporteerd of de machtigingscontrole is geslaagd of mislukt, niet de bewerking. `1` = succes `0` = mislukken
`permission_bitmask`	Variair(16)	In sommige acties is dit bitmasker de machtigingen die zijn verleend, geweigerd of ingetrokken.
`is_column_permission`	bit	Vlag die aangeeft of dit een machtiging op kolomniveau is. Niet nullwaarde. Retourneert `0` wanneer de`permission_bitmask` = `0` . `1` = waar `0` = onwaar
`session_id`	smallint	Id van de sessie waarop de gebeurtenis heeft plaatsgevonden. Niet nullwaarde.
`server_principal_id`	Int	Id van de aanmeldingscontext waarin de actie wordt uitgevoerd. Niet nullwaarde.
`database_principal_id`	Int	Id van de databasegebruikerscontext waarin de actie wordt uitgevoerd. Niet nullwaarde. Retourneert `0` als dit niet van toepassing is. Bijvoorbeeld een serverbewerking.
`target_server_principal_id`	Int	Server-principal waarop de `GRANT`/`DENY`/`REVOKE` bewerking wordt uitgevoerd. Niet nullwaarde. Retourneert `0` indien niet van toepassing.
`target_database_principal_id`	Int	De database-principal waarop de `GRANT`/`DENY`/`REVOKE` bewerking wordt uitgevoerd. Niet nullwaarde. Retourneert `0` indien niet van toepassing.
`object_id`	Int	De id van de entiteit waarop de controle heeft plaatsgevonden, waaronder de volgende objecten: - Serverobjecten -Databases - Databaseobjecten - Schemaobjecten Niet nullwaarde. Retourneert `0` of de entiteit de server zelf is of als de controle niet op objectniveau wordt uitgevoerd. Bijvoorbeeld verificatie.
`class_type`	varchar(2)	Het type controleerbare entiteit waarop de controle plaatsvindt. Niet nullwaarde.
`session_server_principal_name`	sysname	De server-principal voor de sessie. Kan null zijn. Retourneert de identiteit van de oorspronkelijke aanmelding die is verbonden met het exemplaar van de database-engine voor het geval er expliciete of impliciete contextswitches zijn.
`server_principal_name`	sysname	Huidige aanmelding. Kan null zijn.
`server_principal_sid`	varbinair	Huidige aanmeldingsbeveiligings-id (SID). Kan null zijn.
`database_principal_name`	sysname	Huidige gebruiker. Kan null zijn. Retourneert `NULL` indien niet beschikbaar.
`target_server_principal_name`	sysname	Doelinlog van actie. Kan null zijn. Retourneert `NULL` indien niet van toepassing.
`target_server_principal_sid`	varbinair	SID van doelaanmelding. Kan null zijn. Retourneert `NULL` indien niet van toepassing.
`target_database_principal_name`	sysname	Doelgebruiker van de handeling. Kan null zijn. Retourneert `NULL` indien niet van toepassing.
`server_instance_name`	sysname	Naam van het serverexemplaren waar de controle heeft plaatsgevonden. De standaardindeling `server\instance` wordt gebruikt.
`database_name`	sysname	De databasecontext waarin de actie heeft plaatsgevonden. Kan null zijn. Retourneert `NULL` voor controles die plaatsvinden op serverniveau.
`schema_name`	sysname	De schemacontext waarin de actie heeft plaatsgevonden. Kan null zijn. Retourneert `NULL` voor controles die buiten een schema plaatsvinden.
`object_name`	sysname	De naam van de entiteit waarop de controle heeft plaatsgevonden, waaronder de volgende objecten: - Serverobjecten -Databases - Databaseobjecten - Schemaobjecten Kan null zijn. Retourneert `NULL` of de entiteit de server zelf is of als de controle niet op objectniveau wordt uitgevoerd. Bijvoorbeeld verificatie.
`statement`	nvarchar(4000)	Transact-SQL instructie als deze bestaat. Kan null zijn. Retourneert `NULL` indien niet van toepassing.
`additional_information`	nvarchar(4000)	Unieke informatie die alleen van toepassing is op één gebeurtenis, wordt geretourneerd als XML. Een paar controlebare acties bevatten dit soort informatie. Eén niveau van T-SQL-stack wordt weergegeven in XML-indeling voor acties waaraan T-SQL-stack is gekoppeld. De XML-indeling is: `<tsql_stack><frame nest_level = '%u' database_name = '%.s' schema_name = '%.s' object_name = '%.*s' /></tsql_stack>` `frame nest_level` geeft het huidige nestniveau van het frame aan. De modulenaam wordt weergegeven in drie delen (`database_name`, `schema_name`en `object_name`). De modulenaam wordt geparseerd om ongeldige XML-tekens te ontsnappen, zoals `<`, `>`, `/`. `_x` Ze zijn ontsnapt als `_xHHHH_`. De `HHHH` staat voor de hexadecimale UCS-2-code van vier cijfers voor het teken. Kan null zijn. Retourneert `NULL` wanneer er geen aanvullende informatie is gerapporteerd door de gebeurtenis.
`file_name`	Varchar(260)	Het pad en de naam van het auditlogboekbestand waaruit de record afkomstig is. Niet nullwaarde.
`audit_file_offset`	bigint	De bufferverschil in het bestand dat de controlerecord bevat. Niet nullwaarde. Van toepassing op: alleen SQL Server
`user_defined_event_id`	smallint	Door de gebruiker gedefinieerde gebeurtenis-id doorgegeven als argument aan `sp_audit_write`. `NULL` voor systeemgebeurtenissen (standaard) en niet-nul voor door de gebruiker gedefinieerde gebeurtenis. Zie sp_audit_write voor meer informatie. Van toepassing op: SQL Server 2012 (11.x) en latere versies, Azure SQL Database en SQL Managed Instance
`user_defined_information`	nvarchar(4000)	Wordt gebruikt om extra informatie vast te leggen die de gebruiker wil opnemen in het auditlogboek met behulp van de `sp_audit_write` opgeslagen procedure. Van toepassing op: SQL Server 2012 (11.x) en latere versies, Azure SQL Database en SQL Managed Instance
`audit_schema_version`	Int	Altijd `1`.
`sequence_group_id`	varbinair	Unieke id. van toepassing op: SQL Server 2016 (13.x) en latere versies
`transaction_id`	bigint	Unieke id om meerdere controlegebeurtenissen in één transactie te identificeren. van toepassing op: SQL Server 2016 (13.x) en latere versies
`client_ip`	Nvarchar(128)	Bron-IP van de clienttoepassing. van toepassing op: SQL Server 2017 (14.x) en latere versies en Azure SQL Database
`application_name`	Nvarchar(128)	De naam van de clienttoepassing die de instructie heeft uitgevoerd die de controlegebeurtenis heeft veroorzaakt. van toepassing op: SQL Server 2017 (14.x) en latere versies en Azure SQL Database
`duration_milliseconds`	bigint	Duur van uitvoering van de query in milliseconden. Van toepassing op: Azure SQL Database en SQL Managed Instance
`response_rows`	bigint	Het aantal rijen dat wordt geretourneerd in de resultatenset. Van toepassing op: Azure SQL Database en SQL Managed Instance
`affected_rows`	bigint	Het aantal rijen dat wordt beïnvloed door de uitgevoerde instructie. Van toepassing op: alleen Azure SQL Database
`connection_id`	uniqueidentifier	Id van de verbinding op de server. Van toepassing op: Azure SQL Database en SQL Managed Instance
`data_sensitivity_information`	nvarchar(4000)	Informatietypen en vertrouwelijkheidslabels die worden geretourneerd door de gecontroleerde query, op basis van de geclassificeerde kolommen in de database. Meer informatie over het detecteren en classificeren van Azure SQL Database-gegevens. Van toepassing op: alleen Azure SQL Database
`host_name`	Nvarchar(128)	Hostnaam van de clientcomputer.
`session_context`	nvarchar(4000)	De sleutel-waardeparen die deel uitmaken van de huidige sessiecontext.
`client_tls_version`	bigint	Minimale TLS-versie die wordt ondersteund door de client.
`client_tls_version_name`	Nvarchar(128)	Minimale TLS-versie die wordt ondersteund door de client.
`database_transaction_id`	bigint	Transactie-id van de huidige transactie in de huidige sessie.
`ledger_start_sequence_number`	bigint	Het volgnummer van een bewerking binnen een transactie die een rijversie heeft gemaakt. Van toepassing op: Alleen Azure SQL Database
`external_policy_permissions_checked`	nvarchar(4000)	Informatie met betrekking tot de controle van externe autorisatiemachtigingen, wanneer er een controlegebeurtenis wordt gegenereerd en purview-beleid voor externe autorisatie wordt geëvalueerd. Van toepassing op: Alleen Azure SQL Database
`obo_middle_tier_app_id`	Varchar(120)	De toepassings-id van de toepassing in de middelste laag die verbinding maakt met Azure SQL Database met behulp van toegang namens (OBO). Kan null zijn. Retourneert `NULL` als de aanvraag niet wordt gedaan met OBO-toegang. Van toepassing op: alleen Azure SQL Database
`is_local_secondary_replica`	bit	`True` als de controlerecord afkomstig is van een alleen-lezen lokale secundaire replica, `False` anders. Van toepassing op: Alleen Azure SQL Database

Opmerkingen

Als het argument file_pattern wordt doorgegeven aan fn_get_audit_file een pad of bestand dat niet bestaat of als het bestand geen controlebestand is, wordt het MSG_INVALID_AUDIT_FILE foutbericht geretourneerd.
fn_get_audit_file kan niet worden gebruikt wanneer de controle wordt gemaakt met de APPLICATION_LOG, SECURITY_LOGof EXTERNAL_MONITOR opties.

SQL Server 2019 (15.x) en eerdere versies vereisen CONTROL SERVER machtiging op de server.

VOOR SQL Server 2022 (16.x) en latere versies is VIEW SERVER SECURITY AUDIT machtiging op de server vereist.

Hiervoor is de machtiging CONTROL DATABASE vereist.

Serverbeheerders hebben toegang tot auditlogboeken van alle databases op de server.
Niet-serverbeheerders hebben alleen toegang tot auditlogboeken vanuit de huidige database.
Blobs die niet voldoen aan de bovenstaande criteria, worden overgeslagen (er wordt een lijst met overgeslagen blobs weergegeven in het uitvoerbericht van de query). De functie retourneert alleen logboeken van blobs waarvoor toegang is toegestaan.

Voorbeelden

SQL Server
Azure SQL Database

In dit voorbeeld wordt gelezen uit een bestand met de naam \\serverName\Audit\HIPAA_AUDIT.sqlaudit.

SELECT *
FROM sys.fn_get_audit_file(
    '\\serverName\Audit\HIPAA_AUDIT.sqlaudit',
    DEFAULT,
    DEFAULT
);
GO

Zie SQL Server Audit (Database Engine) voor een volledig voorbeeld van het maken van een controle.

In dit voorbeeld wordt gelezen uit een bestand met de naam ShiraServer/MayaDB/SqlDbAuditing_Audit/2017-07-14/10_45_22_173_1.xel:

SELECT *
FROM sys.fn_get_audit_file(
    'https://mystorage.blob.core.windows.net/sqldbauditlogs/ShiraServer/MayaDB/SqlDbAuditing_Audit/2017-07-14/10_45_22_173_1.xel',
    DEFAULT,
    DEFAULT
);
GO

Dit voorbeeld leest uit hetzelfde bestand als eerder weergegeven, maar met meer T-SQL-componenten (TOPORDER BYen WHERE component voor het filteren van de controlerecords die door de functie worden geretourneerd):

SELECT TOP 10 *
FROM sys.fn_get_audit_file(
    'https://mystorage.blob.core.windows.net/sqldbauditlogs/ShiraServer/MayaDB/SqlDbAuditing_Audit/2017-07-14/10_45_22_173_1.xel',
    DEFAULT,
    DEFAULT
)
WHERE server_principal_name = 'admin1'
ORDER BY event_time;
GO

Zie Aan de slag met SQL Database-controle voor meer informatie over het instellen van Azure SQL Database-controle.

Beperkingen

Rijen selecteren vanuit sys.fn_get_audit_file een Create Table As Select (CTAS) of INSERT INTO is een beperking bij het uitvoeren van Azure Synapse Analytics. Hoewel de query is voltooid en er geen foutberichten worden weergegeven, zijn er geen rijen aanwezig in de tabel die is gemaakt met CTAS of INSERT INTO.

Meer informatie

Systeemcatalogusweergaven:

Transact-SQL: