كيفية تكامل Azure API Management مع Azure Application Insights

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

يمكنك بسهولة إجراء تكامل Azure Application Insights مع Azure API Management. Azure Application Insights هي خدمة قابلة للتوسعة لمطوري الويب الذين يقومون بإنشاء وإدارة التطبيقات على منصات متعددة. في هذا الدليل، سوف:

• اطلع على تكامل Application Insights في APIM.
• تتعلم إستراتيجيات للحد من تأثير الأداء على مثيل خدمة API Management.

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

• تحتاج إلى مثيل Azure API Management. إنشاء مثيل أولاً.

• لاستخدام Application Insights، قم بإنشاء مثيل لخدمة Application Insights. لإنشاء مثيل باستخدام مدخل Azure، راجع موارد Application Insights يستند إلى مساحة العمل.

  إشعار

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

• إذا كنت تخطط لتكوين هوية مدارة لإدارة واجهة برمجة التطبيقات لاستخدامها مع Application Insights، فستحتاج إلى إكمال الخطوات التالية:

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

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

  2. تعيين الهوية دور ناشر مقاييس المراقبة، المحدد في نطاق مورد Application Insights. لتعيين الدور، استخدم مدخل Microsoft Azure أو أدوات Azure الأخرى.

نظرة عامة على السيناريو

فيما يلي خطوات عالية المستوى لهذا السيناريو.

1. أولا، يمكنك إنشاء اتصال بين Application Insights وAPIM

   يمكنك إنشاء اتصال بين Application Insights وإدارة واجهة برمجة التطبيقات باستخدام مدخل Microsoft Azure أو واجهة برمجة تطبيقات REST أو أدوات Azure ذات الصلة. تقوم APIM بتكوين مورد مسجل للاتصال.

   إشعار

   إذا كان مورد Application Insights الخاص بك في مستأجر مختلف، فيجب عليك إنشاء المسجل باستخدام واجهة برمجة تطبيقات REST.

   هام

   حاليا، في المدخل، تدعم APIM فقط الاتصالات ب Application Insights باستخدام مفتاح تقرير عن حالة النظام Application Insights. لاستخدام سلسلة الاتصال Application Insights أو هوية مدارة من APIM، استخدم قالب REST API أو Bicep أو ARM لإنشاء المسجل. تعرف على المزيد حول سلسلة الاتصال Application Insights.

2. ثانيا، يمكنك تمكين تسجيل Application Insights لواجهة برمجة التطبيقات أو واجهات برمجة التطبيقات.

   في هذه المقالة، يمكنك تمكين تسجيل Application Insights لواجهة برمجة التطبيقات الخاصة بك باستخدام مدخل Microsoft Azure. تقوم APIM بتكوين مورد تشخيص لواجهة برمجة التطبيقات.

إنشاء اتصال باستخدام مدخل Microsoft Azure

اتبع هذه الخطوات لاستخدام مدخل Microsoft Azure لإنشاء اتصال بين Application Insights وAPIM.

1. انتقل إلى مثيل خدمة Azure API Management في مدخل Microsoft Azure.

2. حدد Application Insights من القائمة على اليسار.

3. حدد + إضافة.
   

4. حدد مثيل Application Insights قمت بإنشائه مسبقاً، ثم قم بتقديم وصف قصير.

5. لتمكين مراقبة توفر مثيل إدارة API في Application Insights، حدد خانة الاختيار إضافة مراقبة التوفر.

   • يتحقق هذا الإعداد بانتظام ما إذا كانت نقطة تقديم بوابة APIM تستجيب.
   • تظهر النتائج في جزء التوفر من مثيل Application Insights.

6. حدد إنشاء.

7. تحقق من ظهور مسجل Application Insights الجديد الآن في القائمة.

   

إشعار

خلف الكواليس، يتم إنشاء كيان مسجل في مثيل APIM الخاص بك، يحتوي على مفتاح الأجهزة لمثيل Application Insights.

تلميح

إذا كنت بحاجة إلى تحديث مفتاح الأجهزة المكون في مسجل Application Insights، فحدد صف المسجل في القائمة (وليس اسم المسجل). أدخل مفتاح تقرير عن حالة النظام، وحدد حفظ.

إنشاء اتصال باستخدام قالب REST API أو Bicep أو ARM

اتبع هذه الخطوات لاستخدام قالب REST API أو Bicep أو ARM لإنشاء اتصال بين Application Insights وAPIM. يمكنك تكوين مسجل يستخدم سلسلة الاتصال أو هوية مدارة معينة من قبل النظام أو هوية مدارة يعينها المستخدم.

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

يظهر سلسلة الاتصال Application Insights في قسم Overview في مورد Application Insights.

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

استخدم API Management REST API مع نص الطلب التالي.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

Bicep

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

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with connection string'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
    }
  }
}

ARM

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

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "resourceId": "<ApplicationInsightsResourceID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
    },
  }
}

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

راجع المتطلبات الأساسية لاستخدام هوية مدارة لإدارة واجهة برمجة التطبيقات.

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

استخدم API Management REST API مع نص الطلب التالي.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

Bicep

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

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with system-assigned managed identity'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
      identityClientId: 'systemAssigned'
    }
  }
}

ARM

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

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "resourceId": "<ApplicationInsightsResourceID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "SystemAssigned"
    }
  }
}

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

راجع المتطلبات الأساسية لاستخدام هوية مدارة لإدارة واجهة برمجة التطبيقات.

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

استخدم API Management REST API مع نص الطلب التالي.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "adding a new logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<ClientID>"
    }
  }
}

Bicep

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

resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with user-assigned managed identity'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
      identityClientId: '<ClientID>'
    }
  }
}

ARM

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

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "resourceId": "<ApplicationInsightsResourceID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "<ClientID>"
    }
  }
}

تمكين تسجيل Application Insights لـ API

استخدم الخطوات التالية لتمكين تسجيل Application Insights لواجهة برمجة التطبيقات. يمكنك أيضا تمكين تسجيل Application Insights لجميع واجهات برمجة التطبيقات.

1. انتقل إلى مثيل خدمة Azure API Management في مدخل Microsoft Azure.

2. حدّد APIs من القائمة على اليمين.

3. انقر فوق API، في هذه الحالة Demo Conference API. إذا تم تكوينه، فحدد إصداراً.

   تلميح

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

4. انتقل إلى علامة التبويب Settings من الشريط العلوي.

5. مرر لأسفل إلى قسم Diagnostics Logs.
   

6. حدد المربع Enable.

7. حدد المسجل المرفق في القائمة المنسدلة Destination.

8. إدخال 100 كأنها عينة (٪) وحدد مربع Always log errors.

9. اترك بقية الإعدادات كما هي. للحصول على تفاصيل حول الإعدادات، راجع مرجع إعدادات سجلات التشخيص.

   تحذير

   تجاوز عدد وحدات البايت الحمولة الافتراضية لتسجيل قيمة 0 قد يقلل بشكل ملحوظ من أداء APIs.

10. حدد حفظ.

11. خلف الكواليس، يتم إنشاء اسم كيان تشخيصapplicationinsights على مستوى API.

إشعار

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

المسجلات لواجهة برمجة تطبيقات واحدة أو جميع واجهات برمجة التطبيقات

يمكنك تحديد المسجلين على مستويات مختلفة:

• مسجل API واحد
• مسجل لجميع واجهات برمجة التطبيقات

تحديد كليهما:

• بشكل افتراضي، يتجاوز مسجل API واحد (مستوى أكثر دقة) واحد لجميع واجهات برمجة التطبيقات.
• إذا كانت المسجلات المكونة على المستويين مختلفة، وكنت بحاجة إلى أن يتلقى كلا المسجلين بيانات تتبع الاستخدام (تعدد الإرسال)، يرجى الاتصال بدعم Microsoft. يرجى ملاحظة أن تعدد الإرسال غير مدعوم إذا كنت تستخدم نفس المسجل (وجهة Application Insights) على مستوى "جميع واجهات برمجة التطبيقات" ومستوى API واحد. لكي يعمل تعدد الإرسال بشكل صحيح، يجب تكوين مسجلات مختلفة على مستوى "جميع واجهات برمجة التطبيقات" وواجهة برمجة التطبيقات الفردية وطلب المساعدة من دعم Microsoft لتمكين تعدد الإرسال للخدمة.

ما هي البيانات التي تتم إضافتها إلى Application Insights

يتلقى Application Insights:

عنصر بيانات تتبع الاستخدام	‏‏الوصف
Request	لكل طلب وارد: طلب الواجهة الأمامية استجابة الواجهة الأمامية
التبعيه	لكل طلب تتم إعادة توجيهه إلى خدمة خلفية: طلب الواجهة الخلفية استجابة الواجهة الخلفية
استثناء	لكل طلب فاشل: فشل بسبب اتصال عميل مغلق تشغيل قسم خطأ بنهج API به كود حالة HTTP للاستجابة تطابق 4xx أو 5xx
Trace	إذا قمت بتكوين نهج تتبع. severityيجب أن يكون الإعداد في النهج trace مساوياً أو أكبر من الإعداد في verbosity تسجيل Application Insights.

إشعار

راجع حدود Application Insights للحصول على معلومات حول الحد الأقصى لحجم وعدد المقاييس والأحداث لكل مثيل Application Insights.

إرسال قياسات مخصصة

يمكنك إرسال مقاييس مخصصة إلى Application Insights من مثيل APIM. تصدر APIM مقاييس مخصصة باستخدام نهج المقاييس المنبعثة.

إشعار

المقاييس المخصصة هي ميزة معاينة من Azure Monitor وتخضع للقيود.

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

1. تمكين المقاييس المخصصة (معاينة) ذات الأبعاد المخصصة في مثيل Application Insights.

   1. انتقل إلى مثيل Application Insights في المدخل.
   2. في القائمة اليسرى، حدد Usage and estimated costs.
   3. حدد Custom metrics (Preview)>With dimensions.
   4. حدد موافق.

2. أضف الخاصية "metrics": trueapplicationInsights إلى كيان التشخيص الذي تم تكوينه في APIM. حاليا يجب إضافة هذه الخاصية باستخدام تشخيص إدارة واجهة برمجة التطبيقات - إنشاء أو تحديث REST API. على سبيل المثال:

   PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights
   
   {
       [...]
       {
       "properties": {
           "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}",
           "metrics": true
           [...]
       }
   }
   

3. تأكد من تكوين مسجل Application Insights في النطاق الذي تنوي إصدار مقاييس مخصصة (إما جميع واجهات برمجة التطبيقات أو واجهة برمجة تطبيقات واحدة). لمزيد من المعلومات، راجع تمكين تسجيل Application Insights لواجهة برمجة التطبيقات الخاصة بك، في وقت سابق من هذه المقالة.

4. تكوين النهج emit-metric في نطاق حيث يتم تكوين تسجيل Application Insights (إما جميع واجهات برمجة التطبيقات أو واجهة برمجة تطبيقات واحدة) ويتم تمكينه للمقاييس المخصصة. للحصول على تفاصيل النهج، راجع مرجع النهج emit-metric .

حدود المقاييس المخصصة

يفرض Azure Monitor حدود استخدام للمقاييس المخصصة التي قد تؤثر على قدرتك على إصدار مقاييس من APIM. على سبيل المثال، يعين Azure Monitor حاليا حدا قدره 10 مفاتيح أبعاد لكل مقياس، وحدود 50000 سلسلة زمنية نشطة إجمالية لكل منطقة في اشتراك (خلال فترة 12 ساعة).

هذه الحدود لها الآثار التالية لتكوين المقاييس المخصصة في APIM:

• يمكنك تكوين 10 أبعاد مخصصة كحد أقصى لكل emit-metric نهج.

• عدد السلاسل الزمنية النشطة التي تم إنشاؤها بواسطة emit-metric النهج خلال فترة 12 ساعة هو نتاج عدد القيم الفريدة لكل بعد تم تكوينه خلال الفترة. على سبيل المثال، إذا تم تكوين ثلاثة أبعاد مخصصة في النهج، وكان لكل بعد 10 قيم محتملة خلال الفترة، emit-metric فإن النهج سيساهم بسلسلة زمنية نشطة 1000 (10 × 10 × 10).

• إذا قمت بتكوين النهج emit-metric في مثيلات APIM متعددة موجودة في نفس المنطقة في اشتراك، يمكن لجميع المثيلات المساهمة في حد السلاسل الزمنية النشطة الإقليمية.

آثار الأداء وأخذ عينات السجل

تحذير

تسجيل جميع الأحداث قد يكون له آثار خطيرة على الأداء، اعتماداً على معدل الطلبات الواردة.

استناداً إلى اختبارات التحميل الداخلية، تسبب تمكين ميزة التسجيل في انخفاض الإنتاجية بنسبة 40٪-50٪ عندما تجاوز معدل الطلب 1000 طلب في الثانية. تم تصميم Application Insights لتقييم أداء التطبيق باستخدام التحليل الإحصائي. إنه ليس:

• مُعد ليكون نظام تدقيق.
• مناسب لتسجيل كل طلب فردي لـ API عالي الحجم.

يمكنك معالجة عدد الطلبات المسجلة عن طريق ضبط إعداد أخذ العينات. تعني القيمة 100٪ أن جميع الطلبات قد تم تسجيلها، بينما لا تعكس 0٪ أي تسجيل.

يساعد أخذ العينات على تقليل حجم بيانات تتبع الاستخدام، ما يمنع بشكل فعال تدهور الأداء بشكل كبير مع الاستمرار في تنفيذ مزايا التسجيل.

لتحسين مشكلات الأداء، تخطي:

• عناوين الطلب والاستجابات.
• تسجيل النص.

فيديو

استكشاف الأخطاء وإصلاحها

معالجة مشكلة تدفق بيانات تتبع الاستخدام من APIM إلى Application Insights:

• تحقق من وجود مورد Azure Monitor Private Link Scope (AMPLS) مرتبط داخل VNet حيث يتم توصيل مورد API Management. موارد AMPLS لها نطاق عمومي عبر الاشتراكات وهي مسؤولة عن إدارة استعلام البيانات واستيعاب جميع موارد Azure Monitor. من الممكن أن تكون AMPLS مع وضع وصول خاص فقط خصيصا لاستيعاب البيانات. في مثل هذه الحالات، قم بتضمين مورد Application Insights ومورد Log Analytics المرتبط به في AMPLS. بمجرد إجراء هذه الإضافة، سيتم استيعاب بيانات APIM بنجاح في مورد Application Insights، وحل مشكلة نقل بيانات القياس عن بعد.

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

• تعرّف على المزيد حول Azure Application Insights.
• فكر في تسجيل الدخول باستخدام مراكز أحداث Azure.
• تعرف على تصور البيانات من Application Insights باستخدام Azure Managed Grafana