sys.fn_get_audit_file_v2 （Transact-SQL）
適用於：
Azure SQL 資料庫
sys.fn_get_audit_file_v2 Azure SQL 資料庫 中的系統函式是設計來擷取稽核記錄數據，相較於其前置專案，sys.fn_get_audit_file其效率更高。 函式會在檔案和記錄層級引進以時間為基礎的篩選，以提供顯著的效能改善，特別是針對以特定時間範圍為目標的查詢。
重要
sys.fn_get_audit_file_v2目前僅支援 Azure SQL 資料庫。
從 Azure SQL 資料庫 伺服器稽核所建立的稽核檔案傳回資訊。 如需詳細資訊，請參閱 SQL Server 稽核 (資料庫引擎)。
語法
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 } )
引數
file_pattern
指定要讀取之稽核檔案的目錄或路徑和檔名。 file_pattern是 nvarchar（260）。
傳遞沒有檔案名模式的路徑會產生錯誤。
這個自變數可用來指定 Blob URL（包括記憶體端點和容器）。 雖然它不支援星號通配符，但您可以使用部分檔案 （blob） 名稱前置詞 （而不是完整 Blob 名稱）來收集以這個前置詞開頭的多個檔案 （blobs）。 例如：
<Storage_endpoint>/<Container>/<ServerName>/<DatabaseName>/- 收集特定資料庫的所有稽核檔案（Blob）。<Storage_endpoint>/<Container>/<ServerName>/<DatabaseName>/<AuditName>/<CreationDate>/<FileName>.xel- 收集特定的稽核檔案 （Blob）。
initial_file_name
指定稽核檔案集中特定檔案的路徑和名稱，以開始讀取稽核記錄。 initial_file_name是 nvarchar（260） 。
initial_file_name自變數必須包含有效的專案，或必須包含 default 或 NULL 值。
audit_record_offset
使用為 initial_file_name指定的檔案，指定已知位置。 使用這個自變數時，函式會開始讀取緩衝區的第一筆記錄，緊接在指定的位移之後。
audit_record_offset自變數必須包含有效的專案，或必須包含 default 或 NULL 值。 audit_record_offset是 bigint。
start_time
篩選記錄的開始時間。 在此時間前的記錄會排除。
end_time
篩選記錄的結束時間。 此時之後的記錄會排除。
傳回的資料表
下表描述此函式所傳回的稽核檔案內容。
| 資料行名稱 | 類型 | 描述 |
|---|---|---|
event_time |
datetime2 | 引發可稽核動作的日期和時間。 不可為 Null。 |
sequence_number |
int | 追蹤單一稽核記錄中太長而無法納入稽核寫入緩衝區內的記錄順序。 不可為 Null。 |
action_id |
varchar(4) | 動作的標識碼。 不可為 Null。 |
succeeded |
bit | 指示觸發此事件的動作是否成功。 不可為 Null。 對於登入事件以外的所有事件，這隻會報告許可權檢查是否成功或失敗，而不是作業。1 = success0 = fail |
permission_bitmask |
varbinary（16） | 在某些動作中，此位掩碼是已授與、拒絕或撤銷的許可權。 |
is_column_permission |
bit | 指出這是否為資料行層級權限的旗標。 不可為 Null。 0當傳permission_bitmask = 0回 。1 = true0 = false |
session_id |
smallint | 事件發生所在之工作階段的識別碼。 不可為 Null。 |
server_principal_id |
int | 動作執行所在之登入環境的識別碼。 不可為 Null。 |
database_principal_id |
int | 動作執行所在之資料庫使用者環境的識別碼。 不可為 Null。 如果不適用，則傳 0 回 。 例如，伺服器作業。 |
target_server_principal_id |
int | 執行作業的伺服器主體 GRANT/DENY/REVOKE 。 不可為 Null。 如果不適用，則傳 0 回 。 |
target_database_principal_id |
int | 執行作業的資料庫主體 GRANT/DENY/REVOKE 。 不可為 Null。 如果不適用，則傳 0 回 。 |
object_id |
int | 發生稽核之實體的標識碼，其中包含下列物件： - 伺服器物件 -資料庫 - 資料庫物件 - 架構物件 不可為 Null。 0如果實體是伺服器本身，或未在物件層級執行稽核，則傳回 。 例如，驗證。 |
class_type |
varchar(2) | 稽核發生的可稽核實體類型。 不可為 Null。 |
session_server_principal_name |
sysname | 會話的伺服器主體。 可為 Null。 傳回連線到 資料庫引擎 實例的原始登入識別，以防有明確或隱含的內容切換。 |
server_principal_name |
sysname | 目前的登入。 可為 Null。 |
server_principal_sid |
varbinary | 目前的登入 SID。 可為 Null。 |
database_principal_name |
sysname | 目前的使用者。 可為 Null。 如果無法使用，則傳 NULL 回 。 |
target_server_principal_name |
sysname | 動作的目標登入。 可為 Null。 如果不適用，則傳 NULL 回 。 |
target_server_principal_sid |
varbinary | 目標登入的 SID。 可為 Null。 如果不適用，則傳 NULL 回 。 |
target_database_principal_name |
sysname | 動作的目標使用者。 可為 Null。 如果不適用，則傳 NULL 回 。 |
server_instance_name |
sysname | 稽核發生所在的伺服器執行個體名稱。 會使用標準 server\instance 格式。 |
database_name |
sysname | 動作發生所在的資料庫環境。 可為 Null。 傳 NULL 回伺服器層級發生的稽核。 |
schema_name |
sysname | 動作發生所在的結構描述環境。 可為 Null。 NULL針對在架構外部發生的稽核傳回 。 |
object_name |
sysname | 發生稽核的實體名稱，其中包含下列物件： - 伺服器物件 -資料庫 - 資料庫物件 - 架構物件 可為 Null。 NULL如果實體是伺服器本身，或未在物件層級執行稽核，則傳回 。 例如，驗證。 |
statement |
nvarchar(4000) | 如果存在 Transact-SQL 語句，則為 。 可為 Null。 如果不適用，則傳 NULL 回 。 |
additional_information |
nvarchar(4000) | 僅套用至單一事件的唯一資訊會以 XML 傳回。 一些可稽核的動作包含這類資訊。 T-SQL 堆疊的一個層級會以 XML 格式顯示，這些動作具有與其相關聯的 T-SQL 堆疊。 XML 格式為： <tsql_stack><frame nest_level = '%u' database_name = '%.*s' schema_name = '%.*s' object_name = '%.*s' /></tsql_stack>frame nest_level 表示框架的目前巢狀層級。 模組名稱以三部分格式表示（database_name、 schema_name和 object_name）。 模組名稱會剖析為逸出無效的 XML 字元，例如 <、、>/、 _x。 它們會逸出為 _xHHHH_。 代表 HHHH 字元的四位數十六進位UCS-2程式碼。 可為 Null。 NULL當事件沒有報告其他資訊時，會傳回 。 |
file_name |
varchar（260） | 記錄的來源稽核記錄檔路徑和名稱。 不可為 Null。 |
audit_file_offset |
bigint | 包含稽核記錄之檔案中的緩衝區位移。 不可為 Null。 適用於：僅限 SQL Server |
user_defined_event_id |
smallint | 傳遞做為自變數給 sp_audit_write的使用者定義事件標識碼。 NULL 針對系統事件 （預設值） 和使用者定義事件的非零。 如需詳細資訊，請參閱 sp_audit_write （Transact-SQL） 。適用於：SQL Server 2012 （11.x） 和更新版本、Azure SQL 資料庫 和 SQL 受管理執行個體 |
user_defined_information |
nvarchar(4000) | 用來記錄使用者想要使用 sp_audit_write 預存程式在稽核記錄檔中記錄的任何額外資訊。適用於：SQL Server 2012 （11.x） 和更新版本、Azure SQL 資料庫 和 SQL 受管理執行個體 |
audit_schema_version |
int | 一律為 1。 |
sequence_group_id |
varbinary | 唯一的 識別碼。 適用於：SQL Server 2016 (13.x) 和更新版本 |
transaction_id |
bigint | 用來識別單一交易中多個稽核事件的唯一標識符。 適用於：SQL Server 2016 (13.x) 和更新版本 |
client_ip |
nvarchar(128) | 用戶端應用程式的來源IP。 適用於：SQL Server 2017 （14.x） 和更新版本，以及 Azure SQL 資料庫 |
application_name |
nvarchar(128) | 執行造成稽核事件之語句的用戶端應用程式名稱。 適用於：SQL Server 2017 （14.x） 和更新版本，以及 Azure SQL 資料庫 |
duration_milliseconds |
bigint | 查詢執行持續時間以毫秒為單位。 適用於：Azure SQL 資料庫 和 SQL 受管理執行個體 |
response_rows |
bigint | 結果集中傳回的數據列數目。 適用於：Azure SQL 資料庫 和 SQL 受管理執行個體 |
affected_rows |
bigint | 受執行語句影響的數據列數目。 適用於：僅限 Azure SQL 資料庫 |
connection_id |
uniqueidentifier | 伺服器中聯機的標識碼。 適用於：Azure SQL 資料庫 和 SQL 受管理執行個體 |
data_sensitivity_information |
nvarchar(4000) | 根據資料庫中以分類的資料行，由稽核的查詢所傳回的資訊類型與敏感度標籤。 深入瞭解 Azure SQL 資料庫 數據探索和分類。 適用於：僅限 Azure SQL 資料庫 |
host_name |
nvarchar(128) | 用戶端電腦的主機名。 |
session_context |
nvarchar(4000) | 屬於目前工作階段內容的索引鍵/值組。 |
client_tls_version |
bigint | 用戶端支援的最低 TLS 版本。 |
client_tls_version_name |
nvarchar(128) | 用戶端支援的最低 TLS 版本。 |
database_transaction_id |
bigint | 目前工作階段中目前交易的交易標識碼。 |
ledger_start_sequence_number |
bigint | 建立數據列版本之交易內的作業序號。 適用於：僅限 Azure SQL 資料庫 |
external_policy_permissions_checked |
nvarchar(4000) | 當產生稽核事件時，與外部授權許可權檢查相關的資訊，並評估 Purview 外部授權原則。 適用於：僅限 Azure SQL 資料庫 |
obo_middle_tier_app_id |
varchar（120） | 使用代理者 （OBO） 存取連線至 Azure SQL 資料庫 之仲介層應用程式的應用程式識別碼。 可為 Null。 NULL如果要求不是使用 OBO 存取進行，則傳回 。適用於：僅限 Azure SQL 資料庫 |
is_local_secondary_replica |
bit | True 如果稽核記錄源自唯讀本機次要複本，則為 ， False 否則為 。適用於：僅限 Azure SQL 資料庫 |
sys.fn_get_audit_file的改善
函 sys.fn_get_audit_file_v2 式透過在檔案和記錄層級引進有效率的時間型篩選，大幅改善較舊的 sys.fn_get_audit_file 。 這項優化對於以較小時間範圍為目標的查詢特別有用，並可協助維護多資料庫環境中的效能。
雙重層級篩選
檔案層級篩選：函式會先根據指定的時間範圍來篩選檔案，以減少需要掃描的檔案數目。
記錄層級篩選：接著會在選取的檔案內套用篩選，只擷取相關的記錄。
效能增強
效能改善主要取決於 Blob 檔案的變換時間和查詢的時間範圍。 假設稽核記錄的統一分佈：
減少負載：藉由將要掃描的檔案和記錄數目降至最低，可減少系統上的負載，並改善查詢響應時間。
延展性：即使資料庫數目增加，也有助於維護效能，不過，在具有大量資料庫的環境中，凈改善可能較不明顯。
如需設定 Azure SQL 資料庫 稽核的詳細資訊，請參閱開始使用 SQL 資料庫 稽核。
備註
如果傳遞至
fn_get_audit_file_v2的 file_pattern 自變數參考不存在的路徑或檔案，或檔案不是稽核檔案，則會MSG_INVALID_AUDIT_FILE傳回錯誤訊息。fn_get_audit_file_v2使用、SECURITY_LOG或EXTERNAL_MONITOR選項建立APPLICATION_LOG稽核時無法使用。
權限
需要 CONTROL DATABASE 權限。
伺服器管理員可以存取伺服器上所有資料庫的稽核記錄。
非伺服器管理員只能從目前的數據庫存取稽核記錄。
略過不符合上述準則的 Blob（查詢輸出訊息中會顯示略過的 Blob 清單）。 函式只會從允許存取的 Blob 傳回記錄。
範例
此範例會從特定 Azure Blob 儲存體 位置擷取稽核記錄，篩選和2023-11-17T09:10:40Z之間的2023-11-17T08:40: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')
其他相關資訊
系統目錄檢視：
- sys.server_audit_specifications (Transact-SQL)
- sys.server_audit_specification_details (Transact-SQL)
- sys.database_audit_specifications (Transact-SQL)
- sys.database_audit_specification_details (Transact-SQL)
Transact-SQL：
- CREATE SERVER AUDIT (Transact-SQL)
- ALTER SERVER AUDIT (Transact-SQL)
- DROP SERVER AUDIT (Transact-SQL)
- CREATE SERVER AUDIT SPECIFICATION (Transact-SQL)
- ALTER SERVER AUDIT SPECIFICATION (Transact-SQL)
- DROP SERVER AUDIT SPECIFICATION (Transact-SQL)
- CREATE DATABASE AUDIT SPECIFICATION (Transact-SQL)
- ALTER DATABASE AUDIT SPECIFICATION (Transact-SQL)
- DROP DATABASE AUDIT SPECIFICATION (Transact-SQL)
- ALTER AUTHORIZATION (Transact-SQL)