مشاركة عبر

تعرف على كيفية تسجيل الأحداث في مراكز الأحداث Azure Event Hubs في APIM.

  • مقالة

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

توضح هذه المقالة طريقة تسجيل الأحداث في مراكز الأحداث Azure Event Hubs في APIM.

مراكز الأحداث هي خدمة إدخال البيانات قابلة للتطوير بدرجة كبيرة التي يمكنها استيعاب ملايين الأحداث في الثانية بحيث يمكنك معالجة وتحليل الكميات الهائلة من البيانات التي تنتجها الأجهزة والتطبيقات المتصلة. تعمل مراكز الأحداث بمثابة «الباب الأمامي» للبنية الأساسية لبرنامج ربط العمليات التجارية، وبمجرد جمع البيانات في مركز الأحداث، يمكن تحويلها وتخزينها باستخدام أي موفر تحليلات في الوقت الحقيقي أو محولات الدفعات / التخزين. تقوم مراكز الأحداث Event Hubs بفصل إنتاج دفق الأحداث عن استهلاك تلك الأحداث، بحيث يمكن للمستهلكين الوصول إلى الأحداث في الجدول الزمني الخاص بهم.

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

تكوين الوصول إلى مركز الأحداث

لتسجيل الأحداث إلى مركز الأحداث، تحتاج إلى تكوين بيانات الاعتماد للوصول من APIM. تدعم APIM أي من آليتي الوصول التاليتين:

  • سلسلة الاتصال مراكز الأحداث
  • هوية مدارة لمثيل APIM الخاص بك.

الخيار 1: تكوين مراكز الأحداث سلسلة الاتصال

لإنشاء سلسلة الاتصال مراكز الأحداث، راجع الحصول على مراكز الأحداث سلسلة الاتصال.

  • يمكنك استخدام سلسلة الاتصال لمساحة اسم مراكز الأحداث أو لمركز الأحداث المحدد الذي تستخدمه للتسجيل من APIM.
  • يجب أن يقوم نهج الوصول المشترك سلسلة الاتصال بتمكين أذونات الإرسال على الأقل.

الخيار 2: تكوين الهوية المدارة لإدارة واجهة برمجة التطبيقات

إشعار

يتم دعم استخدام هوية مدارة من API Management لتسجيل الأحداث إلى مركز أحداث في إصدار 2022-04-01-preview API Management REST API أو أحدث.

  1. قم بتمكين الهوية المُدارة المعينة من قبل النظام أو من قبل المستخدم لإدارة واجهة برمجة التطبيقات في مثيل إدارة واجهة برمجة التطبيقات.

    • إذا قمت بتمكين هوية مُدارة يعينها المستخدم، فقم بتدوين معرف العميل للهوية.

  2. قم بتعيين الهوية لدور مرسل بيانات مراكز الأحداث، محدد النطاق إلى مساحة اسم مراكز الأحداث أو إلى مركز الأحداث المستخدم للتسجيل. لتعيين الدور، استخدم مدخل Microsoft Azure أو أدوات Azure الأخرى.

إنشاء مسجّل خدمة APIM

الخطوة التالية هي تكوين مسجل في خدمة APIM بحيث يمكنه تسجيل الأحداث إلى مركز الأحداث.

إنشاء وإدارة مسجلات APIM باستخدام API Management REST API مباشرة أو باستخدام أدوات بما في ذلك Azure PowerShell أو قالب Bicep أو قالب Azure Resource Management.

المسجل مع بيانات اعتماد سلسلة الاتصال

للحصول على المتطلبات الأساسية، راجع تكوين مراكز الأحداث سلسلة الاتصال.

يستخدم المثال التالي New-AzApiManagementLogger cmdlet لإنشاء مسجل إلى مركز أحداث عن طريق تكوين سلسلة الاتصال.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# Create logger
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName
New-AzApiManagementLogger -Context $context -LoggerId "ContosoLogger1" -Name "ApimEventHub" -ConnectionString "Endpoint=sb://<EventHubsNamespace>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>" -Description "Event hub logger with connection string"

المسجل مع بيانات اعتماد الهوية المدارة المعينة من قبل النظام

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

استخدم API Management REST API أو قالب Bicep أو ARM لتكوين مسجل إلى مركز أحداث باستخدام بيانات اعتماد الهوية المدارة المعينة من قبل النظام.

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "adding a new logger with system assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"SystemAssigned",
         "name":"<EventHubName>"
    }
  }
}

المسجل مع بيانات اعتماد الهوية المدارة المعينة من قبل المستخدم

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

استخدم API Management REST API أو قالب Bicep أو ARM لتكوين مسجل إلى مركز أحداث مع بيانات اعتماد الهوية المدارة المعينة من قبل المستخدم.

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "adding a new logger with user-assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"<ClientID>",
         "name":"<EventHubName>"
    }
  }
}

تكوين نهج log-to-eventhub

بمجرد تكوين المسجل الخاص بك في APIM، يمكنك تكوين نهج log-to-eventhub لتسجيل الأحداث المطلوبة. على سبيل المثال، استخدم النهج log-to-eventhub في قسم النهج الوارد لتسجيل الطلبات، أو في قسم النهج الصادر لتسجيل الاستجابات.

  1. استعرض للوصول إلى مثيل إدارة واجهة برمجة التطبيقات.

  2. حدد واجهات برمجة التطبيقات، ثم حدد واجهة برمجة التطبيقات التي تريد إضافة النهج إليها. في هذا المثال، نقوم بإضافة سياسة إلى واجهة برمجة تطبيقات Echo في المنتجغير المحدود.

  3. حدد «جميع العمليات».

  4. في أعلى الشاشة، حدد علامة التبويب تصميم .

  5. في نافذة المعالجة الواردة أو المعالجة الصادرة، حدد الأيقونة </> (محرر التعليمات البرمجية). لمزيد من المعلومات، يرجي مراجعة طريقة تعيين النهج أو تحريرها.

  6. ضع المؤشر في inbound «المقطع أو outbound النهج».

  7. في الإطار على اليمين، حدد «النهج المتقدمة»> تسجيل الدخول إلى EventHub. يؤدي هذا إلى إدراج قالب بيان النهجlog-to-eventhub.

    <log-to-eventhub logger-id="logger-id">
    @{
        return new JObject(
            new JProperty("EventTime", DateTime.UtcNow.ToString()),
            new JProperty("ServiceName", context.Deployment.ServiceName),
            new JProperty("RequestId", context.RequestId),
            new JProperty("RequestIp", context.Request.IpAddress),
            new JProperty("OperationName", context.Operation.Name)
        ).ToString();
    }
</log-to-eventhub>
    1. استبدل logger-id باسم المسجل الذي قمت بإنشائه في الخطوة السابقة.
    2. يمكنك استخدام أي تعبير لمراجعة سلسلة كقيمة للعنصرlog-to-eventhub. في هذا المثال، يتم تسجيل سلسلة بتنسيق JSON تتضمن التاريخ والوقت واسم الخدمة ومعرف الطلب وعنوان IP واسم العملية .

  8. حدد حفظ لحفظ تكوين النهج المحدث. بمجرد حفظه، يكون النهج نشطا ويتم تسجيل الأحداث إلى مركز الأحداث المعين.

إشعار

الحد الأقصى لحجم الرسالة المعتمدة التي يمكن إرسالها إلى مركز الحدث من نهج APIM يكون 200 كيلو بايت (KB). إذا كانت الرسالة المرسلة إلى مركز أحداث أكبر من 200 كيلوبايت، فسيتم اقتطاعها تلقائيا، وسيتم نقل الرسالة المقتطعة إلى مركز الأحداث. بالنسبة للرسائل الأكبر حجما، ضع في اعتبارك استخدام Azure Storage مع Azure API Management كحل بديل لتجاوز حد 200 كيلوبايت. يمكن العثور على مزيد من التفاصيل في هذه المقالة.

قم «بمعاينة السجل في مراكز الأحداث» باستخدام تحليلات Azure Stream Analytics

يمكنك معاينة السجل في Event Hubs باستخدام استعلامات Stream Analytics.

  1. في مدخل Microsoft Azure قم بتصفح الوصول إلى مركز الأحداث Event Hub الذي يرسل المسجل الأحداث إليه.
  2. ضمن الميزات، حدد علامة التبويب «معالجة البيانات».
  3. في بطاقة Enable real time insights from events ، حدد Start.
  4. يجب أن تكون قادرًا على معاينة السجل في علامة التبويب «معاينة الإدخال» إذا لم تكن البيانات المعروضة غير محدثة، فحدد «تحديث» لمعرفة أخر الأحداث.

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