معالجة عنوان IP وتحديد الموقع الجغرافي

توضح هذه المقالة كيفية عمل بحث الموقع الجغرافي ومعالجة عنوان IP في Application Insights، إلى جانب كيفية تعديل السلوك الافتراضي.

السلوك الافتراضي

بشكل افتراضي، يتم تجميع عناوين IP مؤقتاً ولكن لا يتم تخزينها في Application Insights. تتبع هذه العملية بعض الخطوات الأساسية.

عند إرسال بيانات تتبع الاستخدام إلى Azure، يستخدم Application Insights عنوان IP لإجراء بحث عن الموقع الجغرافي. يستخدم Application Insights نتائج هذا البحث لملء الحقول client_City وclient_StateOrProvince وclient_CountryOrRegion. يتم بعد ذلك تجاهل العنوان، وكتابة 0.0.0.0 في الحقل client_IP.

لإزالة بيانات الموقع الجغرافي، راجع المقالات التالية:

• إزالة أداة تهيئة IP للعميل
• استخدم أداة تهيئة مخصصة

أنواع بيانات تتبع الاستخدام هي:

• بيانات تتبع الاستخدام للمستعرض: يجمع Application Insights عنوان IP الخاص بالمرسل. تحسب نقطة نهاية الاستيعاب عنوان IP.
• بيانات تتبع الاستخدام للخادم: تجمع وحدة بيانات تتبع الاستخدام Application Insights عنوان IP للعميل مؤقتا. ولا يتم تجميع عنوان IP محلياً عند تعيين الرأس X-Forwarded-For. عندما تحتوي قائمة عناوين IP الواردة على أكثر من عنصر واحد، يتم استخدام عنوان IP الأخير لملء حقول الموقع الجغرافي.

هذا السلوك حسب التصميم للمساعدة في تجنب التجميع غير الضروري للبيانات الشخصية ومعلومات موقع عنوان IP. ونوصي بتجنب جمع البيانات الشخصية كلما أمكن.

ملاحظة

رغم أن الإعداد الافتراضي هو عدم جمع عناوين IP، إلا أنه يمكنك تجاوز هذا السلوك. نوصي بالتحقق من أن المجموعة لا تخالف أياً من متطلبات الامتثال أو اللوائح المحلية.

لمعرفة المزيد حول معالجة البيانات الشخصية في Application Insights، راجع إرشادات البيانات الشخصية.

عندما لا يتم جمع عناوين IP، لا يتم أيضا جمع سمات المدينة وغيرها من سمات الموقع الجغرافي التي يتم ملؤها بواسطة البنية الأساسية لبرنامج ربط العمليات التجارية باستخدام عنوان IP. يمكنك إخفاء مجموعة IP في المصدر. هناك طريقتان للقيام بذلك. يمكنك:

• قم بإزالة تهيئة IP للعميل. لمزيد من المعلومات، راجع التكوين باستخدام Applications Insights Configuration.
• قم بتوفير المهيئ المخصص الخاص بك. لمزيد من المعلومات، راجع مثال تصفية واجهة برمجة التطبيقات.

تخزين بيانات عنوان IP

لتمكين تجميع وتخزين IP، يجب تعيين خاصية DisableIpMasking لمكون Application Insights على true. يمكنك تعيين هذه الخاصية من خلال قوالب Azure Resource Manager (قوالب ARM) أو عن طريق استدعاء واجهة برمجة تطبيقات REST.

قالب ARM

{
       "id": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/microsoft.insights/components/<resource-name>",
       "name": "<resource-name>",
       "type": "microsoft.insights/components",
       "location": "westcentralus",
       "tags": {
              
       },
       "kind": "web",
       "properties": {
              "Application_Type": "web",
              "Flow_Type": "Redfield",
              "Request_Source": "IbizaAIExtension",
              // ...
              "DisableIpMasking": true
       }
}

المدخل

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

1. انتقل إلى مورد Application Insights، ثم حددقالب تصديرالتنفيذ التلقائي>.

2. حدد نشر.

   

3. ثم حدد قالب تعديل.

   

   ملاحظة

   إذا واجهت الخطأ الموضح في لقطة الشاشة السابقة، يمكنك حله. ينص على: "مجموعة الموارد في موقع لا يدعمه مورد واحد أو أكثر في القالب. Please choose a different resource group." حدد مجموعة موارد مختلفة مؤقتاً من القائمة المنسدلة ثم أعد تحديد مجموعة الموارد الأصلية.

4. في قالب JSON، حدد موقع properties داخل resources. أضف فاصلة إلى حقل JSON الأخير، ثم أضف السطر الجديد التالي: "DisableIpMasking": true. ثم اختر ⁧⁩حفظ⁧⁩.

   

5. حدد ⁧⁩Review + create⁦⁩⁧⁩⁧>⁩⁧Create⁩⁧⁩.

   ملاحظة

   إذا رأيت الرسالة "فشل النشر الخاص بك"، فابحث في تفاصيل النشر الخاصة بك للحصول على الرسالة من النوع microsoft.insights/components وتحقق من الحالة. إذا نجح ذلك، فقد تم نشر التغييرات التي تم إجراؤها على DisableIpMasking.

6. وبعد اكتمال عملية النشر، سيتم تسجيل بيانات تتبع الاستخدام الجديدة.

   إذا قمت بتحديد القالب وتحريره مرة أخرى، فسترى القالب الافتراضي فقط بدون الخاصية المضافة حديثاً. إذا كنت لا تجد بيانات عنوان IP وتريد تأكيد تعيين "DisableIpMasking": true، فقم بتشغيل أوامر PowerShell التالية:

   # Replace `Fabrikam-dev` with the appropriate resource and resource group name.
   # If you aren't using Azure Cloud Shell, you need to connect to your Azure account
   # Connect-AzAccount 
   $AppInsights = Get-AzResource -Name 'Fabrikam-dev' -ResourceType 'microsoft.insights/components' -ResourceGroupName 'Fabrikam-dev'
   $AppInsights.Properties
   

   يتم إرجاع قائمة من الخصائص نتيجة لذلك. يجب أن تقرأ إحدى الخصائص DisableIpMasking: true. إذا قمت بتشغيل أوامر PowerShell قبل نشر الخاصية الجديدة باستخدام Azure Resource Manager، فلن تكون الخاصية موجودة.

REST API

تقوم حمولة واجهة برمجة تطبيقات REST التالية بإجراء نفس التعديلات:

PATCH https://management.azure.com/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/microsoft.insights/components/<resource-name>?api-version=2018-05-01-preview HTTP/1.1
Host: management.azure.com
Authorization: AUTH_TOKEN
Content-Type: application/json
Content-Length: 54

{
       "location": "<resource location>",
       "kind": "web",
       "properties": {
              "Application_Type": "web",
              "DisableIpMasking": true
       }
}

PowerShell

يمكن ل PoweShell 'Update-AzApplicationInsights' cmdlet تعطيل إخفاء IP باستخدام المعلمة DisableIPMasking .

Update-AzApplicationInsights -Name "aiName" -ResourceGroupName "rgName" -DisableIPMasking:$true

لمزيد من المعلومات حول cmdlet 'Update-AzApplicationInsights'، راجع Update-AzApplicationInsights

مُهيئ بيانات تتبع الاستخدام

إذا كنت بحاجة إلى بديل أكثر مرونة من DisableIpMasking، فيمكنك استخدام مُهيئ بيانات تتبع الاستخدام لنسخ عنوان IP بالكامل أو جزء منه إلى حقل مخصص. التعليمات البرمجية لهذه الفئة هي نفسها عبر إصدارات .NET.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

namespace MyWebApp
{
    public class CloneIPAddress : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            ISupportProperties propTelemetry = telemetry as ISupportProperties;

            if (propTelemetry !=null && !propTelemetry.Properties.ContainsKey("client-ip"))
            {
                string clientIPValue = telemetry.Context.Location.Ip;
                propTelemetry.Properties.Add("client-ip", clientIPValue);
            }
        }
    } 
}

ملاحظة

إذا لم تتمكن من الوصول إلى ISupportProperties، فتأكد من تشغيل أحدث إصدار مستقر من Application Insights SDK. ويكون ISupportProperties مخصص للقيم الأساسية العالية. ويكون GlobalProperties أكثر ملاءمة للقيم المنخفضة للعناصر الأساسية مثل اسم المنطقة واسم البيئة.

.NET 6.0+

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

builder.services.AddSingleton<ITelemetryInitializer, CloneIPAddress>();

⁩.NET 5.0⁧

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, CloneIPAddress>();
}

إطار عمل ASP.NET

using Microsoft.ApplicationInsights.Extensibility;

namespace MyWebApp
{
    public class MvcApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
              //Enable your telemetry initializer:
              TelemetryConfiguration.Active.TelemetryInitializers.Add(new CloneIPAddress());
        }
    }
}

Node.js

Node.js

appInsights.defaultClient.addTelemetryProcessor((envelope) => {
    const baseData = envelope.data.baseData;
    if (appInsights.Contracts.domainSupportsProperties(baseData)) {
        const ipAddress = envelope.tags[appInsights.defaultClient.context.keys.locationIp];
        if (ipAddress) {
            baseData.properties["client-ip"] = ipAddress;
        }
    }
});

JavaScript من جانب العميل

JavaScript من جانب العميل

على عكس SDK من جانب الخادم، لا تحسب JavaScript SDK من جانب العميل عنوان IP. بشكل افتراضي، يحدث حساب عنوان IP لبيانات تتبع الاستخدام من جانب العميل عند نقطة نهاية الاستيعاب في Azure.

إذا كنت تريد حساب عنوان IP مباشرة على جانب العميل، تحتاج إلى إضافة منطق مخصص واستخدام النتيجة لتعيين العلامة ai.location.ip. عند تعيين ai.location.ip، لا تقوم نقطة نهاية الاستيعاب بحساب عنوان IP، ويتم استخدام عنوان IP المقدم في البحث عن الموقع الجغرافي. في هذا السيناريو، لا يزال عنوان IP صفرياً بشكل افتراضي.

للاحتفاظ بعنوان IP بالكامل محسوباً من منطقك المخصص، يمكنك استخدام مُهيئ بيانات تتبع الاستخدام الذي يقوم بنسخ بيانات عنوان IP التي قدمتها في ai.location.ip إلى حقل مخصص منفصل. ولكن مرة أخرى، على عكس SDK من جانب الخادم، لن تحسب SDK من جانب العميل العنوان نيابةً عنك إذا لم تتمكن من الاعتماد على مكتبات الجهات الأخرى أو على منطقك المخصص.

appInsights.addTelemetryInitializer((item) => {
    const ipAddress = item.tags && item.tags["ai.location.ip"];
    if (ipAddress) {
        item.baseData.properties = {
            ...item.baseData.properties,
            "client-ip": ipAddress
        };
    }
});

إذا اجتازت البيانات من جانب العميل وكيلاً قبل إعادة التوجيه إلى نقطة نهاية الاستيعاب، فقد يُظهر حساب عنوان IP عنوان IP الخاص بالوكيل وليس العميل.

عرض نتائج مُهيئ بيانات تتبع الاستخدام

إذا قمت بإرسال نسبة استخدام جديدة للشبكة إلى موقعك وانتظرت بضع دقائق، يمكنك بعد ذلك تشغيل استعلام لتأكيد عمل المجموعة:

requests
| where timestamp > ago(1h) 
| project appName, operation_Name, url, resultCode, client_IP, customDimensions.["client-ip"]

ستظهر عناوين IP التي تم جمعها حديثاً في العمود customDimensions_client-ip. سيظل العمود الافتراضي client-ip يحتوي على جميع البتات الأربعة صفرية.

ذا كنت تجري الاختبار من localhost، وكانت قيمة customDimensions_client-ip هي ::1، فهذه القيمة هي السلوك المتوقع. تمثل قيمة ::1 عنوان الاسترجاع في IPv6. إنها مكافئة لـ 127.0.0.1 في IPv4.

الأسئلة المتداولة

يقدم هذا القسم إجابات للأسئلة الشائعة.

كيف يتم حساب بيانات المدينة والبلد/المنطقة وغيرها من بيانات الموقع الجغرافي؟

نبحث عن عنوان IP (IPv4 أو IPv6) لعميل الويب:

• قياس المتصفح عن بُعد: نجمع عنوان IP الخاص بالمرسل.
• القياس عن بُعد للخادم: وحدة Application Insights تقوم بتجميع عنوان IP العميل. لا يتم جمعه إذا X-Forwarded-For تم تعيينه.
• لمعرفة المزيد حول كيفية جمع عنوان IP وبيانات الموقع الجغرافي في Application Insights، راجع الموقع الجغرافي ومعالجة عنوان IP.

يمكنك التكوين ClientIpHeaderTelemetryInitializer لأخذ عنوان IP من عنوان مختلف. في بعض الأنظمة، على سبيل المثال، يتم نقله بواسطة وكيل أو موازن تحميل أو CDN إلى X-Originating-IP. تعرَّف على المزيد.

يمكنك استخدام Power BI لعرض بيانات تتبع الاستخدام للطلب على خريطة إذا قمت بالترحيل إلى مورد يستند إلى مساحة العمل.

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

• تعرف على المزيد حول جمع البيانات الشخصية في Application Insights.
• تعرف على المزيد حول كيفية عمل مجموعة عناوين IP في Application Insights. هذه المقالة هي منشور مدونة خارجي أقدم كتبه أحد مهندسينا. إنه يسبق السلوك الافتراضي الحالي حيث يتم تسجيل عنوان IP ك 0.0.0.0. تتناول المقالة المزيد من التعمق في آليات مهيئ القياس عن بعد المدمج.