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

  • مقالة

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

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

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

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

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

التكوين

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

إشعار

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

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

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

راجع إنشاء نقطة نهاية لجمع البيانات.
جدول في مساحة عمل 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 .

إنشاء DCR يدويا

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

المعلمة ‏‏الوصف‬
region المنطقة لإنشاء DCR الخاص بك. يجب أن يتطابق هذا مع منطقة DCE ومساحة عمل Log Analytics.
dataCollectionEndpointId معرف المورد ل DCE الخاص بك.
streamDeclarations قم بتغيير قائمة الأعمدة إلى الأعمدة في البيانات الواردة. لا تحتاج إلى تغيير اسم الدفق لأن هذا يحتاج فقط إلى مطابقة streams الاسم في dataFlows.
workspaceResourceId معرف المورد لمساحة عمل Log Analytics. لا تحتاج إلى تغيير الاسم لأن هذا يحتاج فقط إلى مطابقة destinations الاسم في dataFlows.
transformKql سيتم تطبيق استعلام KQL على البيانات الواردة. إذا كان مخطط البيانات الواردة يطابق مخطط الجدول، فيمكنك استخدام source للتحويل الذي سيمرر البيانات الواردة دون تغيير. وإلا، استخدم استعلاما يقوم بتحويل البيانات لمطابقة مخطط الجدول.
outputStream اسم الجدول لإرسال البيانات. بالنسبة لجدول مخصص، أضف البادئة Custom-table-name><. بالنسبة إلى جدول مضمن، أضف البادئة Microsoft-table-name><.

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

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

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

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

نقطة النهاية URI

يستخدم URI لنقطة النهاية التنسيق التالي، حيث Data Collection Endpoint يحدد وDCR Immutable ID DCE وDCR. يتم إنشاء المعرف غير القابل للتغيير ل DCR عند إنشائه. يمكنك استرداده من طريقة عرض JSON ل DCR في مدخل Microsoft Azure. Stream Name يشير إلى الدفق في DCR الذي يجب أن يعالج البيانات المخصصة.

{Data Collection Endpoint URI}/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

الرؤوس

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

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

سحابة 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.

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