تعليمة برمجية لهدف ملف الحدث للأحداث الممتدة في Azure SQL Database ومثيل SQL المُدار

مقالة
01/28/2024

ينطبق على: قاعدة بيانات Azure SQL مثيل Azure SQL المُدار

أنت تريد نموذج تعليمات برمجية كامل لطريقة قوية لالتقاط معلومات عن حدث موسع والإبلاغ عنها.

في Microsoft SQL Server، يستخدم هدف ملف الحدث لتخزين مخرجات الحدث في ملف محرك أقراص ثابت داخلي. لكن التخزين المحلي غير متاح لـAzure SQL Database أو مثيل SQL المُدار. بدلاً من ذلك، استخدم Azure Blob Storage لدعم هدف ملف الحدث.

تقدم هذه المقالة نموذج التعليمات البرمجية من مرحلتين:

PowerShell، لإنشاء حاوية تخزين Azure في السحابة.
Transact-SQL:
- لتعيين حاوية تخزين Azure لهدف ملف الحدث.
- لإنشاء جلسة عمل الحدث وبدء تشغيلها، وهكذا.

المتطلبات الأساسية

ملاحظة

تستخدم هذه المقالة الوحدة النمطية Azure Az PowerShell، وهي الوحدة النمطية PowerShell الموصى بها للتفاعل مع Azure. لبدء استخدام الوحدة النمطية Az PowerShell، راجع تثبيت Azure PowerShell. لمعرفة كيفية الترحيل إلى الوحدة النمطية Az PowerShell، راجع ترحيل Azure PowerShell من AzureRM إلى Az.

هام

لا تزال الوحدة النمطيةPowerShell Azure Resource Manager مدعومة من قبل قاعدة بيانات SQL Azure، ولكن جميع التطويرات المستقبلية تكون للوحدة النمطية Az.Sql. بالنسبة إلى أوامر cmdlets، راجع AzureRM.Sql. تتطابق وسائط الأوامر في الوحدة النمطية Az وفي الوحدات النمطية AzureRm بشكل كبير.

حساب Azure والاشتراك يمكنك الاشتراك في نسخة تجريبية مجانية.
أي قاعدة بيانات يمكنك إنشاء جدول بها.
- اختياريًّا، يمكنك إنشاء قاعدة البيانات التوضيحية AdventureWorksLT في دقائق.
SQL Server Management Studio (ssms.exe)، آخر إصدار تحديث شهري له من الناحية المثالية: تنزيل SQL Server Management Studio
يجب أن تكون لديك الوحدات النمطية لـ Azure PowerShell مثبتة.
- توفر الوحدات النمطية أوامر، مثل - New-AzStorageAccount.

المرحلة 1: رمز PowerShell لحاوية تخزين Azure

PowerShell هذا هو المرحلة 1 من نموذج التعليمات البرمجية ذات المرحلتين.

يبدأ البرنامج النصي بأوامر للتنظيف بعد تشغيل سابق محتمل، ويمكن إعادة تشغيله.

الصق البرنامج النصي PowerShell في محرر نص بسيط، مثل Notepad.exe وحفظ البرنامج النصي كملف مع ملحق .ps1.
ابدأ تشغيل PowerShell ISE كمسؤول.
عند الطلب، اكتب
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
ثم اضغط على زر Enter.
في PowerShell ISE، افتح ملف .ps1. قم بتشغيل البرنامج النصي
يبدأ البرنامج النصي أولاً بنافذة جديدة تقوم فيها بتسجيل الدخول إلى Azure.
- إذا قمت بإعادة تشغيل البرنامج النصي دون مقاطعة جلستك، فلديك الخيار المناسب للتعليق على أمر Add-AzureAccount.

PowerShell ISE, with Azure module installed, ready to run script.

رمز PowerShell

يفترض برنامج PowerShell النصي هذا أنك قمت بالفعل بتثبيت الوحدة النمطية Az. لمزيد من المعلومات، راجع تثبيت Azure PowerShell module.

## TODO: Before running, find all 'TODO' and make each edit!!

cls;

#--------------- 1 -----------------------

'Script assumes you have already logged your PowerShell session into Azure.
But if not, run  Connect-AzAccount (or  Connect-AzAccount), just one time.';
#Connect-AzAccount;   # Same as  Connect-AzAccount.

#-------------- 2 ------------------------

'
TODO: Edit the values assigned to these variables, especially the first few!
';

# Ensure the current date is between
# the Expiry and Start time values that you edit here.

$subscriptionName    = 'YOUR_SUBSCRIPTION_NAME';
$resourceGroupName   = 'YOUR_RESOURCE-GROUP-NAME';

$policySasExpiryTime = '2018-08-28T23:44:56Z';
$policySasStartTime  = '2017-10-01';

$storageAccountLocation = 'YOUR_STORAGE_ACCOUNT_LOCATION';
$storageAccountName     = 'YOUR_STORAGE_ACCOUNT_NAME';
$containerName          = 'YOUR_CONTAINER_NAME';
$policySasToken         = ' ? ';

$policySasPermission = 'rwl';  # Leave this value alone, as 'rwl'.

#--------------- 3 -----------------------

# The ending display lists your Azure subscriptions.
# One should match the $subscriptionName value you assigned
#   earlier in this PowerShell script.

'Choose an existing subscription for the current PowerShell environment.';

Select-AzSubscription -Subscription $subscriptionName;

#-------------- 4 ------------------------

'
Clean up the old Azure Storage Account after any previous run,
before continuing this new run.';

if ($storageAccountName) {
    Remove-AzStorageAccount `
        -Name              $storageAccountName `
        -ResourceGroupName $resourceGroupName;
}

#--------------- 5 -----------------------

[System.DateTime]::Now.ToString();

'
Create a storage account.
This might take several minutes, will beep when ready.
  ...PLEASE WAIT...';

New-AzStorageAccount `
    -Name              $storageAccountName `
    -Location          $storageAccountLocation `
    -ResourceGroupName $resourceGroupName `
    -SkuName           'Standard_LRS';

[System.DateTime]::Now.ToString();
[System.Media.SystemSounds]::Beep.Play();

'
Get the access key for your storage account.
';

$accessKey_ForStorageAccount = `
    (Get-AzStorageAccountKey `
        -Name              $storageAccountName `
        -ResourceGroupName $resourceGroupName
        ).Value[0];

"`$accessKey_ForStorageAccount = $accessKey_ForStorageAccount";

'Azure Storage Account cmdlet completed.
Remainder of PowerShell .ps1 script continues.
';

#--------------- 6 -----------------------

# The context will be needed to create a container within the storage account.

'Create a context object from the storage account and its primary access key.
';

$context = New-AzStorageContext `
    -StorageAccountName $storageAccountName `
    -StorageAccountKey  $accessKey_ForStorageAccount;

'Create a container within the storage account.
';

$containerObjectInStorageAccount = New-AzStorageContainer `
    -Name    $containerName `
    -Context $context;

'Create a security policy to be applied to the SAS token.
';

New-AzStorageContainerStoredAccessPolicy `
    -Container  $containerName `
    -Context    $context `
    -Policy     $policySasToken `
    -Permission $policySasPermission `
    -ExpiryTime $policySasExpiryTime `
    -StartTime  $policySasStartTime;

'
Generate a SAS token for the container.
';
try {
    $sasTokenWithPolicy = New-AzStorageContainerSASToken `
        -Name    $containerName `
        -Context $context `
        -Policy  $policySasToken;
}
catch {
    $Error[0].Exception.ToString();
}

#-------------- 7 ------------------------

'Display the values that YOU must edit into the Transact-SQL script next!:
';

"storageAccountName: $storageAccountName";
"containerName:      $containerName";
"sasTokenWithPolicy: $sasTokenWithPolicy";

'
REMINDER: sasTokenWithPolicy here might start with "?" character, which you must exclude from Transact-SQL.
';

'
(Later, return here to delete your Azure Storage account. See the preceding  Remove-AzStorageAccount -Name $storageAccountName)';

'
Now shift to the Transact-SQL portion of the two-part code sample!';

# EOFile

قم بتدوين القيم المسماة القليلة التي يطبعها برنامج PowerShell النصي عندما ينتهي. يجب تعديل هذه القيم في البرنامج النصي SQL Transact الذي يليه كمرحلة 2.

ملاحظة

في مثال نموذج التعليمات البرمجية PowerShell السابق، لا تتوافق الأحداث الموسعة لـ SQL مع حسابات التخزين ADLS Gen2.

المرحلة الثانية: رمز Transact-SQL الذي يستخدم حاوية تخزين Azure

في المرحلة 1 من نموذج التعليمات البرمجية هذا، قمت بتشغيل برنامج نصي PowerShell لإنشاء حاوية تخزين Azure.
بعد ذلك في المرحلة 2، يجب أن يستخدم البرنامج النصي Transact-SQL التالي الحاوية.

يبدأ البرنامج النصي بأوامر للتنظيف بعد تشغيل سابق محتمل، ويمكن إعادة تشغيله.

البرنامج النصي PowerShell طبع بعض القيم المسماة عند انتهائه. يجب تحرير البرنامج النصي Transact-SQL لاستخدام هذه القيم. البحث عن TODO في البرنامج النصي Transact-SQL لتحديد موقع نقاط التحرير.

افتح SQL Server Management Studio (ssms.exe).
اتصل بقاعدة البيانات الخاصة بك في Azure SQL Database أو مثيل مُدار من SQL.
حدد لفتح جزء استعلام جديد.
الصق البرنامج النصي Transact-SQL في لوحة الاستعلام.
البحث عن كل TODO في البرنامج النصي وإجراء التعديلات المناسبة.
احفظ، ثم قم بتشغيل البرنامج النصي:

تحذير

قد تبدأ قيمة المفتاح SAS التي تم إنشاؤها بواسطة البرنامج النصي PowerShell السابق بـ '؟' (علامة استفهام). عند استخدام المفتاح SAS في البرنامج النصي T-SQL التالي، يجب عليك إزالة البادئة'؟' . وإلا فقد يتم حظر جهودك من قبل الأمن.

رمز Transact-SQL:

---- TODO: First, run the earlier PowerShell portion of this two-part code sample.
---- TODO: Second, find every 'TODO' in this Transact-SQL file, and edit each.

---- Transact-SQL code for Event File target on Azure SQL Database or SQL Managed Instance.

SET NOCOUNT ON;
GO

----  Step 1.  Establish one little table, and  ---------
----  insert one row of data.

IF EXISTS
    (SELECT * FROM sys.objects
        WHERE type = 'U' and name = 'gmTabEmployee')
BEGIN
    DROP TABLE gmTabEmployee;
END
GO

CREATE TABLE gmTabEmployee
(
    EmployeeGuid         uniqueIdentifier   not null  default newid()  primary key,
    EmployeeId           int                not null  identity(1,1),
    EmployeeKudosCount   int                not null  default 0,
    EmployeeDescr        nvarchar(256)          null
);
GO

INSERT INTO gmTabEmployee ( EmployeeDescr )
    VALUES ( 'Jane Doe' );
GO

------  Step 2.  Create key, and  ------------
------  Create credential (your Azure Storage container must already exist).

IF NOT EXISTS
    (SELECT * FROM sys.symmetric_keys
        WHERE symmetric_key_id = 101)
BEGIN
    CREATE MASTER KEY ENCRYPTION BY PASSWORD = '0C34C960-6621-4682-A123-C7EA08E3FC46' -- Or any newid().
END
GO

IF EXISTS
    (SELECT * FROM sys.database_scoped_credentials
        -- TODO: Assign AzureStorageAccount name, and the associated Container name.
        WHERE name = 'https://gmstorageaccountxevent.blob.core.windows.net/gmcontainerxevent')
BEGIN
    DROP DATABASE SCOPED CREDENTIAL
        -- TODO: Assign AzureStorageAccount name, and the associated Container name.
        [https://gmstorageaccountxevent.blob.core.windows.net/gmcontainerxevent] ;
END
GO

CREATE
    DATABASE SCOPED
    CREDENTIAL
        -- use '.blob.',   and not '.queue.' or '.table.' etc.
        -- TODO: Assign AzureStorageAccount name, and the associated Container name.
        [https://gmstorageaccountxevent.blob.core.windows.net/gmcontainerxevent]
    WITH
        IDENTITY = 'SHARED ACCESS SIGNATURE',  -- "SAS" token.
        -- TODO: Paste in the long SasToken string here for Secret, but exclude any leading '?'.
        SECRET = 'sv=2014-02-14&sr=c&si=gmpolicysastoken&sig=EjAqjo6Nu5xMLEZEkMkLbeF7TD9v1J8DNB2t8gOKTts%3D'
    ;
GO

------  Step 3.  Create (define) an event session.  --------
------  The event session has an event with an action,
------  and a has a target.

IF EXISTS
    (SELECT * from sys.database_event_sessions
        WHERE name = 'gmeventsessionname240b')
BEGIN
    DROP
        EVENT SESSION
            gmeventsessionname240b
        ON DATABASE;
END
GO

CREATE
    EVENT SESSION
        gmeventsessionname240b
    ON DATABASE

    ADD EVENT
        sqlserver.sql_statement_starting
            (
            ACTION (sqlserver.sql_text)
            WHERE statement LIKE 'UPDATE gmTabEmployee%'
            )
    ADD TARGET
        package0.event_file
            (
            -- TODO: Assign AzureStorageAccount name, and the associated Container name.
            -- Also, tweak the .xel file name at end, if you like.
            SET filename =
                'https://gmstorageaccountxevent.blob.core.windows.net/gmcontainerxevent/anyfilenamexel242b.xel'
            )
    WITH
        (MAX_MEMORY = 10 MB,
        MAX_DISPATCH_LATENCY = 3 SECONDS)
    ;
GO

------  Step 4.  Start the event session.  ----------------
------  Issue the SQL Update statements that will be traced.
------  Then stop the session.

------  Note: If the target fails to attach,
------  the session must be stopped and restarted.

ALTER
    EVENT SESSION
        gmeventsessionname240b
    ON DATABASE
    STATE = START;
GO

SELECT 'BEFORE_Updates', EmployeeKudosCount, * FROM gmTabEmployee;

UPDATE gmTabEmployee
    SET EmployeeKudosCount = EmployeeKudosCount + 2
    WHERE EmployeeDescr = 'Jane Doe';

UPDATE gmTabEmployee
    SET EmployeeKudosCount = EmployeeKudosCount + 13
    WHERE EmployeeDescr = 'Jane Doe';

SELECT 'AFTER__Updates', EmployeeKudosCount, * FROM gmTabEmployee;
GO

ALTER
    EVENT SESSION
        gmeventsessionname240b
    ON DATABASE
    STATE = STOP;
GO

-------------- Step 5.  Select the results. ----------

SELECT
        *, 'CLICK_NEXT_CELL_TO_BROWSE_ITS_RESULTS!' as [CLICK_NEXT_CELL_TO_BROWSE_ITS_RESULTS],
        CAST(event_data AS XML) AS [event_data_XML]  -- TODO: In ssms.exe results grid, double-click this cell!
    FROM
        sys.fn_xe_file_target_read_file
            (
                -- TODO: Fill in Storage Account name, and the associated Container name.
                -- TODO: The name of the .xel file needs to be an exact match to the files in the storage account Container (You can use Storage Account explorer from the portal to find out the exact file names or you can retrieve the name using the following DMV-query: select target_data from sys.dm_xe_database_session_targets. The 3rd xml-node, "File name", contains the name of the file currently written to.)
                'https://gmstorageaccountxevent.blob.core.windows.net/gmcontainerxevent/anyfilenamexel242b',
                null, null, null
            );
GO

-------------- Step 6.  Clean up. ----------

DROP
    EVENT SESSION
        gmeventsessionname240b
    ON DATABASE;
GO

DROP DATABASE SCOPED CREDENTIAL
    -- TODO: Assign AzureStorageAccount name, and the associated Container name.
    [https://gmstorageaccountxevent.blob.core.windows.net/gmcontainerxevent]
    ;
GO

DROP TABLE gmTabEmployee;
GO

PRINT 'Use PowerShell Remove-AzStorageAccount to delete your Azure Storage account!';
GO

إذا فشل الهدف في الإرفاق عند التشغيل، يجب عليك إيقاف وإعادة تشغيل جلسة الحدث:

ALTER EVENT SESSION gmeventsessionname240b
    ON DATABASE STATE = STOP;
GO
ALTER EVENT SESSION gmeventsessionname240b
    ON DATABASE STATE = START;
GO

المخرجات

عند اكتمال البرنامج النصي Transact-SQL، حدد خلية أسفل رأس العمود event_data_XML. يتم عرض عنصر <حدث> واحد، الذي يظهر عبارة UPDATE واحدة.

فيما يلي عنصر <حدث> واحد تم إنشاؤه أثناء الاختبار:

<event name="sql_statement_starting" package="sqlserver" timestamp="2015-09-22T19:18:45.420Z">
  <data name="state">
    <value>0</value>
    <text>Normal</text>
  </data>
  <data name="line_number">
    <value>5</value>
  </data>
  <data name="offset">
    <value>148</value>
  </data>
  <data name="offset_end">
    <value>368</value>
  </data>
  <data name="statement">
    <value>UPDATE gmTabEmployee
    SET EmployeeKudosCount = EmployeeKudosCount + 2
    WHERE EmployeeDescr = 'Jane Doe'</value>
  </data>
  <action name="sql_text" package="sqlserver">
    <value>

SELECT 'BEFORE_Updates', EmployeeKudosCount, * FROM gmTabEmployee;

UPDATE gmTabEmployee
    SET EmployeeKudosCount = EmployeeKudosCount + 2
    WHERE EmployeeDescr = 'Jane Doe';

UPDATE gmTabEmployee
    SET EmployeeKudosCount = EmployeeKudosCount + 13
    WHERE EmployeeDescr = 'Jane Doe';

SELECT 'AFTER__Updates', EmployeeKudosCount, * FROM gmTabEmployee;
</value>
  </action>
</event>

استخدم البرنامج النصي Transact-SQL السابق دالة النظام التالية لقراءة event_file:

sys.fn_xe_file_target_read_file (Transact-SQL)

يتوفر شرح للخيارات المتقدمة لعرض البيانات من الأحداث الموسعة على:

عرض متقدم للبيانات المستهدفة من الأحداث الموسعة

تحويل نموذج التعليمات البرمجية للتشغيل على SQL Server

افترض أنك تريد تشغيل نموذج Transact-SQL السابق على Microsoft SQL Server.

للتبسيط، قد تحتاج إلى استبدال استخدام حاوية تخزين Azure بملف بسيط تمامًا مثل C:\myeventdata.xel. ستتم كتابة الملف إلى القرص الثابت الداخلي للكمبيوتر الذي يستضيف SQL Server.
لن تحتاج إلى أي نوع من عبارات Transact-SQL ل CREATE MASTER KEY و CREATE CREDENTIAL.
في عبارةCREATE EVENT SESSION، في جملة ADD TARGET الخاصة بها، يمكنك استبدال قيمة Http المعينة لـ إلى اسم الملف = بسلسلة مسار كامل مثل C:\myfile.xel.
- ليس هناك حاجة إلى حساب Azure Storage.

الخطوات التالية

لمزيد من المعلومات حول الحسابات والحاويات في خدمة تخزين Azure، راجع:

مشاركة عبر