بنية التحويل في Azure Monitor

مقالة
06/15/2023

تسمح لك التحويلات في Azure Monitor بتصفية البيانات الواردة أو تعديلها قبل تخزينها في مساحة عمل Log Analytics. يتم تنفيذها كبيان لغة استعلام Kusto (KQL) في قاعدة تجميع البيانات (DCR). توفر هذه المقالة تفاصيل حول كيفية هيكلة هذا الاستعلام والقيود المفروضة على لغة KQL المسموح بها.

بنية التحويل

يتم تطبيق عبارة KQL بشكل فردي على كل إدخال في مصدر البيانات. يجب أن يفهم تنسيق البيانات الواردة وأن ينشئ مخرجات في بنية الجدول الهدف. يمثل الجدول الظاهري المسمى source دفق الإدخال. source تتطابق أعمدة الجدول مع تعريف دفق بيانات الإدخال. فيما يلي مثال نموذجي على تحويل ما. يتضمن هذا المثال الوظائف التالية:

تصفية البيانات الواردة باستخدام عبارة where
إضافة عمود جديد باستخدام عامل التشغيل توسيع
تنسيق الإخراج لمطابقة أعمدة الجدول الهدف باستخدام عامل تشغيل المشروع

source  
| where severity == "Critical" 
| extend Properties = parse_json(properties)
| project
    TimeGenerated = todatetime(["time"]),
    Category = category,
    StatusDescription = StatusDescription,
    EventName = name,
    EventId = tostring(Properties.EventId)

قيود KQL

نظراً لتطبيق التحويل على كل سجل على حدة، فإنه لا يمكنه استخدام أي عوامل تشغيل KQL تعمل على سجلات متعددة. يتم دعم عوامل التشغيل التي تأخذ صفاً واحداً كإدخال فقط ولا ترجع أكثر من صف واحد. على سبيل المثال، التلخيص غير مدعوم لأنه يلخص سجلات متعددة. راجع ميزات KQL المدعومة للحصول على قائمة كاملة بالميزات المدعومة.

تسمح لك التحويلات في قاعدة جمع البيانات (DCR) بتصفية البيانات الواردة أو تعديلها قبل تخزينها في مساحة عمل Log Analytics. توضح هذه المقالة كيفية إنشاء تحويلات في DCR، بما في ذلك تفاصيل وقيود لغة استعلام Kusto (KQL) المستخدمة لعبارة التحويل.

الأعمدة المطلوبة

يجب أن يحتوي إخراج كل تحويل على طابع زمني صالح في عمود يسمى TimeGenerated من النوع datetime. تأكد من تضمينه في النهائي extend أو project الكتلة! سيؤدي إنشاء DCR أو تحديثه بدون TimeGenerated في إخراج التحويل إلى حدوث خطأ.

معالجة البيانات الديناميكية

ضع في اعتبارك الإدخال التالي مع البيانات الديناميكية:

{
    "TimeGenerated" : "2021-11-07T09:13:06.570354Z",
    "Message": "Houston, we have a problem",
    "AdditionalContext": {
        "Level": 2,
        "DeviceID": "apollo13"
    }
}

للوصول إلى الخصائص في AdditionalContext، قم بتعريفه على أنه عمود من النوع الديناميكي في دفق الإدخال:

"columns": [
    {
        "name": "TimeGenerated",
        "type": "datetime"
    },
    {
        "name": "Message",
        "type": "string"
    }, 
    {
        "name": "AdditionalContext",
        "type": "dynamic"
    }
]

يمكن الآن تحليل محتوى العمود AdditionalContext واستخدامه في تحويل KQL:

source
| extend parsedAdditionalContext = parse_json(AdditionalContext)
| extend Level = toint (parsedAdditionalContext.Level)
| extend DeviceId = tostring(parsedAdditionalContext.DeviceID)

القيم الحرفية الديناميكية

استخدم الدالة parse_json للتعامل مع القيم الحرفية الديناميكية.

على سبيل المثال، توفر الاستعلامات التالية نفس الوظيفة:

print d=dynamic({"a":123, "b":"hello", "c":[1,2,3], "d":{}})

print d=parse_json('{"a":123, "b":"hello", "c":[1,2,3], "d":{}}')

ميزات KQL المدعومة

العبارات المدعومة

عبارة let

قد يكون الجانب الأيمن من let تعبيراً عددياً أو تعبيراً جدولياً أو دالة محددة من قبل المستخدم. يتم دعم الوظائف المعرفة من قبل المستخدم فقط مع الوسيطات العددية.

عبارات التعبير الجدولي

مصادر البيانات المدعومة فقط لعبارة KQL هي كما يلي:

المصدر، الذي يمثل بيانات المصدر. على سبيل المثال:

source
| where ActivityId == "383112e4-a7a8-4b94-a701-4266dfc18e41"
| project PreciseTimeStamp, Message

عامل تشغيل print، الذي ينتج دائماً صفاً واحداً. على سبيل المثال:

print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)

عوامل تشغيل الجدولة

extend
project
print
حيث
parse
خارج المشروع
إعادة تسمية المشروع
جدول البيانات
columnifexists (استخدم columnifexists بدلاً من column_ifexists)

عوامل عددية

==
!=
=~
!~
تحتوي على
!contains
contains_cs
!contains_cs
has
!قد
has_cs
!has_cs
startswith
!startswith
startswith_cs
!startswith_cs
endswith
!endswith
endswith_cs
!endswith_cs
matches regex
في
!in

عوامل تشغيل Bitwise

يتم دعم عوامل تشغيل Bitwise التالية.

binary_and()
binary_or()
binary_xor()
binary_not()
binary_shift_left()
binary_shift_right()

دالات عددية

دوال Bitwise

دالات التحويل

دالات التاريخ والوقت والفترات الزمنية

الدالات الديناميكية ودالات الصفيف

الدالات الحسابية

الدالات الشرطية

دالات السلسلة

base64_encodestring (استخدم base64_encodestring بدلاً من base64_encode_tostring)
base64_decodestring (استخدم base64_decodestring بدلاً من base64_decode_tostring)
countof
extract
extract_all
indexof
isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
strlen
substring
tolower
toupper
hash_sha256

دوال النوع

دوال خاصة

parse_cef_dictionary

نظرا لسلسلة تحتوي على رسالة CEF، parse_cef_dictionary يوزع خاصية Extension للرسالة في عنصر مفتاح/قيمة ديناميكي. الفاصلة المنقطة هي حرف محجوز يجب استبداله قبل تمرير الرسالة الأولية إلى الأسلوب، كما هو موضح في المثال.

| extend cefMessage=iff(cefMessage contains_cs ";", replace(";", " ", cefMessage), cefMessage) 
| extend parsedCefDictionaryMessage =parse_cef_dictionary(cefMessage) 
| extend parsecefDictionaryExtension = parsedCefDictionaryMessage["Extension"]
| project TimeGenerated, cefMessage, parsecefDictionaryExtension

geo_location

نظرا لسلسلة تحتوي على عنوان IP (يتم دعم IPv4 وIPv6)، geo_location ترجع الدالة الموقع الجغرافي التقريبي، بما في ذلك السمات التالية:

الدولة
المنطقة
المنطقة
المدينة
خط العرض
خط الطول

| extend GeoLocation = geo_location("1.0.0.5")

هام

نظرا لطبيعة خدمة تحديد الموقع الجغرافي IP المستخدمة من قبل هذه الدالة، قد تقدم زمن انتقال استيعاب البيانات إذا تم استخدامها بشكل مفرط. توخي الحذر عند استخدام هذه الدالة أكثر من عدة مرات لكل تحويل.

اقتباس المعرف

استخدم اقتباس المعرف كما هو مطلوب.

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

إنشاء قاعدة تجميع بيانات والاقتران بها من جهاز ظاهري باستخدام عامل Azure Monitor.

مشاركة عبر

بنية التحويل في Azure Monitor