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

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

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

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

إشعار

حاليا، هذه الميزة غير متوفرة في مساحات العمل.

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

• مثيل خدمة APIM. إذا لم يكن لديك واحد، فراجع إنشاء مثيل خدمة APIM.
• مساحة اسم مراكز الأحداث ومركز الأحداث. للحصول على خطوات مفصلة، راجع إنشاء مساحة اسم لمراكز الأحداث ومركز أحداث باستخدام مدخل Microsoft Azure.

  إشعار

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

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

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

• هوية مدارة لمثيل API Management (مستحسن)
• سلسلة الاتصال مراكز الأحداث

إشعار

نوصي باستخدام بيانات اعتماد الهوية المدارة عندما يكون ذلك ممكنا، لتحسين الأمان.

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

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

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

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

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

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

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

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

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

قم بإنشاء مسجلات إدارة واجهة برمجة التطبيقات وإدارتها باستخدام واجهة برمجة تطبيقات REST لإدارة واجهة برمجة التطبيقات مباشرة أو باستخدام أدوات أخرى، مثل Azure PowerShell أو ملف Bicep أو قالب Azure Resource Management.

الخيار 1: إنشاء مسجل باستخدام بيانات اعتماد الهوية المدارة (موصى به)

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

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

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

واجهة برمجة التطبيقات REST

استخدم مسجل إدارة واجهة برمجة التطبيقات - إنشاء عضو واجهة برمجة تطبيقات REST أو تحديثه باستخدام نص الطلب التالي.

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

Bicep

قم بتضمين قصاصة برمجية مشابهة للآتي في ملف Bicep.

resource ehLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'azureEventHub'
    description: 'Event hub logger with system-assigned managed identity'
    credentials: {
      endpointAddress: '<EventHubsNamespace>.servicebus.windows.net'
      identityClientId: 'systemAssigned'
      name: '<EventHubName>'
    }
  }
}

ذراع

قم بتضمين قصاصة برمجية JSON مشابهة للآتي في قالب Azure Resource Manager.

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with system-assigned managed identity",
    "resourceId": "<EventHubsResourceID>",
    "credentials": {
      "endpointAddress": "<EventHubsNamespace>.servicebus.windows.net",
      "identityClientId": "SystemAssigned",
      "name": "<EventHubName>"
    },
  }
}

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

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

واجهة برمجة التطبيقات REST

استخدم مسجل إدارة واجهة برمجة التطبيقات - إنشاء عضو واجهة برمجة تطبيقات REST أو تحديثه باستخدام نص الطلب التالي.

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

Bicep

قم بتضمين قصاصة برمجية مشابهة للآتي في ملف Bicep.

resource ehLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'azureEventHub'
    description: 'Event Hub logger with user-assigned managed identity'
    credentials: {
      endpointAddress: '<EventHubsNamespace>.servicebus.windows.net'
      identityClientId: '<ClientID>'
      name: '<EventHubName>'
    }
  }
}

ذراع

قم بتضمين قصاصة برمجية JSON مشابهة للآتي في قالب Azure Resource Manager.

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with user-assigned managed identity",
    "resourceId": "<EventHubsResourceID>",
    "credentials": {
      "endpointAddress": "<EventHubsNamespace>.servicebus.windows.net",
      "identityClientId": "<ClientID>",
      "name": "<EventHubName>"
    },
  }
}

الخيار 2. إنشاء مسجل باستخدام بيانات اعتماد سلسلة الاتصال

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

إشعار

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

بوويرشيل

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

# Details specific to API Management 
$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"

Bicep

قم بتضمين قصاصة برمجية مشابهة للآتي في ملف Bicep.

resource ehLoggerWithConnectionString 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'azureEventHub'
    description: 'Event Hub logger with connection string credentials'
    credentials: {
      connectionString: 'Endpoint=sb://<EventHubsNamespace>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>'
      name: 'ApimEventHub'
    }
  }
}

ذراع

قم بتضمين قصاصة برمجية JSON مشابهة للآتي في قالب Azure Resource Manager.

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with connection string credentials",
    "resourceId": "<EventHubsResourceID>"
    "credentials": {
      "connectionString": "Endpoint=sb://<EventHubsNamespace>/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>",
      "name": "ApimEventHub"
    },
  }
}

تكوين نهج تسجيل الدخول إلى eventhub

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

1. انتقل إلى مثيل APIM الخاص بك.

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

3. على علامة التبويب تصميم ، حدد كافة العمليات.

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

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

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

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

إشعار

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

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

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

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

المحتوى ذو الصلة

• تعرف على المزيد حول Azure Event Hubs
  • بدء عمل مركز الأحداث Azure Event Hubs
  • إرسال الأحداث إلى مراكز الأحداث واستلامها منها باستخدام .NET
  • عينات Azure.Messaging.EventHubs
• تعرف على المزيد حول إدارة واجهة برمجة التطبيقات وتكامل مراكز الأحداث
  • مرجع كيان المسجّل
  • مرجع نهج تسجيل الدخول إلى الحدث
• تعرف على مزيد من المعلومات بشأنالتكامل مع Azure Application Insights