مشاركة عبر

واجهة برمجة تطبيقات استيعاب السجلات في Azure Monitor

  • مقالة

تتيح لك واجهة برمجة تطبيقات استيعاب السجلات في Azure Monitor إرسال البيانات إلى مساحة عمل Log Analytics باستخدام استدعاء واجهة برمجة تطبيقات REST أو مكتبات العميل. تسمح لك واجهة برمجة التطبيقات بإرسال البيانات إلى جداول Azure المدعومة أو إلى الجداول المخصصة التي تقوم بإنشائها. يمكنك أيضا توسيع مخطط جداول Azure بأعمدة مخصصة لقبول بيانات إضافية.

العملية الأساسية

يمكن إرسال البيانات إلى واجهة برمجة تطبيقات استيعاب السجلات من أي تطبيق يمكنه إجراء استدعاء REST API. قد يكون هذا تطبيقا مخصصا تقوم بإنشائه، أو قد يكون تطبيقا أو وكيلا يفهم كيفية إرسال البيانات إلى واجهة برمجة التطبيقات. يحدد قاعدة تجميع البيانات (DCR) التي تتضمن الجدول الهدف ومساحة العمل وبيانات اعتماد تسجيل التطبيق مع الوصول إلى DCR المحدد. يرسل البيانات إلى نقطة نهاية محددة بواسطة DCR، أو إلى نقطة نهاية تجميع البيانات (DCE) إذا كنت تستخدم رابطا خاصا.

يجب تنسيق البيانات المرسلة من قبل التطبيق الخاص بك إلى واجهة برمجة التطبيقات في JSON ومطابقة البنية المتوقعة من قبل DCR. لا يحتاج بالضرورة إلى مطابقة بنية الجدول الهدف لأن DCR يمكن أن يتضمن تحويلا لتحويل البيانات لمطابقة بنية الجدول. يمكنك تعديل الجدول الهدف ومساحة العمل عن طريق تعديل DCR دون أي تغيير في استدعاء واجهة برمجة التطبيقات أو بيانات المصدر.

رسم تخطيطي يوضح نظرة عامة على واجهة برمجة تطبيقات استيعاب السجلات.

التكوين

يصف الجدول التالي كل مكون في Azure يجب تكوينه قبل أن تتمكن من استخدام واجهة برمجة تطبيقات استيعاب السجلات.

إشعار

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

المكون الدالة
تسجيل التطبيق والبيانات السرية يتم استخدام تسجيل التطبيق لمصادقة استدعاء واجهة برمجة التطبيقات. يجب منحه الإذن إلى DCR الموضح أدناه. يتضمن استدعاء واجهة برمجة التطبيقات معرف التطبيق (العميل) ومعرف الدليل (المستأجر) للتطبيق وقيمة سر التطبيق.

راجع إنشاء تطبيق Microsoft Entra ومدير الخدمة الذي يمكنه الوصول إلى الموارد وإنشاء سر تطبيق جديد.
جدول في مساحة عمل Log Analytics يجب أن يكون الجدول في مساحة عمل Log Analytics موجودا قبل أن تتمكن من إرسال البيانات إليه. يمكنك استخدام أحد جداول Azure المدعومة أو إنشاء جدول مخصص باستخدام أي من الطرق المتوفرة. إذا كنت تستخدم مدخل Microsoft Azure لإنشاء الجدول، إنشاء DCR لك، بما في ذلك التحويل إذا كان مطلوبا. مع أي أسلوب آخر، تحتاج إلى إنشاء DCR يدويا كما هو موضح في القسم التالي.

راجع إنشاء جدول مخصص.
قاعدة جمع البيانات (DCR) يستخدم Azure Monitor قاعدة جمع البيانات (DCR) لفهم بنية البيانات الواردة وما يجب فعله بها. إذا لم تتطابق بنية الجدول والبيانات الواردة، يمكن أن يتضمن DCR تحويلا لتحويل البيانات المصدر لمطابقة الجدول الهدف. يمكنك أيضا استخدام التحويل لتصفية بيانات المصدر وإجراء أي حسابات أو تحويلات أخرى.

إذا قمت بإنشاء جدول مخصص باستخدام مدخل Microsoft Azure، يتم إنشاء DCR والتحويل لك استنادا إلى عينة البيانات التي توفرها. إذا كنت تستخدم جدولا موجودا أو أنشأت جدولا مخصصا باستخدام أسلوب آخر، فيجب عليك إنشاء DCR يدويا باستخدام التفاصيل في القسم التالي.

بمجرد إنشاء DCR الخاص بك، يجب منح حق الوصول إليه للتطبيق الذي قمت بإنشائه في الخطوة الأولى. من قائمة Monitor في مدخل Microsoft Azure، حدد Data Collection rules ثم DCR الذي قمت بإنشائه. حدد Access Control (IAM) ل DCR ثم حدد Add role assignment لإضافة دور Monitoring Metrics Publisher .

نقطة النهاية

يمكن أن تكون نقطة نهاية REST API لواجهة برمجة تطبيقات استيعاب السجلات إما نقطة نهاية تجميع بيانات (DCE) أو نقطة نهاية استيعاب سجلات DCR.

يتم إنشاء نقطة نهاية استيعاب سجلات DCR عند إنشاء DCR للاستيعاب المباشر. لاسترداد نقطة النهاية هذه، افتح DCR في طريقة عرض JSON في مدخل Microsoft Azure. قد تحتاج إلى تغيير إصدار واجهة برمجة التطبيقات إلى أحدث إصدار لنقاط النهاية التي سيتم عرضها.

لقطة شاشة تعرض نقطة نهاية استيعاب السجل في DCR.

مطلوب DCE فقط عند الاتصال بمساحة عمل Log Analytics باستخدام ارتباط خاص أو إذا لم يتضمن DCR نقطة نهاية استيعاب السجلات. قد يكون هذا هو الحال إذا كنت تستخدم DCR أقدم أو إذا قمت بإنشاء DCR بدون المعلمة "kind": "Direct" . راجع قاعدة جمع البيانات (DCR) أدناه لمزيد من التفاصيل.

إشعار

logsIngestion تمت إضافة العقار في 31 مارس 2024. قبل هذا التاريخ، كان DCE مطلوبا لواجهة برمجة تطبيقات استيعاب السجلات. لا يمكن إضافة نقاط النهاية إلى DCR موجود، ولكن يمكنك الاستمرار في استخدام أي DCRs موجودة مع DCEs الموجودة. إذا كنت تريد الانتقال إلى نقطة نهاية DCR، فيجب عليك إنشاء DCR جديد لاستبدال تلك الموجودة. يمكن ل DCR مع نقاط النهاية أيضا استخدام DCE. في هذه الحالة، يمكنك اختيار ما إذا كنت تريد استخدام نقاط نهاية DCE أو DCR لكل عميل من العملاء الذين يستخدمون DCR.

قاعدة جمع البيانات (DCR)

عند إنشاء جدول مخصص في مساحة عمل Log Analytics باستخدام مدخل Microsoft Azure، يتم إنشاء DCR الذي يمكن استخدامه مع واجهة برمجة تطبيقات استيعاب السجلات لك. إذا كنت ترسل بيانات إلى جدول موجود بالفعل، فيجب عليك إنشاء DCR يدويا. ابدأ بنموذج DCR أدناه، مع استبدال قيم المعلمات التالية في القالب. استخدم أي من الطرق الموضحة في إنشاء قواعد جمع البيانات (DCRs) وتحريرها في Azure Monitor لإنشاء DCR.

المعلمة ‏‏الوصف‬
region المنطقة لإنشاء DCR الخاص بك. يجب أن يتطابق هذا مع منطقة مساحة عمل Log Analytics وDCE إذا كنت تستخدم واحدة.
dataCollectionEndpointId معرف المورد ل DCE الخاص بك. قم بإزالة هذه المعلمة إذا كنت تستخدم نقطة استيعاب DCR.
streamDeclarations قم بتغيير قائمة الأعمدة إلى الأعمدة في البيانات الواردة. لا تحتاج إلى تغيير اسم الدفق لأن هذا يحتاج فقط إلى مطابقة streams الاسم في dataFlows.
workspaceResourceId معرف المورد لمساحة عمل Log Analytics. لا تحتاج إلى تغيير الاسم لأن هذا يحتاج فقط إلى مطابقة destinations الاسم في dataFlows.
transformKql سيتم تطبيق استعلام KQL على البيانات الواردة. إذا كان مخطط البيانات الواردة يطابق مخطط الجدول، فيمكنك استخدام source للتحويل الذي سيمرر البيانات الواردة دون تغيير. وإلا، استخدم استعلاما يقوم بتحويل البيانات لمطابقة مخطط الجدول الوجهة.
outputStream اسم الجدول لإرسال البيانات. بالنسبة لجدول مخصص، أضف البادئة Custom-table-name><. بالنسبة إلى جدول مضمن، أضف البادئة Microsoft-table-name><. 
{
    "location": "eastus",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-eastus",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

مكتبات العميل

بالإضافة إلى إجراء استدعاء REST API، يمكنك استخدام مكتبات العميل التالية لإرسال البيانات إلى واجهة برمجة تطبيقات استيعاب السجلات. تتطلب المكتبات نفس المكونات الموضحة في التكوين. للحصول على أمثلة باستخدام كل من هذه المكتبات، راجع نموذج التعليمات البرمجية لإرسال البيانات إلى Azure Monitor باستخدام واجهة برمجة تطبيقات استيعاب السجلات.

استدعاء واجهة برمجة تطبيقات REST

لإرسال البيانات إلى Azure Monitor باستخدام استدعاء REST API، قم بإجراء مكالمة POST عبر HTTP. يتم وصف التفاصيل المطلوبة لهذه المكالمة في هذا القسم.

URI

يتضمن URI المنطقة ونقطة نهاية استيعاب DCE أو DCR ومعرف DCR واسم الدفق. كما أنه يحدد إصدار واجهة برمجة التطبيقات.

يستخدم URI التنسيق التالي.

{Endpoint}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

على سبيل المثال:

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

DCR Immutable ID يتم إنشاء ل DCR عند إنشائه. يمكنك استرداده من صفحة نظرة عامة ل DCR في مدخل Microsoft Azure.

لقطة شاشة لقاعدة تجميع بيانات تعرض المعرف غير القابل للتغيير.

Stream Name يشير إلى الدفق في DCR الذي يجب أن يعالج البيانات المخصصة.

الرؤوس

يصف الجدول التالي تلك الرؤوس لاستدعاء واجهة برمجة التطبيقات.

الرأس مطلوب؟ ‏‏الوصف
التصريح ‏‏نعم‬ الرمز المميز للحامل الذي تم الحصول عليه من خلال تدفق بيانات اعتماد العميل. استخدم قيمة جمهور الرمز المميز للسحابة الخاصة بك:

سحابة Azure العامة - https://monitor.azure.com
Microsoft Azure المشغل بواسطة سحابة 21Vianet - https://monitor.azure.cn
سحابة Azure US Government - https://monitor.azure.us
نوع المحتوى ‏‏نعم‬ application/json
المحتوى-الترميز لا gzip
x-ms-client-request-id لا GUID منسق بالسلسلة. هذا هو معرف الطلب الذي يمكن استخدامه من قبل Microsoft لأي أغراض استكشاف الأخطاء وإصلاحها.

النص الأساسي

يتضمن نص الاستدعاء البيانات المخصصة التي سيتم إرسالها إلى Azure Monitor. يجب أن يكون شكل البيانات صفيف JSON مع بنية عنصر تطابق التنسيق المتوقع بواسطة الدفق في DCR. إذا كانت هناك حاجة لإرسال عنصر واحد داخل استدعاء واجهة برمجة التطبيقات، يجب إرسال البيانات كصفيف عنصر واحد.

على سبيل المثال:

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

تأكد من ترميز نص الطلب بشكل صحيح في UTF-8 لمنع أي مشكلات في نقل البيانات.

مثال

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

الجداول المدعومة

يمكن إرسال البيانات المرسلة إلى واجهة برمجة تطبيقات الاستيعاب إلى الجداول التالية:

الجداول ‏‏الوصف
جداول مخصصة أي جدول مخصص تقوم بإنشائه في مساحة عمل Log Analytics. يجب أن يكون الجدول الهدف موجودًا قبل أن تتمكن من إرسال البيانات إليه. يجب أن تحتوي الجداول المخصصة على اللاحقة _CL.
جداول Azure جداول Azure التالية مدعومة حاليا. قد تتم إضافة جداول أخرى إلى هذه القائمة عند تنفيذ الدعم لها.

إشعار

يجب أن تبدأ أسماء الأعمدة بحرف ويمكن أن تتكون من ما يصل إلى 45 حرفا أبجديا رقميا وتسطيرا أسفل السطر (_). _ResourceIdidTypeTitle _ResourceId_SubscriptionIdTenantIdUniqueIdأسماء الأعمدة المحجوزة و و. يجب أن تحتوي الأعمدة المخصصة التي تضيفها إلى جدول Azure على اللاحقة _CF.

الحدود والقيود

للحصول على الحدود المتعلقة بواجهة برمجة تطبيقات استيعاب السجلات، راجع حدود خدمة Azure Monitor.

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