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

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

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

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

إشعار

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

تحذير

عند استخدام البوابة المستضافة ذاتيا، لا نضمن دفع جميع بيانات تتبع الاستخدام إلى Azure Application Insights نظرا لأنها تعتمد على التخزين المؤقت في الذاكرة ل Application Insights.

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

• تحتاج إلى مثيل 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 بتكوين مورد مسجل للاتصال.

   هام

   حاليا، في المدخل، تدعم APIM فقط الاتصالات ب Application Insights باستخدام مفتاح تقرير عن حالة النظام Application Insights. لتحسين الأمان، نوصي باستخدام سلسلة الاتصال Application Insights مع هوية مدارة من APIM. لتكوين سلسلة الاتصال باستخدام بيانات اعتماد الهوية المدارة، استخدم واجهة برمجة تطبيقات REST أو الأدوات ذات الصلة كما هو موضح في قسم لاحق من هذه المقالة. تعرف على المزيد حول سلسلة الاتصال Application Insights.

   إشعار

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

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

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

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

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

إشعار

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

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 Logger - إنشاء أو تحديث REST API مع نص الطلب التالي.

{
  "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"
    }
  }
}

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'
    }
  }
}

ذراع

قم بتضمين قصاصة برمجية 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 Logger - إنشاء أو تحديث REST API مع نص الطلب التالي.

{
  "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>"
    }
  }
}

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>'
    }
  }
}

ذراع

قم بتضمين قصاصة برمجية 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 في قسم Overview في مورد Application Insights.

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

استخدم API Management Logger - إنشاء أو تحديث REST API مع نص الطلب التالي.

إذا كنت تقوم بتكوين المسجل لمساحة عمل، فاستخدم Workspace Logger - Create أو Update REST API.

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

Bicep

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

إذا كنت تقوم بتكوين المسجل لمساحة عمل، قم بإنشاء Microsoft.ApiManagement/service.workspace/loggers@2023-09-01-preview مورد بدلا من ذلك.

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/;...'
    }
  }
}

ذراع

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

إذا كنت تقوم بتكوين المسجل لمساحة عمل، فقم Microsoft.ApiManagement/service.workspace/loggers بإنشاء مورد وتعيينه apiVersion إلى 2023-09-01-preview بدلا من ذلك.

{
  "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/;..."
    },
  }
}

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

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

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

2. حدد واجهات برمجة التطبيقات APIs> من القائمة على اليسار.

3. حدد واجهة برمجة تطبيقات، مثل Swagger Petstore. إذا تم تكوينه، فحدد إصداراً.

   تلميح

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

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:

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

إشعار

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

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

يمكنك إرسال مقاييس مخصصة إلى Application Insights من مثيل APIM. تصدر APIM مقاييس مخصصة باستخدام نهج مثل emit-metric وazure-openai-emit-token-metric. يستخدم القسم التالي النهج emit-metric كمثال.

إشعار

المقاييس المخصصة هي ميزة معاينة من 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 ساعة).

هذه الحدود لها الآثار التالية لتكوين مقاييس مخصصة في نهج إدارة واجهة برمجة التطبيقات مثل emit-metric أو azure-openai-emit-token-metric:

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

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

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

تعرف على المزيد حول قيود التصميم واعتبارات المقاييس المخصصة في Azure Monitor.

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

تحذير

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

استناداً إلى اختبارات التحميل الداخلية، تسبب تمكين ميزة التسجيل في انخفاض الإنتاجية بنسبة 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