sys.fn_get_audit_file_v2 (Transact-SQL)

  • Article

S’applique à : Azure SQL Database

La sys.fn_get_audit_file_v2 fonction système dans Azure SQL Database est conçue pour récupérer les données du journal d’audit avec une efficacité accrue par rapport à son prédécesseur. sys.fn_get_audit_file La fonction introduit le filtrage basé sur le temps à la fois aux niveaux de fichier et d’enregistrement, offrant des améliorations significatives des performances, en particulier pour les requêtes ciblant des intervalles de temps spécifiques.

Important

sys.fn_get_audit_file_v2 est actuellement pris en charge sur Azure SQL Database uniquement.

Retourne des informations à partir d’un fichier d’audit créé par un audit serveur dans Azure SQL Database. Pour plus d’informations, consultez Audit SQL Server (moteur de base de données).

Conventions de la syntaxe Transact-SQL

Syntaxe

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

Arguments

file_pattern

Spécifie le répertoire ou chemin d'accès et nom de fichier du jeu de fichiers d'audit à lire. file_pattern est nvarchar(260).

Le passage d’un chemin sans modèle de nom de fichier génère une erreur.

Cet argument est utilisé pour spécifier une URL d’objet blob (y compris le point de terminaison de stockage et le conteneur). Bien qu’il ne prend pas en charge un caractère générique astérisque, vous pouvez utiliser un préfixe de nom de fichier partiel (blob) (au lieu du nom d’objet blob complet) pour collecter plusieurs fichiers (objets blob) qui commencent par ce préfixe. Par exemple :

  • <Storage_endpoint>/<Container>/<ServerName>/<DatabaseName>/ - collecte tous les fichiers d’audit (objets blob) pour la base de données spécifique.

  • <Storage_endpoint>/<Container>/<ServerName>/<DatabaseName>/<AuditName>/<CreationDate>/<FileName>.xel - collecte un fichier d’audit spécifique (objet blob).

initial_file_name

Spécifie le chemin d'accès et le nom d'un fichier spécifique dans le jeu de fichiers d'audit à partir duquel commencer à lire des enregistrements d'audit. initial_file_name est nvarchar(260).

L’argument initial_file_name doit contenir des entrées valides ou contenir la ou NULL la default valeur.

audit_record_offset

Spécifie un emplacement connu avec le fichier spécifié pour la initial_file_name. Lorsque cet argument est utilisé, la fonction commence à lire au premier enregistrement de la mémoire tampon immédiatement après le décalage spécifié.

L’argument audit_record_offset doit contenir des entrées valides ou contenir la ou NULL la default valeur. audit_record_offset est bigint.

heure-début

Heure de début du filtrage des journaux. Enregistrements avant cette période sont exclus.

heure-fin

Heure de fin du filtrage des journaux. Les enregistrements après cette période sont exclus.

Table retournée

Le tableau suivant décrit le contenu du fichier d’audit retourné par cette fonction.

Nom de la colonne Type Description
event_time datetime2 Date et heure auxquelles l'action pouvant être auditée est déclenchée. N'accepte pas la valeur NULL.
sequence_number int Assure le suivi de la séquence d'enregistrements dans un enregistrement d'audit unique qui était trop grand pour la mémoire tampon d'écriture pour audits. N'accepte pas la valeur NULL.
action_id varchar(4) ID de l'action. N'accepte pas la valeur NULL.
succeeded bit Indique si l’action qui a déclenché l’événement a réussi. N'accepte pas la valeur NULL. Pour tous les événements autres que les événements de connexion, cet argument signale uniquement le succès ou l'échec de la vérification des autorisations, mais n'indique rien sur l'opération.

1 = réussite
0 = échec
permission_bitmask varbinary(16) Dans certaines actions, ce masque de bits est les autorisations qui ont été accordées, refusées ou révoquées.
is_column_permission bit Indicateur précisant s’il s’agit d’une autorisation au niveau de la colonne. N'accepte pas la valeur NULL. Retourne 0 lorsque le permission_bitmask = 0.

1 = true
0 = false
session_id smallint ID de la session au cours de laquelle l'événement s'est produit. N'accepte pas la valeur NULL.
server_principal_id int ID du contexte de connexion dans lequel l'action est effectuée. N'accepte pas la valeur NULL.
database_principal_id int ID du contexte de l'utilisateur de base de données dans lequel l'action est effectuée. N'accepte pas la valeur NULL. Retourne 0 si cela ne s’applique pas. Par exemple, une opération de serveur.
target_server_principal_id int Principal du serveur sur lequel l’opération GRANT//DENYREVOKE est effectuée. N'accepte pas la valeur NULL. Retourne 0 le cas échéant.
target_database_principal_id int Le principal de base de données sur lequel l’opération GRANT//DENYREVOKE est effectuée. N'accepte pas la valeur NULL. Retourne 0 le cas échéant.
object_id int ID de l’entité sur laquelle l’audit s’est produit, qui inclut les objets suivants :

- Objets serveur
-Bases
- Objets de base de données
- Objets de schéma

N'accepte pas la valeur NULL. Retourne 0 si l’entité est le serveur lui-même ou si l’audit n’est pas effectué au niveau d’un objet. Par exemple, Authentification.
class_type varchar(2) Type d'entité pouvant être auditée sur laquelle l'audit se produit. N'accepte pas la valeur NULL.
session_server_principal_name sysname Principal du serveur pour la session. Autorise la valeur Null. Retourne l’identité de la connexion d’origine connectée à l’instance du Moteur de base de données en cas de commutateurs de contexte explicites ou implicites.
server_principal_name sysname Connexion actuelle. Autorise la valeur Null.
server_principal_sid varbinary SID de la connexion actuelle. Autorise la valeur Null.
database_principal_name sysname Utilisateur actuel. Autorise la valeur Null. Retourne NULL s’il n’est pas disponible.
target_server_principal_name sysname Connexion cible de l’action. Autorise la valeur Null. Retourne NULL le cas échéant.
target_server_principal_sid varbinary SID de la connexion cible. Autorise la valeur Null. Retourne NULL le cas échéant.
target_database_principal_name sysname Utilisateur cible de l’action. Autorise la valeur Null. Retourne NULL le cas échéant.
server_instance_name sysname Nom de l'instance de serveur où l'audit s'est produit. Le format standard server\instance est utilisé.
database_name sysname Contexte de base de données dans lequel l'action s'est produite. Autorise la valeur Null. Retourne NULL les audits qui se produisent au niveau du serveur.
schema_name sysname Contexte du schéma dans lequel l’action s’est produite. Autorise la valeur Null. Retourne NULL les audits qui se produisent en dehors d’un schéma.
object_name sysname Nom de l’entité sur laquelle l’audit s’est produit, qui inclut les objets suivants :

- Objets serveur
-Bases
- Objets de base de données
- Objets de schéma

Autorise la valeur Null. Retourne NULL si l’entité est le serveur lui-même ou si l’audit n’est pas effectué au niveau d’un objet. Par exemple, Authentification.
statement nvarchar(4000) Instruction Transact-SQL s’il existe. Autorise la valeur Null. Retourne NULL le cas échéant.
additional_information nvarchar(4000) Les informations uniques qui s'appliquent seulement à un événement unique sont retournées au format XML. Quelques actions auditables contiennent ce type d’informations.

Un niveau de pile T-SQL s’affiche au format XML pour les actions associées à la pile T-SQL. Le format XML est le suivant : <tsql_stack><frame nest_level = '%u' database_name = '%.*s' schema_name = '%.*s' object_name = '%.*s' /></tsql_stack>

frame nest_level indique le niveau d’imbrication actuel du frame. Le nom du module est représenté au format trois parties (database_name, schema_nameet object_name). Le nom du module est analysé pour échapper des caractères XML non valides tels que <, >, /, _x. Ils sont échappés comme _xHHHH_. Il HHHH s’appelle le code UCS-2 hexadécimal à quatre chiffres pour le caractère. Autorise la valeur Null. Retourne NULL lorsqu’aucune information supplémentaire n’est signalée par l’événement.
file_name varchar(260) Chemin d'accès et nom du fichier journal d'audit d'où provenait l'enregistrement. N'accepte pas la valeur NULL.
audit_file_offset bigint Offset de la mémoire tampon dans le fichier qui contient l'enregistrement d'audit. N'accepte pas la valeur NULL.

S’applique à : SQL Server uniquement
user_defined_event_id smallint ID d’événement défini par l’utilisateur passé en tant qu’argument à sp_audit_write. NULL pour les événements système (par défaut) et non zéro pour l’événement défini par l’utilisateur. Pour plus d’informations, consultez sp_audit_write (Transact-SQL).

S’applique à : SQL Server 2012 (11.x) et versions ultérieures, Azure SQL Database et SQL Managed Instance
user_defined_information nvarchar(4000) Utilisé pour enregistrer toutes les informations supplémentaires que l’utilisateur souhaite enregistrer dans le journal d’audit à l’aide de la sp_audit_write procédure stockée.

S’applique à : SQL Server 2012 (11.x) et versions ultérieures, Azure SQL Database et SQL Managed Instance
audit_schema_version int A toujours la valeur 1.
sequence_group_id varbinary Identificateur unique.

S’applique à : SQL Server 2016 (13.x) et versions ultérieures
transaction_id bigint Identificateur unique pour identifier plusieurs événements d’audit dans une transaction.

S’applique à : SQL Server 2016 (13.x) et versions ultérieures
client_ip nvarchar(128) Adresse IP source de l’application cliente.

S’applique à : SQL Server 2017 (14.x) et versions ultérieures, et Azure SQL Database
application_name nvarchar(128) Nom de l’application cliente qui a exécuté l’instruction qui a provoqué l’événement d’audit.

S’applique à : SQL Server 2017 (14.x) et versions ultérieures, et Azure SQL Database
duration_milliseconds bigint Durée d’exécution des requêtes en millisecondes.

S’applique à : Azure SQL Database et SQL Managed Instance
response_rows bigint Nombre de lignes retournées dans le jeu de résultats.

S’applique à : Azure SQL Database et SQL Managed Instance
affected_rows bigint Nombre de lignes affectées par l’instruction exécutée.

S’applique uniquement à : Azure SQL Database
connection_id uniqueidentifier ID de la connexion dans le serveur.

S’applique à : Azure SQL Database et SQL Managed Instance
data_sensitivity_information nvarchar(4000) Types des informations et étiquettes de sensibilité renvoyées par la requête auditée, en fonction des colonnes classifiées dans la base de données. En savoir plus sur la découverte et la classification des données Azure SQL Database.

S’applique uniquement à : Azure SQL Database
host_name nvarchar(128) Nom d’hôte de l’ordinateur client.
session_context nvarchar(4000) Paires clé-valeur qui font partie du contexte de session actuel.
client_tls_version bigint Version TLS minimale prise en charge par le client.
client_tls_version_name nvarchar(128) Version TLS minimale prise en charge par le client.
database_transaction_id bigint ID de transaction de la transaction actuelle dans la session active.
ledger_start_sequence_number bigint Numéro de séquence d’une opération au sein d’une transaction qui a créé une version de ligne.

S’applique uniquement à : Azure SQL Database
external_policy_permissions_checked nvarchar(4000) Informations relatives à la vérification des autorisations d’autorisation externes, lorsqu’un événement d’audit est généré et que les stratégies d’autorisation externe Purview sont évaluées.

S’applique uniquement à : Azure SQL Database
obo_middle_tier_app_id varchar(120) ID d’application de l’application de niveau intermédiaire qui se connecte à Azure SQL Database à l’aide de l’accès OBO (on-behalf-of). Autorise la valeur Null. Retourne NULL si la requête n’est pas effectuée à l’aide de l’accès OBO.

S’applique uniquement à : Azure SQL Database
is_local_secondary_replica bit True si l’enregistrement d’audit provient d’un réplica secondaire local en lecture seule, False sinon.

S’applique uniquement à : Azure SQL Database

Améliorations apportées à sys.fn_get_audit_file

La sys.fn_get_audit_file_v2 fonction offre une amélioration substantielle de l’ancienne sys.fn_get_audit_file en introduisant un filtrage efficace basé sur le temps aux niveaux de fichier et d’enregistrement. Cette optimisation est particulièrement bénéfique pour les requêtes ciblant des intervalles de temps plus petits et peuvent aider à maintenir les performances dans les environnements multi-bases de données.

Filtrage à double niveau

Filtrage au niveau du fichier : la fonction filtre d’abord les fichiers en fonction de l’intervalle de temps spécifié, ce qui réduit le nombre de fichiers à analyser.

Filtrage au niveau de l’enregistrement : il applique ensuite le filtrage dans les fichiers sélectionnés pour extraire uniquement les enregistrements pertinents.

Une amélioration du niveau de performance

Les améliorations des performances dépendent principalement du temps de substitution des fichiers blob et de l’intervalle de temps interrogé. En supposant une distribution uniforme des enregistrements d’audit :

  • Charge réduite : en réduisant le nombre de fichiers et d’enregistrements à analyser, elle réduit la charge sur le système et améliore les temps de réponse des requêtes.

  • Scalabilité : permet de maintenir les performances même si le nombre de bases de données augmente, bien que l’amélioration nette puisse être moins prononcée dans les environnements avec un grand nombre de bases de données.

Pour plus d’informations sur la configuration de l’audit Azure SQL Database, consultez Prise en main de l’audit SQL Database.

Notes

  • Si l’argument file_pattern passé à référencer fn_get_audit_file_v2 un chemin d’accès ou un fichier qui n’existe pas ou si le fichier n’est pas un fichier d’audit, le MSG_INVALID_AUDIT_FILE message d’erreur est retourné.

  • fn_get_audit_file_v2ne peut pas être utilisé lorsque l’audit est créé avec les options ou EXTERNAL_MONITOR SECURITY_LOGles APPLICATION_LOGoptions.

autorisations

Nécessite l’autorisation CONTROL DATABASE.

  • Les administrateurs de serveur peuvent accéder aux journaux d’audit de toutes les bases de données sur le serveur.

  • Les administrateurs non serveurs peuvent uniquement accéder aux journaux d’audit à partir de la base de données active.

  • Les objets blob qui ne répondent pas aux critères ci-dessus sont ignorés (une liste d’objets blob ignorés s’affiche dans le message de sortie de requête). La fonction retourne des journaux uniquement à partir d’objets blob pour lesquels l’accès est autorisé.

Exemples

Cet exemple récupère les journaux d’audit à partir d’un emplacement de Stockage Blob Azure spécifique, en filtrant les enregistrements entre 2023-11-17T08:40:40Z et 2023-11-17T09:10:40Z.

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

Plus d’informations

Vues de catalogue système :

Transact-SQL :

Contenu connexe